[named ]. can be one of "mellow" or "upset". In the uw_demo, the 0cXX blocks and many of the conversation string blocks aren't available. +--------------------------------------------------------------------------+ 6 Objects and items This chapter contains information about the objects in Ultima Underworld. Objects (or items) are grouped by type. Here's a short overview of all object groups: 0000-001f Weapons and missiles 0020-003f Armour and clothing 0040-007f Monsters 0080-008f Containers 0090-0097 Light sources 0098-009f Wands 00a0-00af Treasure 00b0-00bf Comestibles 00c0-00df Scenery and junk 00e0-00ff Runes and bits of the Key of Infinity 0100-010f Keys, lockpick, lock 0110-011f Quest items 0120-012f Inventory items, misc stuff 0130-013f Books and scrolls 0140-014f Doors 0150-015f Furniture 0160-016f Pillar, some decals, force field, special tmap obj 0170-017f Switches 0180-019f Traps 01a0-01bf Triggers 01c0-01cf Explosions/splats, fountain, silver tree, moving things A description string for each object is stored in game strings block 0004 Object IDs are in the range 0x0000 to 0x01ff. The bits can be split up for classification purposes of different objects: bits 0..3 object number in subclass 4..5 object subclass 6..8 object class The object class groups together 0x0040 (64) items each. Here's a list of some classes: class item_id description 1 0040 npc's 6 0180 traps/triggers subclass 0/1: traps subclass 2: triggers 7 01c0 sprites, animated objects 6.1 List of all objects and items This chapter lists and describes all objects that are available in Ultima Underworld. Descriptions for obvious items are omitted. 000f a_fist this is not really an item, but is used for fist combat 002f a_pair of dragon skin boots player doesn't get hurt when walking on lava 0040..0x007e NPC's "sp_link" points to the inventory start 007f an_adventurer the player as object; isn't used ingame 008f a_rune bag looking at the bag shows the rune bag panel; available runes are stored in the savegame 0098 a_wand (and other wands) "sp_link" points to a_spell object 00c6 a_pile of bones the "owner" field determines from whom the bones are; strings are taken from block 4; a value of 63 means "an adventurer" 0100 a_key (and up to 010e) the key ID that is needed to unlock a door with an associated lock object is stored in the "owner" field. 010f a_lock the lock object is associated with a door or portcullis and determines the lock state and the lock ID. bit 9 of the flags indicates if the lock is locked (1) or unlocked (0). the lower 6 bits of the "link/special" field determines the lock ID. when unlocking a door with a key, the lock ID must match the key ID on the key. 0110 a_picture of Tom 0114 a_book the book explodes when the user tries to look at it; player takes damage. 0120 a_spell spell object used by wands, spell traps, magical items; the "quality" field 013b a_map the map is shown when looked at the map in inventory. The string at block 1, string 151 is printed, too. 0140 a_door (and up to 014f) if bit 1 of the "owner" field is set, the door is spiked. if the "sp_link" field points to a_lock object, the door is locked. 0146 is a portcullis and 0147 is a secret door. doors from 0148 to 014f are the open versions of the closed doors. the textures for the doors come from the 6 bytes at the end of the texture mapping info from lev.ark. 0160 a_pillar 3d object. texture is determined by the lower 2 bits of the "flags" field (?) 0161 a_lever a clock-like lever with 8 positions; texture is determined by the "flags" field (lower 3 bits) + 4, from "tmobj.gr". 0162 a_switch almost the same as 0161, but starting with image 12 of "tmobj.gr". not used in uw1 0164 a_bridge bridge 3d object. texture to use comes from "flags" field. when the value is < 2, the bridge texture is taken from "tmobj.gr", index 30 + flags. for this bridge, string block 0001, string 171 is printed as "look" description. when the "flags" value is > 2, flags-1 is used as index into the floor texture mapping, effectively using a floor texture. bridges could be use to alter the fixed ceiling height. 0165 a_gravestone 3d grave stone object (obj 0x13). text for gravestone is stored in strings block 0008, indexed by "quantity" - 0x200. the index also serves as offset into the file "grave.dat" which gives a unique grave id. It is used for large gravestone images that are stored in "cuts/cs401.n01", one frame each, indexed by the grave id. texture of the gravestone is image "flags" + 28 from "tmobj.gr". the text printed when looking at it is determined by the "flags" field. gravestone/tombstone description text is from strings block 0008, string 352 + flags. 0166 some_writing wall decal; text is determined through "quantity" field, game strings block 0008. the texture used is determined from "tmobj.gr", image "flags" + 20 (?). the plaque description printed when looking at it is determined by the "flags" field. text printed is from strings block 8, 368 + flags 0167 a_bed [uw2] The "owner" field determines the colour of the sheets and pillow. The sheets are colour (4*owner+5), the pillow colour (4*owner). 016e special tmap obj (tmap_c) wall decal; texture used is determined from the "owner" field and is an index into the texture mapping wall table. 016f special tmap obj (tmap_s) same as 016e, with the difference that the wall is recognized in collision detection, effectively providing thin walls that could be removed by deleting the object. 017x a_button, etc. buttons, switches, pull chains and levers, textured with images from "tmflat.gr". special link usually points to a trigger. 01c9 a_fountain 01ca a_silver tree [uw1] animated objects; "owner" field determines current animation overlay 01cf a_moving door object that is used during opening a door 6.1.2 Traps and Triggers Traps are set off by triggers, which are triggered by the player coming near them. Traps can also be set off by switches or buttons, etc. All triggers contain tilemap coords in "quality" and "owner" field called trigger "target" coordinates. All triggers also have the "special link" set that points to the trap(s) to set off. If a trap also has the "special link" field set, then another trap is set off, allowing trap chaining. 0180 a_damage trap player vitality is decreased; number of hit points are in "quality" field; if the "owner" field is != 0, the hit points are added instead. the trap is only set of when a random value [0..10] is >= 7. 0181 a_teleport trap teleports the player to another level and tile; destination level is given by "zpos" (0 means current level), tile x/y coordinates are given in "quality" and "owner" fields. 0182 a_arrow trap 0183 a_do trap [uw1] a multi-purpose trap. the "quality"-field determines action to perform: action description 02 03 05 18 bullfrog puzzle related; (special property is a link) if not in level 5 (where the puzzle is), the trap just prints "There is a pained whining sound.". "owner" defines some subcode: 00/01: lowers/raises tiles 02: increases x coord (?) (0..7) 03: increases y coord (?) (0..7) 04: resets bullfrog puzzle; prints "reset activated" 28 (special property is a link) 2a starts conversation (uw1 starts a hard-wired conv., slot 0x19, the speaking "Door" 32 39 (not used in uw1) 3c..3e (not used in uw1) 3f ends game, shows end sequence 0183 a_hack trap [uw2] 0184 a_pit trap [uw1] not implemented in uw1, but used on 3rd level, as target for a use trigger that is associated with a check variable trap (map bug?) this is probably a bottomless pit that drops the player through to the next level. 0184 a_special effects trap [uw2] this trap does 'visual' effects like earthquakes, or blurry vision. 0185 a_change terrain trap the trap changes one or more tiles, according to the encoded info. the trigger's target coordinates describe the starting tile. TODO 0186 a_spelltrap fields "quality" and "quantity" determine spell type. 0187 a_create object trap creates a new object using the object referenced by the "quantity" field as a template. the object is created only when a random number between 0 and 3f is greater than the "quality" field value. 0188 a_door trap opens or shuts a door when set off. the trigger "target" coords determine the tile with the door to open/close. if the door has an "a_lock" object associated, it is deleted. if there is no lock, a new lock is created, using the template lock linked to by the "sp_link" field. as the door points to a lock, there can't be another trigger associated with it. the "quality" value decides if a door trap only opens, closes or toggles doors. 1: try open 2: try close 3: toggle door state 0189 a_ward trap not used in uw1 018a a_tell trap [uw1] not used in uw1, implemented the same way as a ward trap 018a a_skill trap [uw2] 018b a_delete object trap deletes an object when set off. "owner" and "quality" of the trap determines tile the object is to be found, "sp_link" points to the object. 018c an_inventory trap the trap searches for an item in the inventory; when it is found, the sp_link'ed trigger is set off. the item_id is given by ("quality" << 5) | "owner". additionally, the zpos value must be != 0 to enable the trap. 018d a_set variable trap sets a game variable; fields "quality", "owner" and "ypos" are combined to form a "value" that is used as variable index later: field bits in value ypos 0..2 owner 3..7 (bit 5 of "owner" seems not to be used) quality 8..13 the "zpos" field determines which variable to set. if zpos is 0, a bit-field is modified and the index value indicates which bit to modify. the "heading" field determines the operation to perform: heading operation bit-field operation 0 add set bit 1 sub clear bit 2 set set bit 3 and set bit 4 or set bit 5 xor flip bit 6 shl set bit values are modified and kept in range 0..63 (0x3f). largest variable index in uw1 is 0x33, the only bit modified in uw1 is bit 7 of the bit field 018e a_check variable trap the "value" from the set variable trap (018d) is also used here. the trap checks a range of variables, starting from "zpos" and of length "heading". if "xpos" is not 0, the variable values in range are added; if it is 0, the lower 3 bits of every variable value are shifted into the resulting value. here's some meta-C code to show how the check works: bool check_variable_trap(zpos,heading,value) { Int16 cmp = 0; for(Int16 i=zpos; i ", with the exception of group D which is for armour items which are grammatically plural even if there is only one of the object, e.g. "leather leggings". 6.3 Object class properties Object properties specific to a range of objects are stored in the file "objects.dat". The file contains several tables. Here is an overview: pos size desc entries bytes per entry 0000 Int16 unknown, always 0x010f 0002 0x80 melee weapons table 16 8 bytes 0082 0x30 ranged weapons table 16 3 bytes 00b2 0x80 armour and wearables table 32 4 bytes 0132 0x0c00 critters table 64 48 bytes 0d32 0x30 containers table 16 3 bytes 0d62 0x20 light source table 16 2 bytes 0d82 0x20 unknown, maybe jewelry info table 0da2 0x40 animation object table 16 4 bytes 0de2 end * Melee weapons table (0x0000-0x000f) 0000 Int8 damage modifier for Slash attack 0001 Int8 damage modifier for Bash attack 0002 Int8 damage modifier for Stab attack 0003 3 unknown 0006 Int8 skill type (3: sword, 4: axe, 5: mace, 6: unarmed) 0007 Int8 durability * Ranged weapons table (0x0010-0x001f) 0000 Int16 unknown bits 9-15: ammunition needed (+0x10) 0002 Int8 durability * Armour and wearables table (0x0020-0x003f) 0000 Int8 protection 0001 Int8 durability 0002 Int8 unknown 0003 Int8 category: 00: shield 01: body armour 03: leggings 04: gloves 05: boots 08: hat 09: ring * Critters table (0x0040-0x007f) 0000 Int8 unknown 0005 Int8 npc_power * Containers table (0x0080-0x008f) 0000 Int8 capacity in 0.1 stones 0001 Int8 objects accepted; 0: runes, 1: arrows, 2: scrolls, 3: edibles, 0xFF: any 0002 Int8 number of slots available?; 2: , -1: any * Light source table (0x0090-0x009f) 0000 Int8 light brightness (max. is 4; 0 means unlit) 0001 Int8 duration (00: doesn't go out, e.g. taper of sacrifice) * Jewelry info table (?) * Animation object table (0x01c0-0x01cf) 0000 Int8 unknown (0x00, 0x21 or 0x84) 0001 Int8 unknown (always 0x00) 0002 Int8 start frame (from animo.gr) 0003 Int8 number of frames 6.4 Object combining In the Ultima Underworlds, when you `apply' certain objects to one another in your inventory a new object is created. For example, pole + strong thread = fishing pole. The mechanism for this is very simple and is controlled by the file "cmb.dat" in the data/ directory. This file contains a table of 3 16-bit words for each allowable combination: `source1', `source2', `newobject' in that order. 3 zeros mark the end of the table. The low 9 bits of each word is the object ID. If an object of type source1 is applied to an object of type source2 (or vice versa) an object of type newobject is created. The top bit of each of the source words indicates whether that object is destroyed in the process: if it is a 1, the object is destroyed. (It is always the case that at least one of the source objects is destroyed: you can't create something from nothing, at least not this way). +--------------------------------------------------------------------------+ 7 Conversations Conversations in Ultima Underworld are controlled using an assembler-like opcode-language that seemed to originate from Forth sourcecode. There are 256 conversation "slots" available that can contain code (but doesn't need to). The field "npc_whoami" of the "Mobile object extra info" (see 4.2.3) decides which slot to take. If it is 0, a generic NPC-conversation is used instead. To persist conversation info, there are several places to store variables. * Quest Flags store infos needed by more than one NPC; they probably can be modified by the game, e.g. when something happens (killing Tyball). Think of them as global variables. * Private Globals store infos saved after exiting conversations. Sizes of this area are determined by the file "babglobals.dat". * Local Variables store infos during conversation. They are lost when conversation ends. * NPC infos are stored along with the NPC's data in the Master Object List and contain infos like npc_gtarg or npc_goal. See chapter 7.x for more. * Game globals are variables that are global to the game, e.g. game time, current dungeon level or player properties The conversation code can call "intrinsic" functions to use functionality built into the game, e.g. for bartering or player inventory access. 7.1 Conversation file format Conversations are stored in the file "cnv.ark". Note that in Ultima Underworld 2 .ark files are compressed. See Chapter 9.1 for details. The File header looks like this: 0000 Int16 number of conversation slots in file 0002 Int32 offset to conversation slot #0 0006 Int32 offset to conversation slot #1 ... If an offset is 0, the conversation slot is empty and no conversation is available. The name of the conversation partner is stored in string block 0007, string number = (conversation slot number - 0x0e00 + 16). The conversation header looks like this: 0000 Int16 unknown, always seems to be 0x0828, or 28 08 0002 Int16 unknown, always 0x0000 0004 Int16 code size in number of instructions (16-bit words) 0006 Int16 unknown, always 0x0000 0008 Int16 unknown, always 0x0000 000A Int16 game strings block to use for conversation strings 000C Int16 number of memory slots reserved for variables (*) 000E Int16 number of imported globals (functions + variables) 0010 start of imported functions list (*) This number includes all variables not belonging to stack, e.g. unnamed globals, imported globals and private conversation globals. An import record describes imported functions and game global variables used by the conversation: 0000 Int16 length of function name 0002 n*char name of function n+02 Int16 ID (imported func.) / memory address (variable) n+04 Int16 unknown, always seems to be 1 n+06 Int16 import type (0x010F=variable, 0x0111=imported func.) n+08 Int16 return type (0x0000=void, 0x0129=int, 0x012B=string) After this table the code section follows. 7.2 Private global variables Each conversation has a set of private global variables that are saved across conversations. The initial size of the area is stored in the file "babglobals.dat". When a game is saved, the globals are stored in the file "bglobals.dat". The layout of both files is as follows: 0000 Int16 number of conversation slot 0002 Int16 size of private global data for that conv.(=n) 0004 n*Int16 all globals for that slot (omitted in "babglobals.dat") ... repeat until file end On conversation start the game globals listed in the import table is copied to the memory address in the private globals. At end of conversation they are copied back to the game globals. 7.3 Memory layout Conversation memory is set up at start like this: 0000 local (unnamed) variables (may be empty, size nglobals) 000n game globals (copied on start) (usually 0x001f long) 0020 private conversation globals (of size nprivglobals) 0020+n stack begin (ascends up) There may be unnamed globals that start at memory location 0. The game globals then start at a higher address (the exact positions of the game globals are noted in the "import records list". For the memory, a full range of 16-bit memory (64k) should be available, which gives plenty of stack memory. 7.4 Assembler language opcodes The conversation code is an assembler-like language with a set of opcodes. It runs on a 16-bit virtual machine with a stack and a result register for imported functions. The language set is described here: Opcode no. immediate operands | Name | no. stack operands | | | | No. values saved to stack | | | | | Action | | | | | | 00 NOP 0 0 0 do nothing. 01 OPADD 0 2 1 push s[0] + s[1] 02 OPMUL 0 2 1 push s[0] * s[1] 03 OPSUB 0 2 1 push s[1] - s[0] 04 OPDIV 0 2 1 push s[1] / s[0] 05 OPMOD 0 2 1 push s[1] % s[0] 06 OPOR 0 2 1 logical OR of top two values. 07 OPAND 0 2 1 logical AND of top two values. 08 OPNOT 0 1 1 logical NOT of top value. 09 TSTGT 0 2 1 greater-than, nonzero if s[1] > s[0]. 0A TSTGE 0 2 1 greater-than-or-equal. 0B TSTLT 0 2 1 less-than. 0C TSTLE 0 2 1 less-than-or-equal. 0D TSTEQ 0 2 1 equality. Nonzero if s[1] == s[0]. 0E TSTNE 0 2 1 non-equal. 0F JMP 1 0 0 jump absolute. address is measured in words from the start of the code. 10 BEQ 1 1 0 branch on equal. Pop a value, branch relative if zero. 11 BNE 1 1 0 branch on Not Equal. As BEQ but branch if the value popped is non-zero. 12 BRA 1 0 0 branch. Always branch relative to the offset address. 13 CALL 1 0 1 call subroutine. Push the next instruction address and jump to the absolute address (in words) given. 14 CALLI 1 0 0 call imported subroutine. Argument is the function ID. 15 RET 0 1 0 return from subroutine. Pop the return address off the stack and jump to it. 16 PUSHI 1 0 1 push immediate value onto the stack. 17 PUSHI_EFF 1 0 1 push effective address onto the stack. The value pushed is the current frame pointer address plus the immediate operand. This allows local variables and function parameters. 18 POP 0 1 0 pop a value from the stack (and throw it away). 19 SWAP 0 2 2 swap the top two stack values. 1A PUSHBP 0 0 1 push the current frame pointer onto the stack. 1B POPBP 0 1 0 pop the frame pointer from the stack 1C SPTOBP 0 0 0 new frame. Set the frame pointer to the stack pointer. 1D BPTOSP 0 0 0 exit frame. Set the stack pointer to the frame pointer. 1E ADDSP 0 1 * pop a value, add to the stack pointer. Used to reserve stack space for variables. 1F FETCHM 0 1 1 pop address, push the value of the variable pointed to. 20 STO 0 2 0 store s[0] in the variable pointed to by s[1]. 21 OFFSET 0 2 1 array offset. Add s[1] - 1 to the effective address in s[0], push this as a new effective address. 22 START 0 0 0 start program. 23 SAVE_REG 0 1 0 pop a value from the stack and store it in the result register. 24 PUSH_REG 0 0 1 push the value of the result register on the stack. 25 STRCMP ? ? ? string compare. 26 EXIT_OP 0 0 0 end program (?) 27 SAY_OP 0 1 0 NPC says something. Print a conversation string (from the stack). 28 RESPOND_OP ? ? ? respond (?) 29 OPNEG 0 1 1 negate. s[0] -> -s[0]. (*) ADDSP, of course, doesn't actually push anything onto the stack, but its effect on the stack pointer is of pushing as many values as its operand specifies. (?) I haven't yet encountered these in the wild, so don't know exactly what they do. 7.5 Text substitutions In text strings printed by SAY_OP or a imported function (like "babl_menu") there may be strings like @SS1 or @GS8 that are substituted with other text. The format of the "format string" is like this: @XY[] X: source of variable to substitute, one of these: GSP G: game global variable S: stack variable P: pointer variable Y: type of variable, one of these: SI S: value is a string number into current string block I: value is an integer value : decimal value : format: C: use array index For pointer variables, the num value determines the location of the pointer relative to the stack. It usually refers to variables passed to a function (since they were pushed onto the stack). For stack variables, the num value determines which stack value is taken from the current local variables. The value to take is basep + For global variables, the value describes the globals position in memory, at the front where the imported game globals and private globals are stored. Example: @SS2 means: print string with string number found at basep + 2 @PI-3 means: print int value pointed to by pointer at basep - 3 @GS8 means: print string from global var #8 7.6 Intrinsic functions Each imported function has an ID (the argument of the CALLI opcode), and the "import table" (see above) usually imports all available functions, even unused ones. All imported functions have at least one argument, and the first one is the number of arguments additionally passed (some times this rule seems to be violated, e.g. function "babl_menu", see (*) below). First argument is always pushed last on stack. All values are passed by reference (as pointer to the actual value or array). Here is a quick overview of all builtin functions ("args" is the number of arguments without the mandatory first one): type args function name int 1 (*) babl_menu int 2 (*) babl_fmenu void 1 print int 0 babl_ask int 2 compare int 1 random string ? plural int 2 contains string ? append string ? copy int ? find int 1 length int ? val void ? say void ? respond int 1 get_quest void 2 set_quest string 2 sex int 2 show_inv int 2 give_to_npc int 2 give_ptr_npc int 1 take_from_npc int 1 take_id_from_npc int 4 identify_inv int * do_offer int 2 do_demand int 1 do_inv_create int 1 do_inv_delete int 1 check_inv_quality int 2 set_inv_quality int 1 count_inv void 0 setup_to_barter void ? end_barter void 0 do_judgement void 0 do_decline void ? pause void 2 set_likes_dislikes int 3 gronk_door void 1/3 set_race_attitude void 3 place_object void 1 take_from_npc_inv void ? add_to_npc_inv void 0 remove_talker void 2 set_attitude int 2 x_skills int 2 x_traps void ? x_obj_pos void 9 x_obj_stuff int 2 find_inv int 1 find_barter int 4 find_barter_total Here is a detailed description of every builtin function. arg0 is always the first argument (the last value pushed on the stack) and specifies the number of arguments passed. id=0000 name="babl_menu" ret_type=int parameters: arg1: array of string id's; ends with id = 0 description: shows a menu of further questions the user can select; string id's are stored in list in arg1 return value: number of selected response (one-based index of arg1 list) ------------------------------------------------------------------------- id=0001 name="babl_fmenu" ret_type=int parameters: arg1: array of string id's; ends with id = 0 arg2: array with on/off flag values (1==on) description: shows a menu with questions from list in arg1; the list in arg2 indicates if the question is available (0 means not available). return value: number of selected response string (from the arg1 list) ------------------------------------------------------------------------- id=0002 name="print" ret_type=void parameters: arg1: string id description: prints a string that is not spoken by anyone (e.g. scene description). ------------------------------------------------------------------------- id=0003 name="babl_ask" ret_type=int parameters: none description: lets the user type in a string; the string typed in is stored in a newly allocated string slot. The string is not stored after conversation ended. return value: string id of allocated string ------------------------------------------------------------------------- id=0004 name="compare" ret_type=int parameters: arg1: string id arg2: string id description: compares strings for equality, case independent return value: returns 1 when strings are equal, 0 when not ------------------------------------------------------------------------- id=0005 name="random" ret_type=int parameters: arg1: highest random value description: generates a random number in the range of [1..arg1] return value: the generated random number ------------------------------------------------------------------------- id=0006 name="plural" ret_type=string parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=0007 name="contains" ret_type=int parameters: arg1: pointer to first string id arg2: pointer to second string id description: checks if the first string contains the second string, case-independent. return value: returns 1 when the string was found, 0 when not ------------------------------------------------------------------------- id=0008 name="append" ret_type=string parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=0009 name="copy" ret_type=string parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=000a name="find" ret_type=int parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=000b name="length" ret_type=int parameters: arg1: string id description: calculates length of string return value: length of string ------------------------------------------------------------------------- id=000c name="val" ret_type=int parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=000d name="say" ret_type=void parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=000e name="respond" ret_type=void parameters: unknown description: (not used in uw1) return value: unknown ------------------------------------------------------------------------- id=000f name="get_quest" ret_type=int parameters: arg1: quest flag number description: returns a quest flag value return value: quest flag value ------------------------------------------------------------------------- id=0010 name="set_quest" ret_type=void parameters: arg1: new flag value arg2: quest flag number description: sets a quest flag value return value: none ------------------------------------------------------------------------- id=0011 name="sex" ret_type=string parameters: arg1: pointer to first string id arg2: pointer to second string id description: decides on the gender of the avatar which string id to return. for a male avatar, the second handle is taken, otherwise the first handle is taken return value: selected string id ------------------------------------------------------------------------- id=0012 name="show_inv" ret_type=int parameters: arg1: list with inventory item positions arg2: list with object id's shown in player's barter area description: the function copies the item positions and object id's of all visible items in the barter area to the array in arg1 and arg2 (which needs at most 4 array values each) return value: returns number of items stored in the arrays ------------------------------------------------------------------------- id=0013 name="give_to_npc" ret_type=int parameters: arg1: list of item inventory positions to give to npc arg2: number of items in list in arg1 description: transfers a number of items from the player inventory to the npc's inventory return value: returns 0 if there were no items to give, and 1 if there were some items ------------------------------------------------------------------------- id=0014 name="give_ptr_npc" ret_type=int parameters: arg1: quantity (?), or -1 for ignore arg2: inventory object list pos description: copies item from player inventory to npc inventory return value: none ------------------------------------------------------------------------- id=0015 name="take_from_npc" ret_type=int parameters: arg1: item id (can also be an item category value, > 1000) description: transfers an item from npc inventory to player inventory, based on an item id. when the value is > 1000, all items of a category are copied. category item start = (arg1-1000)*16 return value: 1: ok, 2: player has no space left ------------------------------------------------------------------------- id=0016 name="take_id_from_npc" ret_type=int parameters: arg1: inventory object list pos (from take_from_npc_inv) description: transfers item to player, per id (?) return value: 1: ok, 2: player has no space left ------------------------------------------------------------------------- id=0017 name="identify_inv" ret_type=int parameters: arg1: arg2: arg3: arg4: inventory item position description: unknown TODO return value: unknown ------------------------------------------------------------------------- id=0018 name="do_offer" ret_type=int parameters: arg1 ... arg5: unknown [arg6, arg7]: unknown description: checks if the deal is acceptable for the npc, based on the selected items in both bartering areas. the values in arg1 to arg5 are probably values of the items that are acceptable for the npc. the function is sometimes called with 7 args, but arg6 and arg7 are always set to -1. return value: 1 if the deal is acceptable, 0 if not ------------------------------------------------------------------------- id=0019 name="do_demand" ret_type=int parameters: arg1: string id with text to print if NPC is not willing to give the item arg2: string id with text if NPC gives the player the item description: decides if the player can "persuade" the NPC to give away the items in barter area, e.g. using karma. return value: returns 1 when player persuaded the NPC, 0 else ------------------------------------------------------------------------- id=001a name="do_inv_create" ret_type=int parameters: arg1: item id description: creates item in npc inventory return value: inventory object list position ------------------------------------------------------------------------- id=001b name="do_inv_delete" ret_type=int parameters: arg1: item id description: deletes item from npc inventory return value: none ------------------------------------------------------------------------- id=001c name="check_inv_quality" ret_type=int parameters: arg1: inventory item position description: returns "quality" field of npc? inventory item return value: "quality" field ------------------------------------------------------------------------- id=001d name="set_inv_quality" ret_type=int parameters: arg1: quality value arg2: inventory object list position description: sets quality for an item in inventory return value: none ------------------------------------------------------------------------- id=001e name="count_inv" ret_type=int parameters: unknown description: counts number of items in inventory return value: item number ------------------------------------------------------------------------- id=001f name="setup_to_barter" ret_type=void parameters: none description: starts bartering; shows npc items in npc bartering area ------------------------------------------------------------------------- id=0020 name="end_barter" ret_type=void parameters: unknown description: (not used in uw1), ends bartering, probably removing npc bartering items ------------------------------------------------------------------------- id=0021 name="do_judgement" ret_type=void parameters: none description: judges current trade (using the "appraise" skill) and prints result ------------------------------------------------------------------------- id=0022 name="do_decline" ret_type=void parameters: none description: declines trade offer (?) ------------------------------------------------------------------------- id=0023 name="pause" ret_type=void parameters: unknown description: (not used in uw1) ------------------------------------------------------------------------- id=0024 name="set_likes_dislikes" ret_type=void parameters: arg1: pointer to list of things the npc likes to trade arg2: pointer to list of things the npc dislikes to trade description: sets list of items that a npc likes or dislikes to trade; the list is terminated with a -1 (0xffff) entry ------------------------------------------------------------------------- id=0025 name="gronk_door" ret_type=int parameters: arg1: x tile coordinate with door to open arg2: y tile coordinate arg3: close/open flag (0 means open) description: opens/closes door or portcullis return value: unknown ------------------------------------------------------------------------- id=0026 name="set_race_attitude" ret_type=void parameters: unknown description: sets attitude for a whole race (?) ------------------------------------------------------------------------- id=0027 name="place_object" ret_type=void parameters: arg1: x tile pos arg2: y tile pos arg3: inventory item slot number (from do_inv_create) description: places a generated object in underworld used in Judy's conversation, #23 ------------------------------------------------------------------------- id=0028 name="take_from_npc_inv" ret_type=void parameters: arg1: unknown, always 1 in uw1 description: moves object from npc to player inventory, by npc inventory index (only used in conv. #16, Ishtass) return value: inventory object list position (used in take_id_from_npc) ------------------------------------------------------------------------- id=0029 name="add_to_npc_inv" ret_type=void parameters: unknown description: (not used in uw1) ------------------------------------------------------------------------- id=002a name="remove_talker" ret_type=void parameters: none description: removes npc the player is talking to (?) ------------------------------------------------------------------------- id=002b name="set_attitude" ret_type=void parameters: unknown description: unknown ------------------------------------------------------------------------- id=002c name="x_skills" ret_type=int parameters: unknown description: unknown return value: unknown ------------------------------------------------------------------------- id=002d name="x_traps" ret_type=int parameters: unknown description: unknown return value: unknown ------------------------------------------------------------------------- id=002e name="x_obj_pos" ret_type=void parameters: unknown description: (not used in uw1) ------------------------------------------------------------------------- id=002f name="x_obj_stuff" ret_type=void parameters: arg1: not used in uw1 arg2: not used in uw1 arg3: 0, (upper bit of quality field?) arg4: quantity/special field, 115 arg5: not used in uw1 arg6: not used in uw1 arg7: quality? arg8: identified flag? arg9: position in inventory object list description: sets object properties for object in inventory object list. if a property shouldn't be set, -1 is passed for the property value. ------------------------------------------------------------------------- id=0030 name="find_inv" ret_type=int parameters: arg1: 0: npc inventory; 1: player inventory arg2: item id description: searches item in npc or player inventory return value: position in master object list, or 0 if not found ------------------------------------------------------------------------- id=0031 name="find_barter" ret_type=int parameters: arg1: item id to find description: searches for item in barter area return value: returns pos in inventory object list, or 0 if not found ------------------------------------------------------------------------- id=0032 name="find_barter_total" ret_type=int parameters: s[0]: ??? s[1]: pointer to number of found items s[2]: pointer to s[3]: pointer to s[4]: pointer to item ID to find description: searches for item in barter area return value: 1 when found (?) ------------------------------------------------------------------------- 7.7 Imported variables All imported variables have type int (except for "npc_name" and "play_name", which are strings). Here's a list of all imported game variables: variable name description play_hunger play_health play_arms play_power play_hp play_mana play_level new_player_exp (not used in uw1) play_name player name play_poison (not used in uw1) play_drawn is 1 when player has drawn his weapon (?) play_sex (not used in uw1) npc_xhome x coord of home tile npc_yhome y coord of home tile npc_whoami npc conversation slot number npc_hunger npc_health npc_hp npc_arms (not used in uw1) npc_power npc_goal goal that NPC has; 5:kill player 6:? 9:? npc_attitude attitude; 0:hostile, 1:upset, 2:mellow, 3:friendly npc_gtarg goal target; 1:player npc_talkedto is 1 when player already talked to npc npc_level npc_name (not used in uw1) dungeon_level (not used in uw1) riddlecounter (not used in uw1) game_time game_days game_mins 7.8 Quest flags There are quest flags that are kept during gameplay to implement interaction between NPC's. Flags can be get/set using get_quest() and set_quest() or during gameplay, triggered by actions. Here's a list of flags and their meanings (when no values for the flag are specified, 1 means yes or true, and 0 means no or false): flag description 0 Dr. Owl's assistant Murgo freed 1 talked to Hagbard 2 met Dr. Owl? 3 permission to speak to king Ketchaval 4 Goldthirst's quest to kill the gazer (1: gazer killed) 5 Garamon, find talismans and throw into lava 6 friend of Lizardman folk 7 ?? (conv #24, Murgo) 8 book from Bronus for Morlock 9 "find Gurstang" quest 10 where to find Zak, for Delanrey 11 Rodrick killed 32 status of "Knight of the Crux" quest 0: no knight 1: seek out Dorna Ironfist 2: started quest to search the "writ of Lorne" 3: found writ 4: door to armoury opened flags 0..31 are stored in a 32-bit integer bit field, flags 32..35 are stored as Int8 values. See chapter 9.2. where the values are stored in the savegame. +--------------------------------------------------------------------------+ 8 3d models These are stored within the executable (bad! bad!). From Doug Church, on the 3d models: We'd take a 3ds model, convert it to an internal ASCII format, and then run a "model builder" which would generate an inlined BSP tree for it. This would be expressed in a byte code, or, really, as a set of simple ASM like codes. Things like "Vtx 56.7, 435, 35.3" or "Color 153" or "Norm 0.6, 0.8, 0.0, front04" or whatever. Then, we used the Macro Assembler (well, Optasm, really) to generate a bunch of "db" statements out of all this, and give it a label, and put it in the data segment. 3D models were then drawn by calling a little "model interpreter" in the game, which was given the address of this data block, which it then interpreted. i.e. when it got to the byte for "Norm", it would fetch the normal, dot it verse the eye vector, and jump or not based on the sign. There is a table of 2-byte model offsets, with room for 64 models. Positions of the table differ, as there are several builds of the uw.exe, ultimau1.exe or uw2.exe. game table start first bytes table base offset uw1 0x0004e910 b6 4a 06 40 0x0004e99e uw1 0x0004ccd0 b6 4a 06 40 0x0004cd5e same models, different place uw1 0x0004e370 b6 4a 06 40 0x0004e3fe ditto (reported Gerd Bitzer) demo 0x0004ec70 b6 4a 06 40 0x0004ecfe uw_demo uw2 0x00054cf0 d4 64 aa 59 0x00054d8a uw2 0x000550e0 d4 64 aa 59 0x0005517a another UW2 build Models are: index item_id description 00 - 01 014x door frame 02 0164 bridge 03 0150 bench 04 015f Lotus Turbo Esprit (no, really!) 05 0156 small boulder 06 0155? medium boulder 07 0154? large boulder 08 0151 arrow 09 0159 beam 0A 0160 pillar 0B 0157 shrine 0C 0D 0163 painting [uw2] 0E 0F 10 0161 texture map (8-way lever) 11 0162 texture map (8-way switch) 12 0166 texture map (writing) 13 0165 gravestone 14 016e? texture map 15 - 16 016f? ?texture map 17 015a moongate 18 0158 table 19 015d chest 1A 015e nightstand 1B 015b barrel 1C 015c chair 1D 0167 bed [uw2] 1E 0168 blackrock gem [uw2] 1F 0169 shelf [uw2] Node list --------- Actual model data is stored as a list with various "nodes" that do different things. There also is a vertex array that is filled at start of the model, and then faces are defined, using points from the vertex list. The list is parsed every frame and tests are done if some faces have to be rendered or not (depending if the player sees the polygon or not). There are some data types that are used in the model node data. These are: Int16 a simple 16 bit unsigned integer Fixed fixed point number with 8 bits before the fraction point (8.8) VertNo vertex number; lowest 3 bits are ignored TexCo texture coordinate; contains a 16 bit fractional texture coord. All data types use 16 bit values. Every model has a header that looks like this: 0000 Int32 unknown 0004 Fixed extents X value 0006 Fixed extents Y value 0008 Fixed extents Z value 000a node entries follow In general, node entries look as following: 0000 Int16 node id 0002 n custom node data (may be omitted) 8.1 List of all nodes Here's an overview of all node types used: node id description 0000 end node 0006 define sort node, arbitrary heading 000C define sort node, ZY plane 000E define sort node, XY plane 0010 define sort node, XZ plane 0014 ??? colour definition 002E ??? 0040 ??? seems to do nothing but introduce a face definition 0044 ??? this one too 0058 define face plane, arbitrary heading 005E define face plane Z/Y 0060 define face plane X/Y 0062 define face plane X/Z 0064 define face plane X 0066 define face plane Z 0068 define face plane Y 0078 define model center 007A define initial vertex 007E define face vertices 0082 define initial vertices 0086 define vertex offset X 0088 define vertex offset Z 008A define vertex offset Y 008C define vertex variable height 0090 define vertex offset X,Z 0092 define vertex offset X,Y 0094 define vertex offset Y,Z 00A0 ??? shorthand face definition 00A8 define texture-mapped face 00B4 define face vertices with u,v information 00BC define face shade (6 bytes) 00BE ??? seems to define 2 shades 00CE ??? yet another texture-mapped face 00D2 ??? shorthand face definition 00D4 define dark vertex face (?) 00D6 define gouraud shading Here's a detailed description of all nodes, sorted after functionality: Misc. nodes ----------- 0000 end node just ends current list; also ends sort node sublists 0078 define model center 0000 Int16 node id 0002 VertNo vertex list index to use as origin (?) 0004 Fixed origin X coordinate 0006 Fixed origin Y coordinate 0008 Fixed origin Z coordinate 000a Int16 ??? because of the limited resolution available for specifying object positions, the origin for model coordinates will typically need to be offset from the center of the collision volume. This parameter gives that center, in model coords. Vertex nodes ------------ Vertex node entries just set up the vertex list that is later used to take points and draw faces (such as triangles, polygons, etc.) 007A define initial vertex 0002 Fixed vertex X coordinate 0004 Fixed vertex Y coordinate 0006 Fixed vertex Z coordinate 0008 VertNo vertex list index to store new vertex 0082 define initial vertices 0002 Int16 number of vertices (=nvert) 0004 Int16 first vertex no.? 0006 Fixed vertex X coordinate for first vertex 0008 Fixed vertex Y coordinate 000a Fixed vertex Z coordinate 000c Fixed vertex X coordinate for second vertex 000e and so on, for nvert vertices 0086 define vertex offset X 0002 VertNo reference vertex to modify 0004 Fixed offset to add to X coordinate 0006 VertNo new list index to store vertex 0088 define vertex offset Z same as 0086, but for the Z coordinate 008A define vertex offset Y same as 0086, but for the Y coordinate 0090 define vertex offset X,Z 0002 Fixed offset to add to X coordinate 0004 Fixed offset to add to X coordinate 0006 VertNo reference vertex to modify 0008 VertNo new list index to store vertex 0092 define vertex offset X,Y same as 0090, but for the X and Y coordinate 0094 define vertex offset Y,Z same as 0090, but for the X and Y coordinate 008C define vertex variable height this is used for pillars and doorframes where the model must reach up to the ceiling, wherever it be. 0002 VertNo reference vertex to modify 0004 Int16 ??? 0006 VertNo new list index to store vertex Face plane checks ----------------- Face plane checks exist to check if a following face has to be drawn or not. Usually a face normal vector is defined to verify. A length value is given to know how many bytes to omit in the node list. 0058 define face plane, arbitrary heading (backface cull) 0002 Int16 number of bytes to skip when not visible 0004 Fixed normal vector X coordinate 0006 Fixed distance "model origin -> face" X value 0008 Fixed normal vector Y coordinate 000a Fixed distance "model origin -> face" Y value 000c Fixed normal vector Z coordinate 000e Fixed distance "model origin -> face" Z value after this node usually face info nodes follow 0064 define face plane X Y and Z coordinates of normal vector is 0 (YZ plane normal) 0002 Int16 number of bytes to skip when not visible 0004 Fixed normal vector X coordinate 0006 Fixed distance "model origin -> face" X value after this node usually face info nodes follow 0066 define face plane Z same as 0064, but with Z coordinate (XY plane normal) 0068 define face plane Y same as 0064, but with Y coordinate (XZ plane normal) 005E define face plane Z/Y X coordinate of normal vector is 0 0002 Int16 number of bytes to skip 0004 Fixed normal vector Z coordinate 0006 Fixed distance Z value 0008 Fixed normal vector Y coordinate 000a Fixed distance Y value 0060 define face plane X/Y same as 005E, but with X and Y coordinates/values (in this order) 0062 define face plane X/Z same as 005E, but with X and Z coordinates/values Face info nodes --------------- They just define a face (polygon) from some points of the vertex list. 007E define face vertices 0002 Int16 number of vertices (=nvert) 0004 VertNo vertex list index for first point 0006 VertNo vertex list index for second point 0008 and so on 00A8 define texture-mapped face vertex u and v coordinates are stored as 0.16 fractional values. just divide by 65535.0 to get coordinates in the range [0; 1] 0002 Int16 texture number (?) 0004 Int16 number of vertices (=nvert) 0006 VertNo vertex list index for first point 0008 TexCo first vertex u coordinate 000a TexCo first vertex v coordinate 000c VertNo vertex list index for second point 000e TexCo second vertex u coordinate 0010 and so on 00B4 define face vertices with u,v information same structure as 00A8, but without the "texture number" field. Sort nodes ---------- Sort nodes are there to sort faces of a whole node list and the renderer can determine if the list has to be rendered at all. 0006 define sort node, arbitrary heading 0002 Fixed normal vector X coordinate 0004 Fixed distance X coordinate 0006 Fixed normal vector Y coordinate 0008 Fixed distance Y coordinate 000a Fixed normal vector Z coordinate 000c Fixed distance Z coordinate 000e Int16 left node offset (starting at 0010) 0010 Int16 right node offset (starting at 0012) 000C define sort node, ZY plane the X coordinate values are assumed to be 0 0002 Fixed normal vector Z coordinate 0004 Fixed distance Z coordinate 0006 Fixed normal vector Y coordinate 0008 Fixed distance Y coordinate 000a Int16 left node offset (starting at 000c) 000c Int16 right node offset (starting at 000e) 000E define sort node, XY plane same as 000C, but with X and Y coordinates (in this order) 0010 define sort node, XZ plane same as 000C, but with X and Z coordinates (in this order) Unknown nodes ------------- 0014 ??? colour definition 0002 VertNo vertex number 0004 Int8 c1 ??? 0005 Int8 c2 ??? 0006 VertNo vertex number 002E ??? 0002 Int16 ??? 0040 ??? seems to do nothing but introduce a face definition 0044 ??? this one too no further node data 00BC define face shade 0002 Int16 colour (address of colour variable) 0004 Int16 shade (dark value) 00BE ??? seems to define 2 shades ?? refers to 2 model variables 0002 Int16 var 1 0004 Int16 var 2 00CE define texture-mapped face same data as 00B4 00A0 shorthand texture-mapped face definition seems to be a quick way to define a face with 4 vertices and automatic texture coordinates; vertex list indices 0002 VertNo ??? 0004 Int8 vertex list index 0 0005 Int8 vertex list index 1 0006 Int8 vertex list index 2 0007 Int8 vertex list index 3 00D2 define texture mapped face (shorthand) same as 00A0 00D4 define vertex shading values 0002 Int16 number of vertices (=nvert) 0004 Int16 base colour for Gouraud shading (colour variable address) 0006 VertNo vertex list index for first point 0008 Int8 dark value for first point ??? 0009 VertNo vertex list index for second point 000b Int8 dark value for second point ??? and so on; if nvert is odd, read another empty byte to have 16 bit word align 00D6 introduce Gouraud shaded face no other info; may switch on gouraud shading +--------------------------------------------------------------------------+ 9 Miscellaneous stuff This section describes all miscellaneous data structures and things that didn't fit elsewhere. 9.1 Ultima Underworld 2 compression scheme [uw2] The second game uses a new compression scheme to crunch data in .ark files together. The file header has a slightly different format than in uw1's files: 0000 Int16 number of blocks in file (=nblocks) 0004 Int32 unknown (always 0) Now follow 4 tables, each one is "nblocks" long and consists of Int32's. Table 1: offset table absolute file offset to block an offset of 0 means the entry is not (yet) used Table 2: flags for the datachunk Bit 0: block should be compressed (always set in uw2) Bit 1: actually is compressed Bit 2: the chunk has extra space allocated in case the compression isn't as effective next time. The "available space" value is valid for such chunks. Table 3: data size this gives the actual space occupied by the chunks on disk, either compressed or uncompressed data size, according to the flags. Table 4: available space This is valid for chunks with extra space (bit 2 in table 2 set). It gives the total space available for the chunk in the archive file. A compressed block always starts with an Int32 value that is to be ignored. If a block is actually compressed, it can be divided into subblocks. Each compressed subblock starts with an Int8 number; the bits from LSB to MSB describe if the following byte is just transferred to the target buffer (bit set) or if we have a copy record (bit cleared). After 8 bytes or copy record, the next subblock begins with an Int8 again. The copy record starts with two Int8's: 0000 Int8 0..7: position, bits 0..7 0001 Int8 0..3: copy count 4..7: position, bits 8..11 The copy count is 4 bits long and an offset of 3 is added to it. The position has 12 bits (accessing the last 4k bytes) and an offset of 18 is added. The sign bit is bit 11 and should be treated appropriate. As the position field refers to a position in the current 4k segment, pointers have to be adjusted, too. Then "copy count" bytes are copied from the relative "position" to the current one. 9.2 Savegame format Savegames are stored in folders called "SaveN", where N is the number of the save game. Ultima Underworld only allows 4 save game slots. The folder "Save0" is used to store the files "lev.ark" and "bglobals.dat" during gameplay. The file "player.dat" contains the main character data. The first 220 bytes are encrypted with a rather simple xor algorithm. The first byte in the file is the starting xor value. The next byte is xor'ed with xorvalue + 3, and for each next byte the xorvalue is incremented by 3. A simple implementation in C is here (it is assumed that xorvalue already contains the first byte): // descramble data unsigned char incrnum = 3; for(int i=0; i<220; i++) { if (i==80) incrnum = 3; data[i] ^= (xorvalue+incrnum); incrnum += 3; } After decryption, the file contains the following: 0000 14*char character name ... 001E Int8 Strength 001F Int8 Dexterity 0020 Int8 Intelligence 0021 Int8 Attack 0022 Int8 Defense 0023 Int8 Unarmed 0024 Int8 Sword 0025 Int8 Axe 0026 Int8 Mace 0027 Int8 Missile 0028 Int8 Mana 0029 Int8 Lore 002A Int8 Casting 002B Int8 Traps 002C Int8 Search 002D Int8 Track 002E Int8 Sneak 002F Int8 Repair 0030 Int8 Charm 0031 Int8 Picklock 0032 Int8 Acrobat 0033 Int8 Appraise 0034 Int8 Swimming ... 0036 Int8 max. vitality 0037 Int8 current mana, (play_mana) 0038 Int8 max. mana 0039 Int8 hunger, play_hunger ... 003D Int8 character level (play_level) ... 0044 3*8bits rune flags (*) ... 004C Int16 weight in 0.1 stones 004E Int32 experience in 0.1 points ... 0054 Int16 x-position in level 0056 Int16 y-position 0058 Int16 z-position 005A Int16 heading 005C Int16 dungeon level ... 005F Int8 bits 2..5: play_poison ... 00CE Int32 game time ... 00DC Int8 current vitality (*) The rune field is a bitfield, where an 1 indicates an available rune. Bits are seen from most to least significant. The 'A' rune is stored in bit 7 of the first field. how items are stored 9.3 Unknown files This section lists files with unknown meaning. skills.dat ---------- The file contains infos about the skills in character creation for every class. First 0x20 bytes are unknown. There are 5 entries for each of the 8 character classes. The first Int8 byte contains the length of one entry. Then follows as many Int8 bytes as the length tells. The bytes describe the skill the user can select. If the length is 1, the only skill given is auto-set, showing no selection. shades.dat ---------- Contains 12 entries, 8 byte long each. When renamed to shadez.dat (or deleted) uw runs in bright colors all the time without using candles and such. sounds.dat ---------- The file "sounds.dat" in the "sound" folder contains sound effect data. The file starts with an Int8 value that is the number of data entries in the file. Then 5 Int8 bytes for each entry in the file follow. It is supposed that the data may be midi commands to play back sfx. xfer.dat ---------- The Underworld games use the (colour-index) translation tables in data/xfer.dat for the transparencies (each transparency index has a table). [The numbers here are an attempt to back-convert from the translation table to RGBA values using a hairy little program of my own devising. They look "about right", so I'm inclined to leave them.] (description from TSSHP CVS) 9.4 Error codes Ultima Underworld has some error codes printed out when the game unexpectedly quits. The format is Nxxx where N is an uppercase letter from B to F and xxx is a decimal number. Error codes: B: out of low memory (1000h) C: out of EMS mem (2000h) D: could not read (3000h) E: could not write (4000h) F: resource/internal problem Here's a list of all possible error codes and their occurance B001 couldn't alloc memory for "data/strings.pak" D002 couldn't read "data/strings.pak" D007 couldn't read "data/babglobs.dat" E001 couldn't write "save0/bglobals.dat" +--------------------------------------------------------------------------+ end of file