SCUMM/Technical Reference/Room resources

From ScummVM :: Wiki
Jump to navigation Jump to search

SCUMM V1

A room resource is located as the first chunk in a LFL File.

Header

The room resource starts with a 28 bytes header containing the following information:

LocationFormatData
0x00UInt16LESize of the room resource chunk
0x02???Unknown
0x04UInt16LERoom width in tiles (always 0x1C or 0x3C)
0x06UInt16LERoom height in tiles (always 0x10 on NES)
0x08???Unknown (Always 0 on NES)
0x0aUInt16LEOffset to 1 byte for the tileset index, followed by 16 bytes of palette data, and then the RLE encoded nametable data (NES)
0x0cUInt16LEOffset to the RLE encoded attribute table (NES)
0x0eUInt16LEOffset to the mask flag location. A value of 0x01 is followed by the RLE encoded mask data, otherwise 0x01.
0x10???Unknown (On NES both these values are equal)
0x12???Unknown
0x14UInt8Number of objects in room
0x15UInt8Offset to number of boxes location
0x16UInt8Number of sounds in room (Always 0 on NES)
0x17UInt8Number of scripts in room
0x18UInt16LEOffset to exit script location
0x1aUInt16LEOffset to entry script location

All offsets are relative to the start of the chunk.

Note: Because of the following constraints:

  • Offset to box number location is stored as an UInt8, thus must be within the first 255 bytes of the chunk
  • The header takes 28 bytes
  • The combined size of object image and object code offsets is 4 bytes per object

The total number of objects per room must be less than 57: 

(256 - 28) / 4 = 57

Content

Object image offsets

From byte 0x1c starts the offsets to object images, 2 bytes per object:

LocationFormatData
0x1cUInt16LEOffset to object 1 image location
0x1eUInt16LEOffset to object 2 image location
...UInt16LERepeated objNum times

On the NES this is RLE encoded nametable and attribute table data based on the height and width of the object. The nametable data is encoded per row. These graphical updates are triggered in SCUMM by setState08 and clearState08. Objects that have no state changes must still have an entry and can point arbitrarily.

Object code offsets

Next starts the list of offsets to each object's data:

LocationFormatData
0x1c + objNum * 2UInt16LEOffset to object 1 content location
0x1c + objNum * 2UInt16LEOffset to object 2 content location
...UInt16LERepeated objNum times

See table below for a description of the object data.

Unknown data

At this point there are 4 bytes of unknown data on the NES.

Number of boxes

The number of boxes (boxNum) in the room is located at the offset specified in the header.

LocationFormatData
Offset to number of boxesUInt8Number of boxes in room

Note: Some LFL files have unknown data between the last object code offset and the boxes number offset location. For most files however, the data is contiguous.

Boxes

If the number of boxes is greater then 0 then 1 byte later starts the boxes payload. Each box has 8 bytes described as follows:

Relative locationFormatData
0x00UInt8uy
0x01UInt8ly
0x02UInt8ulx
0x03UInt8urx
0x04UInt8llx
0x05UInt8lrx
0x06UInt8mask
0x07UInt8flags

The flags byte has various uses including:

Flag ValueMeaning
0x08X flip
0x10Y flip
0x20Unused in V1
0x40Locked
0x80Invisible

Boxes matrix table

The box matrix payload starts with an offset table that points to the beginning of each box's data. It is boxNum wide.

Box matrix

Immediately following the last box's data is the box matrix which determines how the boxes are connected.

There are a minimum of boxNum * boxNum entries read as UInt8. Each entry consists of at least two pairs of three bytes which determine how the boxes connect. The table allows more values to be used in each entry if necessary. Example pseudo code: 

boxMatrix = [
[1, 1, 1,  1, 1, 0],
[1, 2, 2,  2, 2, 1],
[1, 2, 3,  3, 3, 2],
[2, 2, 3,  4, 4, 3],
[3, 3, 3,  4, 5, 4],
[4, 4, 4,  4, 5, 5]
];

function nextBox (from, to)
{
  var box = boxMatrix[from];
  if (box[0] <= to && to <= box[1])
    return box[2];
  if (box[3] <= to && to <= box[4])
    return box[5];
  return -1;
}

Tileset index

The two bytes of room data at 0x0a point to the tileset index which is used to look up the tileset details in a separate table. The tileset table provides the bank and memory offset for the given tileset.

Palettes

One byte later starts the background palettes for a total of 16 bytes.

Nametable data

Next starts the RLE encoded nametable data (NES). The room height and width at bytes 0x06 and 0x04 of the room data are used to determine how much data is decoded.

Attribute table data

The two bytes at 0x0c of the room data point to the RLE encoded attribute table (NES). The amount of data is decoded according to the room height and width.

Mask Flag

Byte 0x0e of the room data points to this mask flag. It has a value of 0x00 or 0x01.

Mask data

If the mask flag is 0x01 then the RLE encoded mask data is next. This is bitmap data where each bit corresponds to a single tile, so a single byte covers a row of 8 tiles. A bit value of 1 = masked (background priority), and 0 = unmasked (sprite priority). The bits in each byte are reversed (or read right to left) before they are applied.

Object image data

Next starts the data that is pointed to by the object image offsets beginning at byte 0x1c in the room data. This is RLE encoded nametable and attribute table data for each object. The amount of data for each object is based on the height and width of the object. The data is RLE encoded per row. These graphical updates are triggered in SCUMM by setState08 and clearState08.

Object code

The object code section has the following structure starting at its corresponding object code offset:

Object code header

Relative locationFormatData
0x00UInt8Size of the object code chunk
0x02???Unknown (Always 0 on NES)
0x03???Unknown (Always 0 on NES)
0x04UInt16LEThe object number (used to reference object in scripts). Because of the way the data is stored in-game, the object number must be 255 (0xFF) or less in order to be picked up.
0x06??Unknown (Always 0 on NES)
0x07UInt8X position of object
0x08UInt8Object parent state + Y position of object (0xSSSYYYYY). Parent state is always 0x04 if present and is used in combination with the Object parent value at 0x0a to hide objects behind doors (e.g. items in the refrigerator).
0x09UInt8Object width in tiles
0x0aUInt8Object parent
0x0bUInt8Walk to X position
0x0cUInt8Preposition + Walk to Y position (0xPPPYYYYY). Possible preposition values are: 0x001 = in, 0x010 = with, and 0x011 = on.
0x0dUInt8Object height in tiles + Actor facing direction (0xHHHHHDDD). Possible facing values are: 0x100 = left, 0x101 = right, 0x110 = front (facing the player), and 0x111 = back (facing away from the player).
0x0eUInt8Offset to object name

Note: The object code data starts at byte 15. The verb-script pairs terminate with a null byte (0x00). This means that the object name offset value is always an even number, 16 or above.

Object code content

Object code content contains 3 optional sections, in this order:

  • 0 or more pairs of verb id and script offsets
  • The name of the object
  • 0 or more object scripts consisting of SCUMM bytecode
Object script offsets

Starting at byte 15, two UInt8 values are read at a time.

The first value is a the verb ID and the second value is an offset to the beginning of the object script. Multiple verbs can have the same offset. The verb IDs are as follows:

Verb IDMeaning
0x01Open
0x02Close
0x03Give
0x04Turn On
0x05Turn Off
0x06Fix (Unused)
0x07New Kid (Unused)
0x08Unlock
0x09Push
0x0APull
0x0BUse
0x0CRead
0x0DWalk To
0x0EGet
0x0FWhat is (Unused)
0xFFAll

This part ends with 0x00.

Object name

The object name starts at the offset specified in byte 0x0e of the object data. Each character is read until a 0x00 value is found.

Object scripts

The object scripts are composed of SCUMM bytecode. Each object script ends with 0x00 (SCUMM opcode for stopObjectCode()).

Retrieved from "https://wiki.scummvm.org/index.php?title=SCUMM/Technical_Reference/Room_resources&oldid=41295"