Events play a central role in Ecstatica. This article describes the content of event objects.
Formal Decription
Event objects in memory
Event instances contain a couple of arguments as well as a class id. The class id is required to process the event accordingly.
| Offset in Bytes | Property | Purpose |
|---|---|---|
| 0x0h | Index Arg | The main argument of the event. Normally it points to a specific actor, part, script, scene, triangle, etc. The respective object, the event points on, is identified by its index in a global array. |
| 0x2h | Event Class Id | The Class Id of the event. The different types available are listed in the table below. |
| 0x4h | Arg 1 | 1st of three additional arguments of the event. In the case of a vector event, this argument contains the x component. |
| 0x6h | Arg 2 | 2nd of three additional arguments of the event. In the case of a vector event, this argument contains the y component. |
| 0x8h | Arg 3 | 3rd of three additional arguments of the event. In the case of a vector event, this argument contains the z component. |
| 0x10h | Next | Pointer to another event instance, used to control linked lists of event instances. |
Event objects in FANT files
| Offset in Bytes | Endianess | Property |
|---|---|---|
| 0x0h | Big Endian | Event Class Id |
| 0x2h | Big Endian | Index Arg |
| 0x4h | Big Endian | Arg 1 |
| 0x6h | Big Endian | Arg 2 |
| 0x8h | Big Endian | Arg 3 |
Event classes
In an object-oriented sense, all event classes are instances of one single event metaclass with a fixed set of properties, valid for all event classes. The instance variables of the event class can be found in the chapter about event objects above. The event classes have additional class-level variables
| Property | Purpose |
|---|---|
| Unblockable | If set to 1, the event is processed even if event handling is blocked |
| Index Arg Type | If set to 0x10h, Index Arg contains a part index, if set to 0x20h, Index Arg contains a triangle index, if set to 0x40h, Index Arg contains a point index |
| Priority | Event instances linked to a key are always ordered according to the priority property of their event class |
The following Table lists event types and their properties. It contains the following columns:
- Class Id is the unique id of the respective event class
- Name Name is a string used to identify the event type in debug messages of the Ecstatica engine. Not all events have an "official" name. In those cases, we have chosen one (the relevant names are marked by a footnote)
- Index Arg* is the type of the index argument property. See the convention for field types below.
- Arg 1-3** are the arguments 1-3 of the event. See the convention for field types below.
- Blockable is 1, if the "Unblockable" property of the event class is 0 and vice versa.
- Prio The priority property of the event class
- Regular Event If yes, the event is regularly handled by the Ecstatic engine. If not, this is propably a pseudo event (todo: link to event article).
- Can be interpolated If yes, the target state described by the event is not achieved by instantaneously changing the game state but via linear interpolation of a state variable.
Field types in the table below are described by key words. Uppercase key words like "Part", "Actor", "Scene" denote that the event argument contains a globally valid index identifying an object of the respective type. The type can be prefixed by "lcl", which means, that this is an object index valid only within another object. e.g. in the ADD_PART event, the index argument specifies the global index of an existing part object to append the new part object to. Arg 1 of this event specifies the local index of the parent part object, under which the new part object resides. Another special case is the entry "Code +1" which means, that the content of the event argument has to be decremented by 1 to get the actual global index of the code object. Lowercase key words denote the purpose of a field, e.g. the event ROTATE contains 3 euler angles.
| Class Id | Name | Index Arg | Arg 1 | Arg 2 | Arg 3 | Blockable | Prio | Regular Event | Can be interpolated |
|---|---|---|---|---|---|---|---|---|---|
| 0 | NO_EVENT | - | - | - | - | 0 | 0 | ||
| 1 | ROTATE | Part | rotation x | rotation y | rotation z | 1 | 0 | yes | yes |
| 2 | OFFSET | Part | offset x | offset y | offset z | 1 | 0 | yes | yes |
| 3 | COLOUR | Part | colour idx? | - | - | 0 | 0 | yes | no |
| 4 | VECTOR1 | Part | halfaxes x | halfaxes y | halfaxes z | 1 | 0 | yes | yes |
| 5 | VECTOR2 | Part | centre_lcl x | centre_lcl y | centre_lcl z | 0 | 0 | yes | yes |
| 6 | VECTOR3 | Part | - | - | - | 0 | 0 | no | |
| 7 | ADD_PART | Part | lcl Part | - | - | 0 | 0 | yes | no |
| 8 | ADD_THING | - | Actor | - | - | 0 | 1 | yes | no |
| 9 | TYPE | Part | type | - | - | 0 | 0 | yes | no |
| 10 | ADD_PART_TO_THING | - | lcl Part | - | - | 0 | 0 | yes | no |
| 11 | PSEUDO_ACTION | - | - | - | - | 0 | 0 | no | |
| 12 | PSEUDO_KEY | - | - | - | - | 0 | 0 | no | |
| 13 | DISP_PNT | Part | x | y | z | 0 | 0 | yes | yes |
| 14 | FLAGS | Part | flags to set | flags to clear | ? | 0 | 0 | yes | no |
| 15 | MOVE_ACT | Actor | ? | Action idx | ? | 0 | 0 | no | |
| 16 | RAND_ACT | Actor | - | - | - | 0 | 0 | no | |
| 17 | RAND_INFO | Actor | - | - | - | 0 | 0 | no | |
| 18 | ROTATE_THING | - | delta x angle | delta y angle | delta z angle | 0 | 0 | yes | no |
| 19 | MOVE_THING | - | delta xpos | delta ypos | delta zpos | 0 | 0 | yes | no |
| 20 | START_POSITION | - | x | y | z | 0 | 0 | yes | no |
| 21 | THING_FLAGS | - | flags | - | - | 0 | 0 | yes | no |
| 22 | SCRIPT_MOVE | Part | xpos | ypos | zpos | 1 | 1 | yes | no |
| 23 | SCRIPT_TURN | Part | xangle | yangle | zangle | 1 | 1 | yes | no |
| 24 | SPAWN_ACTION | - | Action | upper 8 Bit of ? | lower 8 Bit of ? | 0 | 0 | yes | no |
| 25 | PSEUDO_SCENE | Scene | View | ? | Code | 0 | 0 | no | |
| 26 | PSEUDO_SCRIPT | - | ? | ? | Actor | 0 | 0 | no | |
| 27 | NEXT_SCENE | ? | - | - | - | 0 | 0 | no | |
| 28 | ANCHOR_PART | Part | - | - | - | 0 | -1 | yes | no |
| 29 | LOOSEN_JOINT | Part | - | - | - | 0 | -1 | yes | no |
| 30 | UNLOOSEN_JOINT | Part | - | - | - | 0 | -1 | yes | no |
| 31 | POSITION | Part | origin x | origin y | origin z | 1 | 0 | yes | yes |
| 32 | 2_PART_LIMB | Part | - | - | - | 0 | -1 | yes | no |
| 33 | FIX_PART | Part | - | - | - | 0 | -1 | yes | no |
| 34 | UNFIX_PART | Part | - | - | - | 0 | -1 | yes | no |
| 35 | UNMAKE_LIMB | Part | - | - | - | 0 | -1 | yes | no |
| 36 | REORIENT_THING | ? | ? | ? | ? | 0 | -1 | yes | no |
| 37 | PSEUDO_ADJUNCT | Adjunct | ? | ? | ? | 1 | 0 | no | |
| 38 | PSEUDO_ADJUNCT_2 | Adjunct | ? | ? | ? | 1 | 0 | no | |
| 39 | ABSOLUTE_POS | Part | - | - | - | 0 | 0 | yes | yes |
| 40 | ABSOLUTE_ROT | Part | rotation x | rotation y | rotation z | 0 | 0 | yes | yes |
| 41 | ADD_POINT | Part | lcl Point | - | - | 0 | 0 | yes | no |
| 42 | OFFSET_POINT | Point | delta x | delta y | delta z | 0 | 0 | yes | yes |
| 43 | ADD_TRIANGLE | Triangle (new) | point1 idx | point2 idx | point3 idx | 0 | 0 | yes | no |
| 44 | COLOUR_TRIANGLE | Triangle | color front | color back | 0 | 0 | yes | no | |
| 45 | TRIANGLE_FLAGS | Triangle | ? | ? | ? | 0 | 0 | yes | no |
| 46 | INTERACT | Part | Interaction Type | Depending on Type | - | 0 | -1 | yes | no |
| 47 | ? | 0 | 0 | no | |||||
| 48 | POINT_TO_POINT | Part | lcl Point | 0 | 0 | yes | no | ||
| 49 | HELD_OFFSET | - | x | y | z | 0 | 0 | yes | no |
| 50 | HELD_ROTATE | - | x | y | z | 0 | 0 | yes | no |
| 51 | BACKGROUND | - | isForeground(0/1) | - | - | 0 | -1 | yes | no |
| 52 | PSEUDO_SCENE_2 | ? | - | - | - | 0 | no | ||
| 53 | PSEUDO_REPERTOIRE | Repertoire | - | - | - | 0 | no | ||
| 54 | REP_ENTRY | ? | index in Words | word value | - | 0 | no | ||
| 55 | ACTOR_REP | - | Repertoire | 2AA42 | - | 0 | yes | no | |
| 56 | DEF_ROTATE | Part | ? | ? | ? | -1 | yes | no | |
| 57 | DEF_OFFSET | Part | ? | ? | ? | -1 | yes | no | |
| 58 | DEF_VECTOR1 | Part | ? | ? | ? | -1 | yes | no | |
| 59 | DEF_VECTOR2 | Part | ? | ? | ? | -1 | yes | no | |
| 60 | DEF_COLOUR | Part | ? | ? | ? | -1 | yes | no | |
| 61 | DEF_FLAGS | Part | ? | ? | ? | -1 | yes | no | |
| 62 | DEF_POSITION | Part | ? | ? | ? | -1 | yes | no | |
| 63 | CUT_PART | Part | ? | ? | ? | 2 | yes | no | |
| 64 | HELD_OFF_LEFT | - | x | y | z | 0 | no | ||
| 65 | HELD_ROT_LEFT | - | x | y | z | 0 | yes | no | |
| 66 | THING_CODE | ? | Code + 1 | Code + 1 | Code + 1 | 0 | yes | no | |
Scope
Assumed
- Most of the information is propably also valid for Ecstatica 2
Tested
- This information is valid for Ecstatica 1
