You are here

UPD file format

UPD is a file format designed to help with merging 2da flles. This is a file format created for use with Never Launcher and not a game format.

It offers a language to describe DIFFS between 2 2da files, generally the difference between a customized file and the official version from the same patch that the customized version used. However those using common content like kaedrins, PRC or CEP as a base, would have a diff a between THEIR changes and the content they originally started from.

It has the ability to Run as a script, quickly applying the specified 2da diff to another version of the same 2da file. Multiple UPD files can be run on the same 2da files, thus merging lots of content into one, with much less issues.

It does not deal with row conflicts, authors have to respect reserved ranges, and those hitting run should read and inspect the UPD file.

It is designed to be used in a SVN or GIT repository, and be easily read and edited via a simple text editor.

Syntax is as follows:

UPD Script Commands

Syntax is very simple, and is basically composed of commands, followed by a colon and then parameters. This file when opened with NeverLauncher will automatically apply the given changes to an open 2da file, or can be used to reassemble a 2da. By design it is supposed to be easy to read, as many modders prefer to do all edits themselves.
Comment, descriptive information describing what the modification is for.
Use: <full2dafilename>
Sets the active 2da to use, if it's open currently it uses that file, if not it opens the vanilla 2da.
A variable storing the current row pointer - makes it easier to move a row to another row by just editing one value per row.
SetRow: <integer>
sets currow to given integer 
adds a new row and sets currow to the result
AddColumn: <columnname>
Adds a new column of the given name
Set: <rowid>, <columnname> to <string>
Set: currow, <columnname> to <string>
Set a value for a given row and column
SetBit: <rowid>, <columnname> with <bit> to <0|1>
SetBit: currow, <columnname> with <bit> to <0|1>
Set the bit for a given row and columns value - keeps all other bits as is - saves value in 0xFF format ( 0x3E )
<bit> = value from 1 to 8, representing the 1st to 8th bit, setting the first bit to 1 would be 0x01, setting the second bit to 1 would be 0x02, if the original value is 0x00. Setting the 1st bit to 0 with an original value of 0x03 would make the value 0x02.
( look at the above for setting a single bit initially, but also look at bitwise math so it does an OR to merge, and a XOR to subtract )
For those not versed in bitwise math
hex   -  binary
0x00  = 00
0x01 = 01
0x02 = 10
0x03 = 11
The above is hexadecimal values, but it's works the same as decimal for such low numbers. Setting the bit means working with the raw binary number, setting the value to 1 or 0 directly, without affecting anything else. The resulting number you see is actually in hexadecimal. ( first bit is on the far right, and each bit goes one place over to the left ). You don't have to really know any of this, just know that if the TargetType description for spells.2da on nwn2wiki says the first bit determines if you can target self, then you'd just set that bit to turn that feature on or off for the particular spell.
SetCustomVal: <rowid>, <columnname> to <string>
SetCustomVal: currow, <columnname> to <string>
Special command which dynamically sets custom tlk reference values, works just like set in every other way but varies the value based on if end user is creating a dialog.tlk or a custom tlk.
Uses for this could be removal of scroll use as a option in spells.2da, or making a particular spell like divine power persistent.
FillColumn: <columnname> to <string>
Sets all values in the given column to the given value. Note this affects both padding rows and rows with actual data, but it won't add a row. Primarily designed to remove the strref column from placeables.2da so the labels used in that file are visible in the toolset.
Fixes all the row numbers involved to be correct.
Pad: <lastrownumber>
Add enough rows to make the 2da have values up to this row, ( is not required )
Void: <rownumber>
Voids a particular row in the 2da
Flag: <flag>
This sets a flag
if: <flag>
    other commands
<flag> is to match the above flag and whatever is between if: and fi: are only run if the given flag is set. Other flags such as ALPHA and BETA will be defined so they apply via checkboxes. This should allow new features to be developed, and surrounded with the if construct and only deployed to the live server after the leave beta.
Technically this could allow content to be dependent on if something else is installed as well. At least initially this is not set up to be recursive, an if cannot be inside another if basically.
// The following are planned additions which are not yet implemented
Compile <foldername|filename>
<foldername> being somewhat relative
// this is speculative, but need to figure out if something like this would work
Replace <foldername|filename> <regularexpression>
append <foldername|filename> <string>
A UPD file is automatatically generated by DIFFing in Never Launcher
First install never launcher
  1. First download this Never Launcher (53)
  2. Then extract the application and open the exe in the folder. It's self contained, your prefs go into a text file where apps should save them per your OS, and the rest never leaves it's folder so you can just delete it when you are done.
Second, generate a upd file
  1. Click "Build - Toolset" button on the main screen, or select the "Build" menu item in the file menu.
  2. Click "Open File" 
  3. Navigate to the 2da file with the modifications you want.  ( technically you can drag the 2da file on the Neverlauncher app as well)
  4. Wait while it opens the file ... can take a while as it's designed to open even the most corrupt 2da file and is reading every cell into memory up front. ( I am opening the combined 2da which is just plain huge anyway so you might have to be patient - if it shows a dialog with an number that is me trying to figure out how to speed it up by showing the ticks spent, not sure if that is showing in the released version )
  5. Using the Compare Menu, select NWN21.23.1765XP2 and wait a bit for this to process ( should be pretty fast )
  6. Using the Compare Menu, select Extract Diff
  7. This creates a diff file, with ALL the differences set up as a script.
  8. Close the placeables.2da
  9. Save the UPD files created for future use, or just leave it open. This syntax should be simple enough to review, so any extraneous lines, or anything you don't like can be reviewed. ( very hard to sneak any changes you don't know about using this system )
  10. Repeat on all the 2da's you want to use, i save these so later on when i do more merging i can keep track of where each change came from.
Third Run the UPD script to Create a combined placeables.2da
  1. Open the UPD file ( just like you did placeables.2da )
  2. The UPD editor has 2 options, first is "Open Files" which makes it target an open file, the other is "NWN21.23.1765XP2" which opens the vanilla 2da file provided ( this is based on the installed versions available, shown is 1.23 for NWN2 ). If you use open files, make sure you have just one placeables.2da open on which to run the script.
  3. Click run ( it runs very fast, you might want to scroll down to the lines it's going to edit just to see it happen )
  4. Repeat for all the upd files you want to use, yes this is all merged ( This was used by me to do the combined 2da which has just about all the NWN2 placeables in it ) Note this will not deal with conflicts, but you can just edit the number in the script.
  5. Save the placeables.2da file ( there is a preference to choose tab or space delimited, both work fine in NWN2, NWN1 requires space delimited, excel prefers tab delimited.

This is a fundamental part of the system to allow multiple projects to automatically install together in an automated fashion, without having to manually set up every project on the vault. UPD files can easily be extracted assuming we have the 2da from the patch indicated by the project, and this system eliminates issues with both version and merging as long as the 2da changes do not target the same rows. Authors can further use this system to enable more control to this process.


First Release: 
  • up
  • down