ucxtread.txt

来自「一个制作3d游戏的源程序」· 文本 代码 · 共 747 行 · 第 1/3 页

This file is currently a random pile of useful information... someday it'll
be ordered in a coherent format.

* Error: "error: could not locate */Docs/opcodes.txt. exiting"
	ucxt needs to find the abovementioned file for details of the
	opcodes. You either need to run ucxt in the path exult/usecode/ucxt
	or add the following to exult.cfg:

	(inside the <config> tag)
	 <ucxt>
	  <root>
	  (the path to ucxt goes here (eg: /home/st/exult/usecode/ucxt/data))
	  </root>
	 <ucxt>

* Error: "Failed to locate usecode file. Exiting."
	ucxt attempts to locate the exult.cfg file to find the locations
	of black gate (ultima7) and serpent isle (serpent).

	ucxt hunts for the usecode file under all permutations of the
	following filenamesthe following filenames:

		$MAINPATH = (bg path from exult.cfg) | (si path from exult.cfg)
			| "ultima7" | "ULTIMA7" | "serpent" | "SERPENT"
		$STATICPATH = "static" | "STATIC"
		$USECODENAME = "usecode" | "USECODE"

		$MAINPATH/$STATICPATH/$USECODE
		$STATICPATH/$USECODE
		$USECODE

	It also searches under:
		
		usecode.u7
		usecode.si

	It's a mess, but I'm trying to be thorough. <grin>

***** Original ucdump.cc history, credits and stuff. *****
----------------------------------------------------------------------------------
	
 Ultima 7 usecode dump/disassembly utility
 Distributed under GPL

 Maintainer:
  Maxim S. Shatskih aka Moscow Dragon ([e-mail])

 History:
 - originally written June 99 by Maxim S. Shatskih aka Moscow Dragon ([e-mail])
 Thanks to Keldon Jones ([e-mail])
  and Wouter Dijklslag aka Wody Dragon ([e-mail]) for their help
 11-Oct-99
  - added "function search by opcode & intrinsic" feature
  - added "unknown opcode & intrinsic counting" feature
 12-Oct-99
  - the good deal of intrinsic functions is now known

 See source file comments for the description of usecode opcodes & intrinsic functions
  (the latter one differs between BG & SI)

 Some general usecode ideas:
 - usecode functions 0x0-0x3ff are shape handlers - called on double-clicks & other
  event with appropriate shapes
 - usecode functions 0x401-0x4ff are NPC handlers - called on double-clicks & other
  event with appropriate NPCs - NPCID + 0x400 (401 for Iolo, 417 for LB etc).
 - usecode functions 0x500-0x5ff is for Wisps & guards (nonNPC characters able to talk)
  (these ranges seems to be hardcoded)
 - stack machine used to execute bytecodes
 - the machine's state is:
  stack
  local variables(forgotten on function exit, first N of them are call arguments -
          first pushed is 0, next are 1, 2...)
  game flags
  ItemRef (???seems to be valid only for top-level functions-event handlers
        or maybe is persistent till quitting usecode executuion???)
  EventID (???seems to be valid only for top-level functions-event handlers
        or maybe is persistent till quitting usecode executuion???)
 - game flags are bytes treated as booleans (0/1), persistent across engine shutdown/restart
  and stored as a simple array (??? 0 or 1 based. Don't remember. Flag 3 means
  - Tetrahedron is down, flag 4 means - Sphere is down) in GAMEDAT\FLAGINIT.
 - usecode can also manipulate items & NPCs by means of intrinsic functions
 - "add" opcode can sum strings (concatenation). Also it can add integer to string
 - any array operations can be peformed on scalar values. In fact, each scalar value is
  treated by the array operations as an array with a single element. Vice versa is also
  true - for instance, ItemsNearItem() function returns an array. Sometimes it is used in
  enum/next loop as an array, but sometimes it is used as an itemref.
 - array indices are 1-based as in VB
 - itemref is a unique ID of the given item. For NPCs, itemref is (-NPCID). For other items,
  itemrefs seems to be non-persistent (not saved to savegame & re-invented on each
  engine startup)??? indexes into engine's item lists
 - there is a value called "referent" which identifies item & stored in U7IBUF
    Maybe Itemref is the same thing?
 - -356 is always an Itemref for Avatar. So, Avatar's NPC ID is possibly 356.
 - usecode execution starts from the event handler function. It is called by the engine
  without arguments (double-click) in some cases. ItemRef & EventID are set before entering usecode.
 - the easiest case is double-click on some item. In this case, a usecode event handler
  function called. Function ID usually matches the shape's Type number
  or is (NPCID + 0x400) for NPCs.
  ItemRef is set to the item double-clicked, EventID is set to 1 (double-click).
 - other causes for the engine to call usecode function:
  - events scheduled by intrinsic functions 1 & 2 have EventID 2
  - item is put on another item - the underlying item's handler is called with EventID 3
    (Penumbra's plaque)
  - usecode Egg - also calls a function with EventID 3
  - use item as a weapon (flammable oil) - EventID 4
  - NPC being beaten to death (examples: Hook in BG, Dracothaxus in FoV,
          Pomdirgun & Rotoluncia in SI) - 7 in SI???
  - Avatar & NPC approaching to some distance??? - 9 in SI
 - hex coords to sextant coords - ( x - 933 ) / 10, ( y - 1134 ) / 10

----------------------------------------------------------------------------------

***** Original ucdump Intrinsic Function Table Follows. *****
----------------------------------------------------------------------------------

/* Embedded function table for Black Gate */
const char* bg_func_table[] =
{
  /* Random1(Hi) - Returns a random integer or from 1 to Hi inclusively
    Used to select a random party member for remarks
  */
  "Random1",            /* 0 */
  /* Takes itemref + array of several integers.
    Executes a macro for this itemref
    Macro opcodes:
      either 0x35 or 0x45 - deletes an item (fire caused by the flaming oil)
      0x46 <integer> - sets item's frame number to integer (rotating crossbeam
                            while opening the portcullis gate)
      0x52 <string> - the same as ItemSay() function
      0x55 <usecode function number> - call a usecode event for the item
      0x56 <integer> - Guardian's phrase with given number
    All spells use this function - if current weather is 3 - 606 is called
    instead of the second part of the spell engine (magic negation field at Ambrosia,
      Armageddon is blocked after shouting 1st mantra & before shouting second).
  */
  "MacroExec",             /* 1 */
  /* Takes itemref + array of several integers + one more integer
    The same as above - but schedules a macro for execution later
    (use a serpent venom on somebody - first raises stats, then - after some time
      - lower them)
    Can also shout exclamations - "Call it... Heads... Its tails..."
      - double-click on money.
  */
  "MacroDelay",             /* 2 */
  /* SwitchTalkTo(itemref, face_frame) - switches conversation to other NPC,
    selecting one of possible face pictures
    Shows the face in the bottom of the screen if the face on top was not hidden yet
    Switching talk to -277 means - huge reg Guardian semi-transparent face
  */
  "SwitchTalkTo",           /* 3 */
  /* HideNPC(itemref) - hides NPC face away from the conversation */
  "HideNPC",            /* 4 */
  /* AddAnswer(str_or_array) - adds a answer or set of answers to */
  /*  the set of talk threads suggested */
  "AddAnswer",            /* 5 */
  /* RemoveAnswer(str) - removes a given string from set of talk threads suggested */
  "RemoveAnswer",           /* 6 */
  /* SaveTalkStartNew() - saves the conversation state & starts */
  /*  new blank set of talk answers suggested */
  "SaveTalkStartNew",         /* 7 */
  /* RestoreTalk() - restores set of answers suggested */
  /*  as was saved in SaveTalkStartNew() */
  "RestoreTalk",            /* 8 */
  /* EmptyTalk() - removes all talk answers
    Looks like the same as "cla" opcode
  */
  "EmptyTalk",              /* 9 */
  /* GetAnswer() - asks user to select one of the talk threads & returns it
    Practically the same functionality as "ask" opcode
  */
  "GetAnswer",            /* a */
  /* GetAnswerIndex() - asks user to select one of the talk threads
    & returns the 1-based index of it instead the text itself
  */
  "GetAnswerIndex",           /* b */
  /* AskNumber(min, max, step, default) - asks user a number by showing a slider */
  /*  with given parameters */
  "AskNumber",            /* c */
  /* SetItemType(itemref, type) - changes a type of given item to the new value */
  "SetItemType",            /* d */
  /* AreItemsNearNPC(NPCID, type, distance) - returns boolean whether there are
    items of such Type at the given distance from the given NPC.
    Distance -1 means - screen borders
  */
  "AreItemsNearNPC",            /* e */
  /* PlaySoundEffect(sound_num) - plays a given effect soundtrack
  */
  "PlaySoundEffect",              /* f */
  /* Random2(lo, hi) - returns a random integer from lo to hi inclusively */
  "Random2",            /* 10 */
  /* GetItemType(itemref) - returns a "type" value of the item */
  "GetItemType",            /* 11 */
  /* GetItemFrame(itemref) - returns a "frame" value of the item */
  "GetItemFrame",           /* 12 */
  /* SetItemFrame(itemref, frame) - sets a "frame" value for the item */
  "SetItemFrame",           /* 13 */
  /* GetItemQuality(itemref) - returns a "quality" value of the item */
  "GetItemQuality",         /* 14 */
  /* SetItemQuality(itemref, quality) - sets a "quality" value for the item
    (Penumbra's plaque)
    Returns old quality???
  */
  "SetItemQuality",       /* 15 */
  NULL,             /* 16 */
  NULL,             /* 17 */
  /* GetItemCoords(itemref) - parameter is itemref returned by
      ItemSelectModal(), returns array
    The array is 2 item's coordinates - array[1], array[2]
  */
  "GetItemCoords",          /* 18 */
  NULL,             /* 19 */
  NULL,             /* 1a */
  /* GetNPCID(itemref) - returns NPCID from Itemref - possibly does-nothing function???
    Accepts values like -2 for Spark or -356 for Avatar on input
  */
  "GetNPCID",         /* 1b */
  /* GetNPCClass(NPCID) - returns a number specifying the NPC class -
    fighter/sage/shopkeeper etc. Used in exclamations like "Oh my aching back!"
    10 seems to be Noble (Finnegan & his aching back :-) )
    Or maybe this is GetNPCActivity???
  */
  "GetNPCClass",          /* 1c */
  /* SetNPCActivity(NPCID, activity) - sets an NPC activity
    11 - Loiter (leave with "go home")
    15 - Wait (leave with "wait here")
    ??? in cheat menu order?
  */
  "SetNPCActivity",             /* 1d */
  /* JoinNPC(itemref) - joins NPC to the party
    This seems to only set Party flag on - the same effect as doing this in cheat mode
    ???in BG, unusual companions (joined by cheat) will not be shown in Inventory/Ztats
      gumps. Where this information (whether the NPC is a usual companion) is kept?
    In SI, they will (I saw Rotoluncia's Ztats - though no 2 keys + a wand usually taken
      from her when dead in inventory. Trying to display Vasculio's Ztats hung
      the game) - but headless :-)
    Once more - it is kept somewhere...
  */
  "JoinNPC",              /* 1e */
  /* DismissNPC(itemref) - dismisses NPC from the party */
  "DismissNPC",             /* 1f */
  /* GetNPCStat(NPCID, property_id) -
    returns NPC's statistic value (9 is food level, 0 is Strength, 3 is Hits, )
    (1 & 4 seems to be Training & Combat???)
    Vas Mani (Restoration) spell is a good example
  */
  "GetNPCStat",         /* 20 */
  /* ChangeNPCStat(itemref, property_id, delta) -
    increments (or decrements for negative delta) NPC's statistic value.