Difference between revisions of "Behavior"

From DoomWiki.org

[checked revision][checked revision]
m (Consistency fix: <tt>command line parameter</tt>)
(ACS0 bytecode format)
 
(4 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{Doom level format}}
 
{{Doom level format}}
 +
The '''BEHAVIOR''' [[lump]] is part of the [[Hexen]] map format, and stores the {{wp|bytecode}} of compiled [[ACS]] scripts, which are output created by the [[ACC]] {{wp|compiler}} tool. Given the difference in records size between the Doom and Hexen format for [[Thing|THINGS]] and [[Linedef|LINEDEFS]] lump, the presence or absence of a BEHAVIOR lump also serves to identify the format of the entire map in ports which support several different formats.
 +
 
==Lump structure==
 
==Lump structure==
 +
The BEHAVIOR lump contains compiled [[ACS]] scripts for the map. There exist three different formats for BEHAVIOR lumps, the original Hexen one is identified by a four-byte header of ACS\0 (0x41435300); ZDoom also uses two different "enhanced" formats identified by ACSE (0x41435345) and ACSe (0x41435365).
 +
 +
Behavior lumps are compiled with [[ACC]]. The version of ACC maintained by [[Marisa Heit (Randi)]] needs the <tt>-h</tt> command line parameter to produce ACS\0 bytecode, since many of the ACS functions it supports are only available in the ZDoom formats.
 +
 +
The [[Eternity Engine]]'s ACS VM can now interpret all three bytecode formats.
 +
 +
===ACS0 bytecode format===
 +
{| {{prettytable}}
 +
|+ Lump header
 +
|-
 +
! Offset !! Size !! C99 data type !! Field name !! Purpose
 +
|-
 +
| 0 || 4 || int32_t || marker || Must be {{c|0x41435300}} ({{c|"ACS\0"}})
 +
|-
 +
| 4 || 4 || int32_t || infoOffset || Offset to script directory from start of lump<ref group="notes" name="validation"/>
 +
|}
 +
 +
{| {{prettytable}}
 +
|+ Script directory
 +
|-
 +
! Offset !! Size !! C99 data type !! Field name !! Purpose
 +
|-
 +
| 0 || 4 || int32_t || ACScriptCount  || Number of scripts in directory; 0 if empty<ref group="notes" name="ACScriptCount"/>
 +
|-
 +
| 4 || 12 * ACScriptCount ||  || info[] || Array of script information structures
 +
|-
 +
| 4 + 12 * ACScriptCount || 4 || int32_t || ACStringCount || Number of strings in string table
 +
|-
 +
| 8 + 12 * ACScriptCount || 4 * ACStringCount || || strings[] || Array of string table entries
 +
|}
  
The '''BEHAVIOR''' lump originates from the [[Hexen]] map format and is never found in the other games. Given the difference in records size between the Doom and Hexen format for [[Thing|THINGS]] and [[Linedef|LINEDEFS]] lump, the presence or absence of a BEHAVIOR lump serves to identify the format of the entire map in ports which support several different formats.
+
{| {{prettytable}}
 +
|+ Script information structure
 +
|-
 +
! Offset !! Size !! C99 data type !! Field name !! Purpose
 +
|-
 +
| 0 || 4 || int32_t || number || Script number
 +
|-
 +
| 4 || 4 || int32_t || offset || Offset to bytecode instruction stream from start of lump
 +
|-
 +
| 8 || 4 || int32_t || argCount || Number of arguments to script (only 0 to 3 are valid)<ref group="notes" name="argCount"/>
 +
|}
  
The BEHAVIOR lump contains compiled [[ACS]] scripts for the map. There exist three different formats for BEHAVIOR lumps, the original Hexen one is identified by a four-byte header of ACS\0 (0x41435300); ZDoom also uses two different "enhanced" formats identified by ACSE (0x41435345) and ACSe (0x41435365).
+
{| {{prettytable}}
 +
|+ String table entry
 +
|-
 +
! Offset !! Size !! C99 data type !! Field Name !! Purpose
 +
|-
 +
| 0 || 4 || int32_t || offset || Offset to null-terminated string data from start of lump
 +
|}
 +
 
 +
====Notes====
 +
<references group="notes">
 +
<ref name="validation">Offset validation for all offset fields is minimal in the vanilla Hexen executable; invalid values may cause undefined behavior.</ref>
 +
<ref name="ACScriptCount">Lump cannot be empty in vanilla Hexen; a map with no scripts must have a valid header containing 0 in this field instead. Program behavior is undefined otherwise.</ref>
 +
<ref name="argCount">Negative values or values greater than 3 may cause undefined behavior in the vanilla Hexen executable.</ref>
 +
</references>
  
Behavior lumps are compiled with [[ACC]]. The version of ACC maintained by [[Randy Heit]] needs the <tt>-h</tt> command line parameter to produce ACS\0 bytecode, since many of the ACS functions it supports are only available in the ZDoom-exclusive formats.
+
===Instructions===
 +
{{main|ACS0 instruction set}}
  
 
==See also==
 
==See also==
 
* [[ACS]]
 
* [[ACS]]
 +
* [[ACC]]
 +
* [[DEACC]]
 +
 +
==External links==
 +
* {{zdoomwiki|BEHAVIOR}}
 +
 
[[Category:Doom engine]]
 
[[Category:Doom engine]]
 
[[Category:WAD lumps]]
 
[[Category:WAD lumps]]

Latest revision as of 00:45, 16 January 2022

Doom level format

Extensions:

The BEHAVIOR lump is part of the Hexen map format, and stores the bytecode of compiled ACS scripts, which are output created by the ACC compiler tool. Given the difference in records size between the Doom and Hexen format for THINGS and LINEDEFS lump, the presence or absence of a BEHAVIOR lump also serves to identify the format of the entire map in ports which support several different formats.

Lump structure[edit]

The BEHAVIOR lump contains compiled ACS scripts for the map. There exist three different formats for BEHAVIOR lumps, the original Hexen one is identified by a four-byte header of ACS\0 (0x41435300); ZDoom also uses two different "enhanced" formats identified by ACSE (0x41435345) and ACSe (0x41435365).

Behavior lumps are compiled with ACC. The version of ACC maintained by Marisa Heit (Randi) needs the -h command line parameter to produce ACS\0 bytecode, since many of the ACS functions it supports are only available in the ZDoom formats.

The Eternity Engine's ACS VM can now interpret all three bytecode formats.

ACS0 bytecode format[edit]

Lump header
Offset Size C99 data type Field name Purpose
0 4 int32_t marker Must be 0x41435300 ("ACS\0")
4 4 int32_t infoOffset Offset to script directory from start of lump[notes 1]
Script directory
Offset Size C99 data type Field name Purpose
0 4 int32_t ACScriptCount Number of scripts in directory; 0 if empty[notes 2]
4 12 * ACScriptCount info[] Array of script information structures
4 + 12 * ACScriptCount 4 int32_t ACStringCount Number of strings in string table
8 + 12 * ACScriptCount 4 * ACStringCount strings[] Array of string table entries
Script information structure
Offset Size C99 data type Field name Purpose
0 4 int32_t number Script number
4 4 int32_t offset Offset to bytecode instruction stream from start of lump
8 4 int32_t argCount Number of arguments to script (only 0 to 3 are valid)[notes 3]
String table entry
Offset Size C99 data type Field Name Purpose
0 4 int32_t offset Offset to null-terminated string data from start of lump

Notes[edit]

  1. Offset validation for all offset fields is minimal in the vanilla Hexen executable; invalid values may cause undefined behavior.
  2. Lump cannot be empty in vanilla Hexen; a map with no scripts must have a valid header containing 0 in this field instead. Program behavior is undefined otherwise.
  3. Negative values or values greater than 3 may cause undefined behavior in the vanilla Hexen executable.

Instructions[edit]

Main article: ACS0 instruction set

See also[edit]

External links[edit]