View Single Post
Old 09-05-2006, 01:02 PM   #201
Mostly dormant
stoffe's Avatar
Status: Administrator
Join Date: Apr 2002
Posts: 5,850
Helpful!  10 year veteran!  Notable contributor 
Here is another "quick how-to" guide for how the TSLPatcher could be used to accomplish certain modding tasks. Hopefully these examples will make it a bit clearer how things fit together.

* * *

New Player Appearance Mod:
To use TSLPatcher to install a mod adding a new player appearance to the game you'd roughly follow these steps. This assumes that you have already added the new lines required to appearance.2da, heads.2da and portraits.2da and created your textures and models. This is not a guide for how you create a new player appearance mod, only for how you could make an installer for such a mod.

ChangeEdit main window
  1. Create a folder to contain your mod and copy TSLPatcher.exe to this folder. You may rename the EXE file to something more intuitive if you wish, like "Install Mod.exe" or whatever you like.

  2. Create a new folder inside this folder alongside the TSLPatcher.exe, name it exactly tslpatchdata. Copy the models, textures and any other files belonging to your mod into this folder, except any 2DA files used.

  3. Use KotorTool to extract unaltered copies of the files appearance.2da, heads.2da and portraits.2da. Put these 2DA files inside the tslpatchdata folder as well.

  4. Start ChangeEdit.exe and chose New... from the File menu to create a new config file. Save the file as changes.ini inside your tslpatchdata folder.

  5. The Settings panel will open. In the Window caption input box, type in the name of your mod. If you want a confirmation dialog box to pop up before the installation begins when the user presses the Install mod button, type in the warning text in the Confirm message input box, or set it to N/A to prevent the box from showing.

    Make sure Run mode is set to Installer. If you want TSLPatcher to automatically locate the folder where the game is installed, set the Ask for game folder dropdown menu to Look up folder path in the Windows registry, and select which game your mod is for. If you use automatic game lookup you should probably use a confirm message as mentioned previously. If you pick Ask the user to select folder location an Open dialog box will show when installation starts to let the user select where to install.

    For debugging purposes you should leave it at Ask the user... for now, and set the Log level dropdown menu to 4. Press the Save changes button to save your settings to the config file.

  6. Next, select the 2DA Files section in the treeview to the left, right-click on it and pick Add 2da file... in the context menu. In the box that opens, either type in heads.2da, or press the icon to the right of the input field to browse to the file if you are afraid of typos. Press OK, and the file should be added to the treeview. Select it to view its 2DA Modifications panel.

  7. Since you have already made the necessary 2DA modifications with KotorTool or another 2DA editor, let's make use of those. Click the Compare button above the modifier list. It's the one with a finger pointing at a red blob. This will allow ChangeEdit to compare two 2DA files and automatically create modifiers for the found differences for you.

    In the first Open dialog box that opens, select the unaltered heads.2da file you saved in the tslpatchdata folder. This is what your changes will be compared against to figure out what has been modified.

    In the next Open dialog box, select the heads.2da file that has been modified for your mod. Please wait while ChangeEdit works, depending on the size of your 2DA files and how much you have changed it may take a while for it to finish working. A confirmation box will pop up once it is done.

  8. If your mod adds just one new player appearance, ChangeEdit should now have found your new line and created an "AddRow" modifier for it. Doubleclick this modifier in the list to open its editing window.

    In the Label of Exclusive column dropdown menu, select head. (If there is no content in the dropdown menu you can click the icon to the right of the input box to load the column labels from a 2da file manually.) This will instruct the TSLPatcher to only add this new line if there isn't already another line in heads.2da that has the same value as this new line in the head column. If there is, no new line will be added, and the existing line will be updated instead to match the values of this AddRow modifier. This is used to prevent duplicate lines from being added to the 2DAs if the installer is run more than once.

    Next you will need to store the line number of this new line, so it can be properly referred to from appearance.2da's normalhead column.

    Temporarily storing values in TSLPatcher is done using the (poorly named) 2DAMEMORY tokens. Think of the 2DAMEMORY tokens as a series of storage containers with numeric labels stuck to them to tell them apart. 2DAMEMORY token labels are defined as 2DAMEMORY1, 2DAMEMORY2, 2DAMEMORY3 etc up to as many as you need.

    Working with 2DA files a 2DAMEMORY token can keep track of the line number (RowIndex) of the current line, the Row Label (RowLabel) of the current line, or the value of any column on the current line (by assigning the column label to the token).

    Anyway, in this case we want to keep track of the line number. Still in the Add 2DA Line editor window, select the Column input box under the Set column value section. 2DAMEMORY tokens don't show up in the dropdown menu, so you'll have to type them in by hand. Type in 2DAMEMORY1 in the Column input box. Next, select the Value input box below it and type in RowIndex.

    Click on the button with the right-pointing red arrow to add the token to the Column values list to the right, then close the editor window. This will save the line number of your new line in the 2DAMEMORY1 token. You will need this soon when setting up appearance.2da.

  9. Select the 2DA Files section in the treeview again, right-click and pick Add 2da file... in the context menu. Type in or select appearance.2da. Just like you did for heads.2da, select the file in the treeview and click the Compare button above the modifier list. First select the unaltered appearance.2da file from your tslpatchdata folder, then select the appearance.2da file modified for your mod. Let ChangeEdit do the work the create the necessary modifiers.

  10. If you've followed the standard procedure of adding a separate appearance for the Guardian, Sentinel and Consular starting classes (or Soldier/Scout/Scoundrel if it's for Kotor 1) three new modifiers should have been created to instruct TSLPatcher how to add your three new lines to the 2DA file. Doubleclick on the first one to open its editing window.

  11. Set the Label of exclusive column dropdown menu to label, to use the label column to prevent duplicates. Make sure your new lines have unique labels if you have copy&pasted existing lines when you added them.

    Next locate the normalhead column in the New column values list to the right and double-click it to load it into the Set column value fields to the left. Drop down the menu of the Value field and you should find 2DAMEMORY1, the token you just assigned in the heads.2da section, in the menu. Select it and press the right-pointing red arrow button to save the changes to the normalhead value. This will ensure that the correct line number from heads.2da is used, no matter what other custom lines may already exist in that file.

    Further we need to save the line number of this new appearance.2da line as well, so it can be properly assigned in the portraits.2da file. In the Add column value Column field, type in 2DAMEMORY2 and in the Value box type in RowIndex and press the red right-arrow button to save. Close the editor window. Note the new numerical label used, we want to save the line number in a separate token (number 2) and not overwrite the heads.2da line number in token number 1.

  12. Repeat the previous stage for the two other appearance.2da modifiers. Take care to assign 2DAMEMORY1 to the normalhead column for each, and to save their line numbers in a new 2DAMEMORY token (2DAMEMORY2, 2DAMEMORY3 and 2DAMEMORY4 respectively).

  13. Memory refresher: TSLPatcher is now keeping track of 4 values for us, stored something like:
    2DAMEMORY1 - line number of new row added to heads.2da
    2DAMEMORY2 - line number of new row for Consular/Scoundrel in appearance.2da
    2DAMEMORY3 - line number for new row for Sentinel/Scout in appearance.2da
    2DAMEMORY4 - line number for new row for Guardian/Soldier in appearance.2da

  14. Add portraits.2da to the 2DA Files section like before, and compare the unaltered version against your modded one to create modifiers. If you added one new player appearance, one new modifier should have been generated. Doubleclick it to open the editor.

  15. Set the Exclusive column to baseresref to prevent duplicates, then find the columns appearancenumber, appearance_s and appearance_l in the column value list to the right. These columns refer to your new appearance.2da lines. Assign the values kept in the 2DAMEMORY tokens to them, assuming the above order it would be like:
    appearancenumber = 2DAMEMORY3
    appearance_s = 2DAMEMORY2
    appearance_l= 2DAMEMORY4
    Save and close the window.

  16. That should take care of the mod compatibility parts, letting your mod play nice with most other mods that modify those same three 2DA files. Next we'll get the other files that don't need any editing to where they should be. Click on the Install Files section in the treeview. From here you can instruct TSLPatcher to copy files from the tslpatchdata into any folder, ERF or RIM file within the game folder. In this case we simply want to move the texture and model files into the override folder.

  17. Click the Add multiple files button below the file list. It's the one that looks like a stack of documents next to the arrow buttons. This opens a window where you can either type in the name of a folder, or select a folder to get the name of with a standard Open dialog box (to reduce the risk of typos). Type in override in this box and check the Replace existing files in folder to instruct the TSLPatcher to overwrite any files in override that are named the same as your files. (They will be copied to the backup folder before being overwritten.)

    Click the Select button and a standard Open dialog box will open. Hold down the SHIFT/CTRL keys on your keyboard as needed to select multiple files, select your textures and models in the tslpatchdata folder and press Open to add the to the file list.

    Important: Do not add any files added to the 2DA Files, GFF Files, Soundset Files or Script source sections to the install list! Those files will be put in their proper place already when the TSLPatcher modifies them.

    Exit ChangeEdit, your config file should now be functional.

  18. Open up WordPad (comes with Windows) and create a new RTF (Rich Text Format) document. Name this file info.rtf and save it in the tslpatchdata folder. The content of this file is the text that will be shown in the main TSLPatcher window when the installer is started, before the user presses the Install Mod button. Put whatever you like in this file, for example a readme file, or special installation instructions.

  19. Create a new folder somewhere and copy the dialog.tlk file from your game into it. Also create an override folder inside this folder. This folder can now be used as a fake game folder, allowing you to test that your installer has been properly configured without having to risk messing with your game.

    Run your installer and keep an eye on the progress log for any warnings or errors being logged, indicating that something is improperly configured or some files are missing.

  20. When everything installs without any errors, start ChangeEdit again, open your changes.ini config file, go to the Settings section and change the Log Level back to 3 to hide the debug output in the progress log. If you wish you can also set it to automatically look up the game folder in the windows registry now.

The purpose of doing things like this is to improve chances of making your mod compatible with other mods that also have modified 2DA files that the prospective mod user might have installed in their game. When set up like this TSLPatcher will not overwrite any existing 2DA files found in the game. It will rather make changes to those 2DA files, preserving any changes and additions made by other mods.

The reason you include unaltered copies of the 2DA files in the tslpatchdata folder is for when the mod user do not already have any of those 2DA files in their override folder. In those cases TSLPatcher will first copy the missing 2DA file to the override folder, and then apply the instructed changes as usual.

Remember that the order you add the 2DA files is important, since you must have your heads.2da line before you can refer to it in appearance.2da, and you must have your appearance.2da lines already before you can refer to them in portraits.2da. Modifiers must be added in the order they are to be carried out when the TSLPatcher installs the mod.

Last edited by stoffe -mkb-; 09-05-2006 at 01:13 PM.
stoffe is offline   you may: quote & reply,