Difference between revisions of "SCUMM/Technical Reference/Script resources"

From ScummVM :: Wiki
Jump to navigation Jump to search
(Added description of OC block for V3/4 games)
 
(6 intermediate revisions by 3 users not shown)
Line 12: Line 12:
Starting with Scumm V5, the blockname contains 4 bytes and the block size is BE including the 8 bytes for the header. Older games just have a 2 bytes blockname and the block size is in LE without the 6 bytes for the header.
Starting with Scumm V5, the blockname contains 4 bytes and the block size is BE including the 8 bytes for the header. Older games just have a 2 bytes blockname and the block size is in LE without the 6 bytes for the header.


<br>


= Global Scripts (SC or SCRP) =
== Global Scripts (SC or SCRP) ==


Global scripts are limited to 200 and stored in the '''LF''' or '''LFLF''' container. The id and the offset is stored in the ''directory of scripts'' in the game [[SCUMM/Index File|index file]].
Global scripts are limited to 200 and stored in the '''LF''' or '''LFLF''' container. The id and the offset is stored in the ''directory of scripts'' in the game [[SCUMM/Index File|index file]].
Line 21: Line 22:
  Script code        variable
  Script code        variable


= Local Scripts (LS or LSCR) =
== Local Scripts (LS or LSCR) ==


Local scripts are stored within a room. The first byte after the blockname contains the id of the script. IDs for local scripts always start at 200.
Local scripts are stored within a room. For games until version 6, the first byte after the blockname contains the id of the script. IDs for local scripts always start at 200.


  Block name        2 ("LS") or 4 ("LSCR") bytes
  Block name        2 ("LS") or 4 ("LSCR") bytes
Line 30: Line 31:
  Script code        variable
  Script code        variable


For v7 and v8 games the script id is stored in 2 bytes and starts with 2000.


= Room Entry Scripts (EN or ENCD) =
Block name        4 bytes ("LSCR")
Block size        4 bytes
ID                2 bytes
Script code        variable
 
== SCUMM V1 and V2 Room Entry and Exit Scripts ==
 
In SCUMM V1 and V2, the entry and exit scripts are part of [[SCUMM/Technical_Reference/Room resources#Header|the room resource]].
 
== SCUMM V3+ Room Entry Scripts (EN or ENCD) ==


This block contains special code when a room is entered.  
This block contains special code when a room is entered.  
Line 39: Line 50:
  Script code        variable
  Script code        variable


 
== SCUMM V3+ Room Exit Scripts (EX or EXCD) ==
= Room Exit Scripts (EX or EXCD) =


This block contains special code when the player leaves a room  
This block contains special code when the player leaves a room  
Line 48: Line 58:
  Script code        variable
  Script code        variable


== SCUMM V3 and V4 Object Scripts (OC) ==
In Version 3 and 4 the code can be found in the '''OC''' block:
OC
  Block size        4 bytes (LE)
  Block name        2 bytes ("OC")
  Object ID        2 bytes (LE)
  unknown          1 byte
  x pos            1 byte
  y pos, par. state 1 byte
  image width / 8  1 byte
  parent            1 byte
  walk_x            2 bytes (LE)
  walk_y            2 bytes (LE)
  height, actor dir 1 byte
  name offset      1 byte
  offset table      variable {
    verb            1 byte (0xFF is default)
    offset          2 bytes
  }
  table end        1 byte (must be 0x00)
  object name      null-terminated string
  object code      variable
This block contains all object data except for the actual image bitmap. Compare this to V5+ objects, where metadata is split into seperate CDHD and OBNA blocks.
Image width is given in strips, which are 8 pixels wide. The high bit of y pos is used to store the parent's state (0 or 1). Both x pos and y pos will be multiplied by 8 by the interpreter. The lower three bits (mask 0x07) of height are used to store actor dir. Name offset is the absolute offset of object name (or, if you prefer, the position after table end).
The offset table is a variable block like that used in the VERB block in later games, which contains the verb identifier (1 byte) and the absolute offset (2 bytes). The table end is marked with 0x00. Next is the object's name, which is a standard null-terminated string. After this follows the actual object code. Note that unlike other script types, because there are multiple entry points (one for each supported verb), there are also multiple exit points (or "stopObjectCode" instructions).


= Object Scripts (OBCD in V5+, OC in V3/4) =
== SCUMM V5+ Object Scripts (OBCD) ==


These are scripts that correspond to VERB actions. VERBs are predefined activities at the bottom of the screen, e.g. "Open", "Look", "Give" etc. For each named object in a room, the game designer could define responses to the players actions. Starting with version 5, the whole code can be found in an [[Object resources|Object Resource]].  
These are scripts that correspond to VERB actions. VERBs are predefined activities at the bottom of the screen, e.g. "Open", "Look", "Give" etc. For each named object in a room, the game designer could define responses to the players actions. A single VERB block contains the code for all possible player actions on the object. Starting with version 5, the whole code can be found in an [[Object resources|Object Resource]].  


  OBCD     
  OBCD     
Line 66: Line 107:
       Block name    4 bytes ("VERB")
       Block name    4 bytes ("VERB")
       Block size    4 bytes
       Block size    4 bytes
       offset table  variable
       offset table  variable {
      verb          1 byte (0xFF is default)
      verb          1 byte (0xFF is default)
      offset        2 bytes
      offset        2 bytes
       table end    1 byte(must be 0)
      }
       table end    1 byte (must be 0x00)
       object code  variable
       object code  variable


In Version 3 and 4 the code can be found in the '''OC''' block:
    OBNA
 
      Block name   4 bytes ("OBNA")
OC
      Block size   4 bytes
   Block size        4 bytes
      object name   null-terminated string
  Block name        2 bytes ("OC")
   Object ID        1 byte (?)
  unknown          12 bytes
 
Now starts a variable block similar to the VERB block in later games, which contains the verb identifier (1 byte) and the offset. The table end is marked with 0.
 
  verb              1 byte
  offset            2 bytes
  table end          1 byte (must be 0)
  object name       0 terminated string
  object code        variable

Latest revision as of 13:48, 16 November 2021

SCUMM/Technical ReferenceScript resources


Scripts control the internal logic of the games. They exist in different flavours:

  • global scripts
  • local scripts
  • room entry scripts
  • room exit scripts
  • object scripts

Starting with Scumm V5, the blockname contains 4 bytes and the block size is BE including the 8 bytes for the header. Older games just have a 2 bytes blockname and the block size is in LE without the 6 bytes for the header.


Global Scripts (SC or SCRP)

Global scripts are limited to 200 and stored in the LF or LFLF container. The id and the offset is stored in the directory of scripts in the game index file.

Block name         2 ("SC") or 4 ("SCRP") bytes
Block size         4 bytes 
Script code        variable

Local Scripts (LS or LSCR)

Local scripts are stored within a room. For games until version 6, the first byte after the blockname contains the id of the script. IDs for local scripts always start at 200.

Block name         2 ("LS") or 4 ("LSCR") bytes
Block size         4 bytes
ID                 1 byte
Script code        variable

For v7 and v8 games the script id is stored in 2 bytes and starts with 2000.

Block name         4 bytes ("LSCR")
Block size         4 bytes
ID                 2 bytes
Script code        variable

SCUMM V1 and V2 Room Entry and Exit Scripts

In SCUMM V1 and V2, the entry and exit scripts are part of the room resource.

SCUMM V3+ Room Entry Scripts (EN or ENCD)

This block contains special code when a room is entered.

Block name         2 ("EN") or 4 ("ENCD") bytes
Block size         4 bytes
Script code        variable

SCUMM V3+ Room Exit Scripts (EX or EXCD)

This block contains special code when the player leaves a room

Block name         2 ("EX") or 4 ("EXCD") bytes
Block size         4 bytes
Script code        variable

SCUMM V3 and V4 Object Scripts (OC)

In Version 3 and 4 the code can be found in the OC block:

OC
  Block size        4 bytes (LE)
  Block name        2 bytes ("OC")
  Object ID         2 bytes (LE)
  unknown           1 byte
  x pos             1 byte
  y pos, par. state 1 byte
  image width / 8   1 byte
  parent            1 byte
  walk_x            2 bytes (LE)
  walk_y            2 bytes (LE)
  height, actor dir 1 byte
  name offset       1 byte
  offset table      variable {
   verb             1 byte (0xFF is default)
   offset           2 bytes
  }
  table end         1 byte (must be 0x00)
  object name       null-terminated string
  object code       variable


This block contains all object data except for the actual image bitmap. Compare this to V5+ objects, where metadata is split into seperate CDHD and OBNA blocks.

Image width is given in strips, which are 8 pixels wide. The high bit of y pos is used to store the parent's state (0 or 1). Both x pos and y pos will be multiplied by 8 by the interpreter. The lower three bits (mask 0x07) of height are used to store actor dir. Name offset is the absolute offset of object name (or, if you prefer, the position after table end).

The offset table is a variable block like that used in the VERB block in later games, which contains the verb identifier (1 byte) and the absolute offset (2 bytes). The table end is marked with 0x00. Next is the object's name, which is a standard null-terminated string. After this follows the actual object code. Note that unlike other script types, because there are multiple entry points (one for each supported verb), there are also multiple exit points (or "stopObjectCode" instructions).

SCUMM V5+ Object Scripts (OBCD)

These are scripts that correspond to VERB actions. VERBs are predefined activities at the bottom of the screen, e.g. "Open", "Look", "Give" etc. For each named object in a room, the game designer could define responses to the players actions. A single VERB block contains the code for all possible player actions on the object. Starting with version 5, the whole code can be found in an Object Resource.

OBCD    
  Block name       4 bytes ("OBCD")
  Block size       4 bytes
   CDHD
     Block name    4 bytes ("CDHD")
     Block size    4 bytes (25)
     obj id        2 bytes
     ...           see Object Resource
   VERB
     Block name    4 bytes ("VERB")
     Block size    4 bytes
     offset table  variable {
      verb          1 byte (0xFF is default)
      offset        2 bytes
     }
     table end     1 byte (must be 0x00)
     object code   variable
   OBNA
     Block name    4 bytes ("OBNA")
     Block size    4 bytes
     object name   null-terminated string