GOOL Interpreter

*This page is up to date at https://wiki.cbhacks.com/w/GOOL\_Interpreter.*
In the Crash games, the GOOL Interpreter is responsible for interpreting an object's executable bytecode. This bytecode instructs the interpreter to perform a specific sequence of operations that can conditionally or unconditionally alter specific characteristics of the object (ex. appearance, location, status, etc.), and should ultimately render the object according to its changing characteristics. As a result, the player observes a lively, animated, and interactive enemy, box, collectible item, or whatever other kind of in-game object it may be.

## Interpretation

A single *interpretation* of an object's bytecode consists of the following steps:

1. *Fetch* the instruction at the object's program counter location
	* Read the instruction at the object's program counter location
	* Point the object's program counter to the location of the following instruction
2. *Perform* the operation specified by the fetched instruction
3. *Continue* repeating steps 1 and 2 until a suspending instruction is fetched

(A suspending instruction is typically either a RET, which marks the end of a block, or ANIF/ANIS, which change the object's current frame of animation.)

A single call to the GOOL interpreter routine with some desired object as its first argument results in a single interpretation of that object's bytecode. The GOOL bytecode interpreter routine expects an object that provides the following information:

* The location in its bytecode at which the interpreter shall begin its interpretation = object's program counter
* The location in its memory of a stack frame created for the interpretation = object's frame pointer
* The location in its memory at which the interpreter shall begin pushing the results of/popping the operands for interpreted instructions = object's stack pointer

Prior to an interpretation, each of these fields (program counter, frame pointer, stack pointer) is modified according to the object's current state [descriptor] and the type of interpretation.

## Types of interpretation

Many separate interpretations of an object's bytecode can occur within a single frame. The GOOL interpreter routine can be called with the same object from up to 7 distinct locations in a single iteration of the game loop. Each of the 7 calls to the interpreter routine with that object, and thus the ensuing interpretations of its bytecode, occurs under a separate condition. The 7 interpretations are identified based on the conditions under which they occur, and are as follows:

* One that occurs at a specified rate, i.e. after a specific amount of time has elapsed since its previous occurrence. (Code Block interpretation)
* One that [always] occurs [for each frame]. (Trans Block interpretation)
* One that occurs whenever the object is sent an event and its current state specifies the location of an event service routine. (Event Block interpretation)
* One that occurs whenever the object is sent an event and: its current state does not specify an event service routine or its event service routine failed to return an event, and the event sent maps to an event handler. (Handles Block interpretation)
* One that occurs whenever the object changes state. (Head Block interpretation)
* One that occurs whenever the object changes state and its recent Trans Block interpretation was unsuccessful (\*Trans Block interpretation)
* One that occurs when the object minimizes the distance during another object's query to 'find the nearest object', and the event sent for asynchronous handling (from the querying object) maps to an event handler. (\*Handles Block interpretation)

Ignoring the details for now, the latter 2 types are just a Trans Block and Handles Block interpretation, respectively, although their calls cross-reference the interpreter routine from different locations. Thus, there are a total of 5 types. These 5 types are more simply viewed as 5 separate *threads* of execution of the object's bytecode. To demonstrate, here is the expanded game loop routine with only the calls to routines that have a descendant call to the interpreter routine:

```
 sub_80011FC4(levelid)
 {
   ...
   C) sub_80011DD0 - Load entries and/or create universal game objects
                     (HUD/display, Crash, Aku Aku, Shadows, Boxes, Fruit)
     1) sub_8001C6C8 - CreateObject() [called once for each object created]
     ...
   GAME LOOP:
   {
     1) Code for handling game pause/start button press
       A) If start pressed...
          i) If pause menu object does not exist....
             1) sub_8001C6C8 - CreateObject() [create pause menu object]
             ...
             else
             1) sub_80024040 - SendEvent() [destroy pause menu object]
             ...
     2) If Crash object does not exist:
       A) sub_8002E98C - Create HUD and initialize level
          i) sub_8001C6C8 - CreateObject() [create HUD object]
          ii)sub_80026650 - Reinitialize Level
             1) sub_8001C6C8 - CreateObject() [create Crash object]
             ...
     3) Code for loading a new level if necessary
       A) If new level to load
          ...
          ii)sub_80011DD0 - Load entries and/or create universal game objects
             1) sub_8001C6C8 - CreateObject() [called once for each object created]
             ...
     ...
     5) Spawn all objects in current zone [for those that have their respawn bit set]
       A) sub_80025928 - Spawn objects
          1) sub_8001BCC8 - SpawnObject() [called for each object spawned]
          ...
     ...
     9) Update all objects and create transformed primitives for them
       A) sub_8001D5EC - UpdateObjects()
          1) sub_8001DA0C - UpdateObject() [called for each existing object]
     ...
   }
 }

```

Based on the above, consider an arbitrary frame of execution in terms of a single object. CreateObject() or SpawnObject() will not be called more than once [to create that object] in that frame; that is-the object is not created or spawned more than once, or even spawned after it is created and vice-versa. The object may not even be created/spawned in that frame because it either already exists or does not exist since the game has not requested it be created/spawned. If it is an existing object, it will also be updated only once in that frame. For a single object, the above can be reduced the following series of potential calls:

```
 sub_80011FC4(levelid)
 {
   ...
   GAME LOOP:
   {
     ...
     CreateObject(obj,...) or SpawnObject(obj,...)
     ...
     SendEvent(src,obj,...)
     ...
     UpdateObject(obj)
   }
 }

```

What the above leaves out, however, are the number of other locations at which a call to the SendEvent() routine reside. Some are located before the CreateObject or SpawnObject routine calls, some after, some within the UpdateObject routine itself, and even some within the interpreter routine, since there exist several types of GOOL instructions that allow another object to send an event to the recipient object. In fact, there is nothing preventing the object from being the recipient of more than one event sent (from potentially multiple sources) in a single frame. There may be an interpretation for each event sent to the object during that frame, and there is no limit on the number of events that can be sent. Thus, there may be many calls to SendEvent() [with the object as the recipient] in a single frame, but still only at most one call to CreateObject/SpawnObject() and UpdateObject(). Without getting too far off track, it is simply necessary to understand that each of these routines contains (or calls a routine that calls a routine that contains) a call to the interpreter routine:

```
 sub_80011FC4(levelid)
 {
   ...
   GAME LOOP:
   {
     ...
     CreateObject(obj,...) or SpawnObject(obj,...)
       InitObject(obj, ...)
         ChangeObjectState(obj, ...)
           CreateObjectStackFrame(obj); // *create initial stack frame
           -if there is a head block to interpret for the object
             CreateObjectStackFrame(obj);
             obj->pc = obj->pchead;
             InterpretObject(obj, 0x13, &stateref); // # 1 (head block interpretation)

     SendEvent(src,obj,...) // there may be multiple calls to this
        -if there is an event service routine for the object (in its current state)
           CreateObjectStackFrame(obj);
           obj->pc = obj->pcevent;
           InterpretObject(obj, 0x8, &stateref);    // # 2 (event block interpretation)
        -if there is not an event service routine for the object (in its current state)
         or the event service routine failed to return an event
          -if the event maps to an event handler in the event->state/handler map
           CreateObjectStackFrame(obj);
           obj->pc = handlerlocation;
           InterpretObject(obj, 0x3, &stateref);    // # 3 (handles block interpretation)
          -else
           ChangeObjectState(obj,state,...); // *

     UpdateObject(obj)
      -if the object is able to animate
        -if there is a trans block to interpret for the object (in its current state)
           CreateObjectStackFrame(obj);
           obj->pc = obj->pctrans;
           InterpretObject(obj, 0x3, &stateref);   // # 4 (trans block interpretation)
        -if at least n ticks have elapsed, where n is given by the 'wait' operand of the
         most recently suspending animation type instruction of the object's code block
           InterpretObject(obj, 0x4, &stateref);   // # 5 (code block interpretation)

   }
 }

```

Notice that immediately prior to each call [to the interpreter routine], with the exception of #5, a new stack frame is created for the object (which includes pointing its frame pointer and stack pointer, respectively, to the beginning and ending of its new frame), and its program counter is pointed to a distinct location within its bytecode. If each bytecode instruction is represented by a pseudo-instruction, a potential sequence of calls to the interpreter routine in a single frame [for only that object] might be represented by the following:

```
label  | address | pseudo-instruction

pcevent: 0x34      N  // call A
         0x38      N
         0x3C      S
...
pchead:   0x0      N  // call B
          0x4      N
          0x8      N
          0xC      S
...
pctrans: 0x50      N  // call C
         0x54      N
         0x58      N
         0x5C      N
         0x60      N
         0x64      N
         0x68      S
...
*pccode: 0x70      N  // call D
         0x74      N
         0x78      N
         0x7C      N
         0x80      S
...
pcevent: 0x34      N  // call E
         0x38      N
         0x3C      S
...
pcevent: 0x34      N  // call F
         0x38      N
         0x3C      S

```

Each call above to the interpreter routine is represented by the sequence of instructions (represented as pseudo-instructions) fetched during its interpretation. An N pseudo-instruction represents an instruction that did not suspend the interpreter, causing the next instruction in sequence to be fetched and interpreted. An S pseudo-instruction represents an instruction that did suspend the interpreter, causing the interpreter routine to end the interpretation/return to its caller. Each pseudo-instruction is listed with the address of the instruction it represents in the object's bytecode [relative to the beginning].

The first instruction fetched in each interpretation is also marked with a label; this label is given the name of the object *field* that points to its associated instruction. Immediately prior to each interpretation, with the exception of the one marked \*pccode, the object's program counter is pointed to the location in *this* particular field; it is this operation that causes each interpretation to begin at the location it does. This particular object field is also primarily responsible for determining the type of interpretation:

 pcevent
 pchead
 pc

The `pctrans`, `pcevent`, and `pchead` fields each contain a pointer to/the absolute location of an individual *block* in the object's bytecode. These fields locate the respective entry points for 3 separate *threads* of interpretation for the object-a *trans* thread, an *event* thread, and a *head* thread. Whenever the object changes state, its `pctrans` and `pcevent` fields are modified according to the state descriptor for its new state; its `pchead` field is then cleared. (If the object wishes to modify its `pchead` field, it does so via a MOVC instruction in its bytecode.)

Whenever the object changes state, its program counter (`pc` field) is also set directly to the location of the *code* block specified by the `pccode` field of the state descriptor for its new state. The entirety of the object's stack contents are then unwound, or the object's stack pointer is reset to its initial location, and an initial stack frame is [re]created. This program counter location and stack configuration is then restored after each subsequent non-code block interpretation is completed. (That is-since those interpretations require the program counter value to be *replaced* with a new location and a new stack frame to be created, after they are completed, the original program counter location and initial stack frame are restored). When the interpretation marked #5 in the above pseudo-code (the code block interpretation) finally occurs, the object's program counter will point to its code block and its stack frame will be the initial frame. The code block interpretation is yet another thread of interpretation for the object-a *code* thread.

For the sake of explanation, *handles* blocks are viewed as being equivalent to *event* blocks, so *handles* interpretations and threads are simply ignored. The timeline to the right shows an arbitrary frame of execution in terms of the times elapsed for the various interpretations of a single object's bytecode. Towards the beginning of the frame, the interpreter has performed a code block interpretation and a trans block interpretation for the object. Towards the end of the frame, the interpreter has performed an event block interpretation for that object, as it has been sent an event from some [unknown] source. The following timeline extends this timeline [to the right] to 6 arbitrary frames of execution:

The extended timeline makes it clear that this particular object has been configured to have its code block interpretation occur every other frame. It also shows the performance of more than one event block interpretation for that object during the second frame. The following timeline shows the same 6 frames of execution in terms of the times elapsed for all interpretations of each existing object's bytecode; in this particular instance, there are only 2 existing objects.

## Stack Frame (incomplete)

A new stack frame is created for an object immediately prior to an interpretation of its bytecode. It is also created when jumping to and linking a bytecode routine via the JAL instruction. An object's *initial* stack frame is created when it enters its initial state, and is recreated for each subsequent state change (after the unwinding the stack). The initial stack frame is used for the object's code block interpretation. At any given point in time, an object's frame pointer and stack pointer, respectively, locate the beginning and end of its *current* stack frame.

### Format

A stack frame has the following format:

(\*\*Arguments come before frames and are not actually 'part' of them)

### Initial Stack Frame

When the object is first created/spawned, or when it changes state, its program counter is pointed to the code block with offset `pccode` (given by the state descriptor for its initial or new state), its frame pointer is cleared, and its stack pointer is *reset* to its initial location:

The object's initial stack frame is then [re]created by pushing the following sequence of values to the stack:

* 0x0000FFFF - Interpreter Mode Flags. Not an actual interpreter mode flags value but rather an indicator that an unwinding of this frame shall not restore interpreter mode flags.
* `obj->pc` - Program Counter. At this point, it points to the code block for the object's initial/new state.
* `(((unsigned long)obj->fp - (unsigned long)&obj->self) << 16) | ((unsigned long)obj->sp - (unsigned long)&obj->self))` Frame Pointer and Stack Pointer relative offsets. At this point, frame pointer (`obj->fp`) is 0 and stack pointer points to its initial location; this combined value should be of the form 0x0000\*\*\*\*.

The object's frame pointer is then pointed to the beginning of that frame. With these values having been pushed to its stack, the object's stack pointer now points to the end of that frame. Thus, immediately following the instantiation or state change, the object's current stack frame is its initial stack frame.

During the object's code block interpretation, this frame is then *extended* with additional data, including stack operands and/or the results of interpreted instructions.

### Non-Initial Stack Frame

After an object's initial stack frame is created, but before its next code block interpretation occurs, several other non-code block interpretations may be performed. Immediately prior to performing any of these interpretations, a new stack frame is created *on top* of the initial stack frame, and *then* the current program counter value (which contains the code block location) is replaced with the location of the non-code block. This frame is created by pushing the following sequence of values to the stack:

* `modeflags` - Interpreter Mode Flags
* `obj->pc` - Program Counter. At this point, it points to the **code block** for the object's initial/new state.
* `(((unsigned long)obj->fp - (unsigned long)&obj->self) << 16) | ((unsigned long)obj->sp - (unsigned long)&obj->self))` Frame Pointer and Stack Pointer relative offsets. At this point, frame pointer points to the beginning of the initial frame, and stack pointer points to the end of the initial frame.

The object's frame pointer is then pointed to the beginning of that frame. With these values having been pushed to its stack, the object's stack pointer now points to the end of that frame. Thus, immediately following the creation of the frame, *it* is the object's current stack frame-that is, the initial stack frame is no longer the current stack frame.

When the following interpretation finishes, the object's program counter is *restored* to the code block location preserved in the current frame, and the preserved frame pointer and stack pointer offsets are used to restore the initial stack frame as the current frame.

**UNFINISHED**

## GOOL Instructions

### Crash 1

The GOOL Interpreter in Crash 1 recognizes a total of 58 different GOOL instructions:

* 6 Arithmetic Instructions (incl SHA\*)
* 4 Non-bitwise Logical/Logical Comparison Instructions
* 4 Bitwise Logical Instructions
* 5 Comparison Instructions
* 5 Data Transfer Instructions
* 8 Mathematical Function Instructions
* 4 Control Flow Instructions
* 19 Miscellaneous/Multi-Purpose Instructions

#### GOOL Instruction Tables

##### Main Instruction Table

The GOOL instruction table below lists the opcode, mnemonic/name, format, operands (based on explicit and/or implicit specification of source origin and/or destination target), general operation (represented with c-style statement), and a description for each GOOL instruction.

Note that a few instructions can not be represented with a single mnemonic; operations for these instructions are not only determined by their opcode but also their primary operation subtype and possibly secondary operation subtype fields. These instructions have their own tables, which are given in the following sections.

### Crash 2

The GOOL Interpreter in Crash 2 recognizes a total of 79 GOOL instructions, including two duplicates. Many of the instructions are unknown. The basic arithmetic and logical operations are preserved the same as in Crash 1, but most others have been changed.

Crash 2 GOOL code may also contain sections of machine code for the MIPS processor architecture (used by the playstation).

#### GOOLv2 Instruction Table

The GOOL instruction table below lists the opcode, mnemonic/name, format, operands (based on explicit and/or implicit specification of source origin and/or destination target), general operation (represented with c-style statement), and a description for each GOOL instruction.

### GOOL Instruction Operands

...

* In/Source type operands
	+ Explicitly specified (i.e. origin = determined by operand's corresponding bitfield from the instruction)
		- GOOL in/source operand
		- Immediate operand
	+ Implicitly specified (i.e. origin = top of object's stack; implicitly popped from top of object's stack)
		- Stack in/source operand
* Out/Destination type operands
	+ Explicitly specified (i.e. target = determined by operand's corresponding bitfield from the instruction)
		- GOOL out/destination operand
	+ Implicitly specified (i.e. target = top of object's stack; implicitly pushed to top of object's stack)
		- Stack out/destination operand/result\*

\*technically not an 'operand', but rather a *result* of the instruction's overall operation; it is *implied* that instructions that use [an] operand(s) of this type always pushes it/them (i.e the result(s)) to the top of the object's stack.

#### Explicit Operands

A GOOL instruction's explicit operands are *explicitly* specified in its lower 24 bits (operand portion). Each explicitly specified operand is either an immediate operand, or a GOOL operand.

##### Immediate Operands

An immediate operand *directly* specifies its value in its corresponding bitfield (within the operand portion) of the instruction. The number of immediate operands and their positions/bit-lengths varies between instructions.

Immediate Operands are in operands (source operands).

##### GOOL Operands

Conversely, a GOOL operand is specified as a *reference* to its actual value or destination location. Each GOOL operand is 12 bits in length; a GOOL instruction may require the specification of at most 2 GOOL operands, within the upper and/or lower halves of its operand portion, respectively. The 12 bit GOOL reference that specifies a GOOL operand encodes a [32 bit] pointer to its corresponding source value and/or destination location. Operations for instructions that require GOOL operand specification first *translate* the corresponding GOOL reference(s) to yield their decoded pointer(s) before accessing pointed data.

See the GOOL Reference Translation section for more information.

Depending on how a GOOL operand is used by its instruction, it may be an *in* (source) operand, an *out* (destination) operand, or both (*inout* operand). If an instruction only reads the [input] value located by its translated GOOL operand (a pointer), it is an *in* (source) operand. If an instruction only writes a result/value to the location of its translated GOOL operand, it is an *out* (destination) operand. If an operand meets both of these criteria it is an *inout* operand.

#### Implicit Operands

##### Implicit In Operands

Some GOOL instructions may require the *implicit* specification of one or more (implicit) in operands. In operands are implicitly specified prior to an instruction's interpretation by pushing their value(s)-which must remain the topmost values at interpretation-to the object's stack. It is *implied* that these so-called implicit operands will exist on the stack for the instruction to pop and use as input.

##### Implicit Out Operands

For most GOOL instructions, the net effect of their operation involves an implicit push of one or more *results* to the object's stack. That is-it is *implied* or expected that these instructions will ultimately push their results to the object's stack.

### GOOL Reference Translation

The following table lists the encoding format, potential type name, and a descriptive type name for each of the possible GOOL reference types:

Potential GOOL Reference type names have been deduced based on what appears to be an unreferenced array of GOOL interpreter debug strings at 0x103B8.

#### Stack Pop/Push

A GOOL reference of this format translates differently depending on whether the operand that specifies it is an *in* operand or an *out* operand:

* *In* operands specified as a reference of this type translate to a pointer to the top of the object's stack after an ensuing pop of the value located there (i.e. stack pointer is decremented).
* *Out* operands specified as a reference of this type translate to a pointer to the top of the object's stack prior to an incrementation of its stack pointer. A stack push will result from the translation's incrementing of the object's stack pointer and the instruction's ultimate dereferencing of the returned/translated pointer for a write.

#### Var Ref

 Field

GOOL References of this format translate to a pointer to the `A`th object field in relation to the object's `self` field.

Most of an object's significant fields are located past a `0x60` byte offset from the beginning of its structure-i.e. past its `self` field. Note that the last of these fields is the object's array of/address space for its [local] memory where its global variables and stack contents are stored. Because object fields are 4 bytes in size and an object's `self` field is located at a 0x60 byte offset from the beginning of its structure, then the formula:

`0x60 + (A * 4)`

gives the byte offset of the actual field located by the translated pointer.

If `A` = `0x1F`, then the reference will have the format `111000011111`; this is, however, already defined as the format for a stack pop/push reference-the processing of which takes precedence over that of var references. Notice that if such a reference were not instead translated as a stack pop/push reference, its translated pointer would locate the field at byte offset `0x60 + (0x1F * 4) = 0xDC`-the object's stack pointer. Then, it should not be possible to directly modify an object's stack pointer by accessing a translated reference. Only indirectly via translation of a stack push/pop reference should the object's stack pointer be modified.

#### Reg Ref

 Field
 L

GOOL references of this format translate to a pointer to the `A`th object field in relation to the object's `B`th link object's `self` field. An object's *link objects* are referred to by the group of 8 object pointers beginning with its `self` field; the first of these pointers is the object's `self` link, the second a pointer to its `parent` object, the third a pointer to its `sibling` object, and so on.

#### Ireg Ref

 Field

GOOL references of this format translate to a pointer to the predefined constant long at an offset of `R` longs relative to the beginning of the object's local executable's constant data pool item.

A GOOL executable's constant data pool item is essentially a table of predefined constants. For example, it includes the EIDs of any entries, preconfigured bitfields and bit selectors, audio sample parameters (volume, pan, etc), specific speeds or velocities, and other constants referenced by this type.

NOTE: if an instruction's *out* operand is specified as a reference of this type, its operation will ultimately replace the constant at the translated location with its output result. A write to the executable's data pool should generally be avoided unless a global change to that constant, and therefore an equal change in behavior for each object that is an instance of that executable, is desired.

#### Pool Ref

 Field

GOOL references of this format translate to a pointer to the predefined constant long at an offset of `R` longs relative to the beginning of the object's external executable's constant data pool item.

The same considerations for ireg refs apply to pool refs.

#### Frac Ref

100IIIIIFFFF
 Field
be multiplied by 16
-0x2000 to 0x1FF0
-16.0 to 15.9375?
R = 0x10N
 I
 F

GOOL references of this format translate to a pointer to the value `(16*C)`.

Two signed long *constant buffers* are located at offsets `0x40` and `0x44`, respectively, in scratch memory (as referenced by the pointer at memory location `0x56480` [`gp$(0x44)`].) At any point during the game's execution, the *currently active constant buffer* is either the buffer at offset `0x40` or `0x44`, and is indicated by either a `0` or a `1` in the unsigned long at memory location `0x56484` [`gp$(0x48)`]. Translation for references of this format consists of the following steps:

* Write the value `(16*C)`-that is, 16 times the value specified by the `C` bits-to the currently active constant buffer.
* Swap the currently active and inactive constant buffers (that is, if `0` previously indicated the currently active constant buffer, change it to a `1`; conversely, if it is a `1`, change it to a `0`).
* Return a pointer to the `(16*C)` signed long value in the buffer it was written to (which, after the swap, will always be the currently inactive buffer.)

This double-buffer allows the sufficient specification of up to 2 constant type GOOL references per instruction; each of the 2 buffers will keep track of up to 2 constants to be used by operations of instructions with the corresponding operands.

`C` can be specified as a negative constant with the following 2's complement format:

* `C = 1NNNNNNNN (-N): V = 11111111111111111111NNNNNNNN0000 (16 * -N)`
* `C = 0NNNNNNNN ( N): V = 00000000000000000000NNNNNNNN0000 (16 * N)`

Where `V` is the calculated signed long that will be written to the appropriate constant buffer for the specified formats of `C`.

Note: *out* operands are not meant to specify a reference of this type; any that do so are useless. Translation of this reference type returns a pointer to the currently inactive constant buffer after storing the appropriate constant value `(C * 16)` in the currently active constant buffer and then swapping the 2 buffers. The constant value in the inactive constant buffer would ultimately be overwritten with an expected result of the instruction with the out operand. However, since that buffer could only be accessed via subsequent translation of another frac or int ref, which would involve first overwriting its current value (the result) with a new constant value, then that result could never be accessed [without first being overwritten].

#### Int Ref

 Field
be multiplied by 256
-0x8000 to 0x7F00
R = 0x100N

GOOL references of this format are translated almost identically to frac refs; the only difference is in the calculation for the constant written to the buffer:

* `I = 1NNNNNNN (-N): V = 1111111111111111NNNNNNNN00000000 (256 * -N)`
* `I = 0NNNNNNN ( N): V = 0000000000000000NNNNNNNN00000000 (256 * N)`

The same considerations for frac refs apply to int refs.

#### Stack Ref

 Field
relative to object fp
-64 args to +63 local vars

GOOL references of this format translate to a pointer to the long that is `S` longs (`4*S` bytes) relative to the object's current frame pointer. If `S` is specified as a negative value/offset, it refers to an argument; this is because arguments are located *before* the start of the stack frame. If `S` is specified as a positive offset (> 3), it refers to a local variable (i.e. operation result).

`S` can be specified as a negative offset with the following 2's complement format:

* `S = 1NNNNNN (-N): O = 111111111111111111111111NNNNNN00 (4 * -N)` (argument offset)
* `S = 0NNNNNN ( N): O = 000000000000000000000000NNNNNN00 (4 * N)` (local variable offset)

#### Null Ref

(translates to `0`)

GOOL references of this format translate to the value `0` (i.e. invalid pointer to address `0`). Some instructions will return without making any calculations or pushing any results if an operand is specified as a reference of this type.

Most other instructions do not account for translated references of this type. They assume that a translated reference will always point to a valid memory location. After these instructions translate a null ref, they will attempt to access the memory at address `0x0`-which lies in the kernel code segment-thus resulting in a trap.

In the instruction table, brackets '[]' around one or more of an instruction's explicit operands (\*given that parenthesis '()' are not listed around any other operand) indicate that, if any of those operands are specified as null refs, the instruction will return before performing their associated calculations. Brackets '[]' around one or more of an instruction's implicit operands (\*given that parenthesis '()' are not listed around any other operand) indicate that, if the 'corresponding' explicit operands are specified as null refs, they (the implicit operands) do not actually exist. The order in which associated calculations are performed is indicated by the nested bracketing of operands.

For example, the `PSHV` instruction is listed with explicit GOOL in operands `[A,[B]]`, and implicit stack out operands `[I,[J]]`-aliases for the respective destinations of two subsequent stack pushes. These operand nestings indicate that:

* If only operand `B` is specified as a null ref, the instruction returns before operation `J = B` (equivalently, `push(obj,B)`) is performed. As a result, only operation `I = A` (equivalently, `push(obj,A)`) is performed.
* If operand `A` is specified as a null ref, the instruction returns before `push(obj,A)` is performed; then `push(obj,B)` is also never performed-so the instruction does nothing. It does not matter whether or not `B` is a null ref because its associated calculation/operation (i.e. push to stack) is never performed.
* If neither operand `A` nor operand `B` are specified as null refs, both/all operations-`push(obj,A)` followed by `push(obj,B)`-are performed.

#### SP-Double Ref

(translates to `1`)

GOOL references of this format translate to the value `1` (i.e. invalid pointer to address `1`). Specification of sp-double refs is exclusive to a few specific instructions. Most instructions do not account for translated references of this type. They assume that a translated reference will always point to a valid memory location. After these instructions translate an sp-double ref, they will attempt to access the memory at address `0x1`-which lies in the kernel code segment-thus resulting in a trap.

For a few instructions, if [a specific] one of their operands is explicitly specified as an sp-double ref, the actual values for both that operand and some other operand will be implicitly popped (in 2 subsequent pops) from the object's stack; no actual translation of the reference is performed. Alternatively, if that operand is not specified as an sp-double ref, then it is a valid reference to its actual value (and will be translated to a pointer that can be dereferenced to resolve that value); the other operand will then instead take on some *default* value.

In the instruction table, parenthesis '()' around one of an instruction's explicit operands indicate that: if that operand is specified as an sp-double ref, the instruction will pop the actual values for the bracketed '[]' pair of implicit stack in operands including that operand, in the order listed; otherwise the operand is a valid reference to its actual value, and its paired operand-for example, `P`-will take on a default value of `V`, where `P = V` is listed as an explicit immediate operand for that instruction.

For example, the `PATH` instruction is listed with explicit GOOL in operands `(A),B`, explicit immediate in operand `R = 0x100`, and implicit stack in operands `[R,A]`. If operand `A` is specified as an sp-double ref, the values for `R` and `A` will be popped from the object's stack, in that order. Otherwise, `R` [rate of path travel] will take on a default value of `0x100` (`1.0`) and `A`'s reference will be translated to resolve its value (by dereferencing, just as the majority of other instructions do for GOOL operands.)