Ultima VII usecode

UCC

The following is a discussion about UCC, Exult's Usecode Compiler, was taken from Exult's source code. The original file can be found on the Exult project site.

Introduction

Ultima VII's plot and conversations are controlled by a script encoded in 'usecode', a file in the game's 'static' directory. UCC is our attempt at providing a language and compiler so that we and others can write our own game plots.

This document is my first at documenting UCC. Please be aware that the UCC language is still being developed, so some language constructs may change to make script-writing easier.

The UCC language (which I'll sometimes refer to as 'usecode') is generally patterned after 'C', but with many exceptions:

• No type-checking. Values can be integers, strings, and vectors.
• Some constructs ('for' loops, 'case' statements) are not implemented. (This may change.)
• Game-specific features have been added, such as 'converse.'
• Functions need to be assigned unique numbers (though this may be relaxed in the future).

Command line options

• -o <file>

write output to <file>

• -I <path>

add <path> to the include path

• -s

compile for SI. Usecode for SI needs to be compiled with this option.

Top-Level

At the top-level, UCC supports pre-processor directives, functions, function prototypes, and integer constant declarations.

Pre-processing

UCC only supports the "#include <filename>" for pulling in another source file. In the future, support for macros ("#define") may beadded. And although we have not done so yet, we should also provide header files that declare various Exult constants.

Functions

Functions are similar to those in C, but without type declarations. Plus, one must assign a unique number which may be used to reference that function in ExultStudio.

Example:

	
Add2 0x793 (a, b)
{
    return a + b;
 }

Ranges of function numbers have specific meanings in Exult:

0-0x3ff	Function # is called for a game shape of that number.
0x400-0x5ff	Function # 0x400+N applies to NPC #N.
0x600-0x7ff	Used for 'Usecode eggs' (trigger points on the game map), except that 0x640-?? are used for spells.
0x800-	I think these are for general-purpose use.

Function Prototypes

These are declarations of other functions that can be called. In particular, these can refer to functions in U7 usecode. Example:

extern Ask_yesno 0x90a();  // Rets. true if 'Yes'.

Constant Declarations

One can declare integer constants globally, as follows:

     
	const int AMY = 0x168;	   // Amy's NPC #.
	const int [[AVATAR]] = -356;

Statements

Mainly want to document conversations at the moment:

Conversations

Since conversations are one of the game's strong points, I've tried to make their creation as easy as possible. The structure is:

   converse (<array of choices to enable>)
	     {
    case <answer string> [(remove)]:
	 <Code to execute if answer is chosen>
    ...
	     }

The above works like a loop, getting a choice from the user at the top, and then executing the code under the 'case' for that choice. The process ends when a 'break;' is encountered.

If "(remove)" appears on the 'case' line, the choice is removed from the screen when the user selects it. Otherwise, it remains.

One conversation can be nested in another. When a 'converse' is encountered within the code of another 'converse', the inner 'converse' choices replace the outer 'converse' choices (they're pushed onto a stack). When the inner 'converse' ends, the outer 'converse' choices are automatically restored.

While any code can be executed inside a 'case', there are several that are especially useful for conversations. These are:

Say

This causes an NPC to 'say' something in the conversation. To specify which NPC (whose face will appear), we provide an interface similar to a method-call in C++. Example:

<source>npc->say("Hello Avatar");</source>

'Say' may also be used without specifying an npc. In this case, the text will appear next to the face of the last npc that spoke.

Each 'say()' call will require a click from the user to proceed. More than one string can be specified in 'say', in which case they are concatenated together. A '~' in a string will cause text output to pause until the user clicks. Example:

<source>npc->say("Hello Avatar,", " it is good to see you.~", "How may I help you?");</source>

Add/Remove

These allow you to enable/disable possible choices that the user may make. This only makes sense for choices that appear in 'case' entries in the conversation. Example:

	converse (["Name", "Bye"])	// 2 choices enabled.
		 {
        case "Bye":
	     break;
	case "xyzzy" (remove):
	     say("Please don't make fun of my name.");
	     add("Bye");
	case "Name" (remove):
	     say("My name is xyzzy");
	     add("xyzzy");		// Now this is enabled.
	     remove("Bye");
		 }

Hide

While "npc->say()" will bring up a portrait of an NPC during a conversation, "npc->hide()" will remove that portrait.

USECODE File

Documentation for the STATIC/USECODE file. This information can also be found here.Italic text

PsudoBNF overview:

• LEFTVALUE = RIGHTVALUE is read as "LEFTVALUE consists of RIGHTVALUE".
• [TOKEN]* is read as "zero or more of TOKEN(s)".
• TOKEN = lots of text. "lots of text" is the details of what TOKEN is ususally data size, and vague description of relevance.

USECODE_FILE = [FUNCTION]*

FUNCTION = FUNCTION_HEADER DATASEGMENT CODESEGMENT

FUNCTION_HEADER = FUNCID FUNCSIZE

DATASEGMENT = DATASEG_SIZE DATASEG_DATA

CODESEGMENT = NUM_ARGS NUM_LOCALS EXTERNS USECODE_BLOCK

EXTERNS = NUM_EXTERNS EXTERN_LIST

FUNCID = (uint16) The "id" of the function. (Also referenced as "function number".)

FUNCSIZE = (uint16) The total size of the function (code + data). Am unsure if this also includes the "header".

DATASEG_SIZE = (uint16) The total size of the data segment (in number of bytes).

DATASEG_DATA = Consists of DATASEG_SIZE bytes of string data of the format "string\0" where \0 is the NULL byte.

NUM_ARGC = (uint16) The number of arguments to the function on the stack.

NUM_LOCALS = (uint16) The number of local "variables" used in the function.

NUM_EXTERNS = (uint16) The number of external function numbers in the external function list.

EXTERN_LIST = NUM_EXTERNS number of external numbers, each is (uint16) in size.

USECODE_BLOCK = [USECODE_CALL]+

USECODE_CALL = Consists of (ubyte8) opcode and a variable number of trailing bytes, depending upon which opcode. See: usecode/ucxt/Docs/opcodes.txt for more information.