.DTE missions¶

Each of the 44 missions is one image: the ships it places, the globals it seeds, the triggers it arms, and the script they run.

sltool dte info <mission>        # counts and sizes
sltool dte sections <mission>    # the 27-entry directory
sltool dte ships <mission>       # placed ships and nav points
sltool dte triggers <mission>    # triggers, with the object whose slice holds each
sltool dte strings <mission>     # the string pool
sltool dte parts <mission>       # the script's named routines
sltool dte script <mission>      # every trigger block and part, disassembled
make check-missions              # parse all 44

Container¶

A mission inside a .HOG is RefPack compressed; one loose in missions\ is stored expanded. The archive's reader expands a member that begins 10 FB, but a loose file is read as it is, so it must be stored expanded (Missions). A retail install carries two loose missions, mission18.dte and mission25.dte, which begin 08 33 where their archive copies begin 10 FB. sltool hog expands members as it extracts.

Directory¶

The image opens with 27 entries of 8 bytes:

Capacity is fixed: a section's offset is the same in every mission built from the same template, and the count says how much of the reserved room is filled, so most missions are exactly the same size.

Sections 17 to 21 and 25 are empty in all 44 missions. The engine reads nothing of sections 9, 20, 21 and 23: the binder binds 21 into a local variable of its own, and the rest into globals nothing reads. Sections 9 and 23 hold records in some missions, likely the original editor's. Of the directory's 128 slots before the first section, at 0x400, the binder reads the first 27. Slot 27 holds the file's size in most missions and is unused in the rest, and slots 28 on are unused in all of them. Section 24 holds one word per command of the catalogue (dte.CommandFlags): command passes bit 0 of the word, inverted, to the engine before each call, and with the bit clear for_each_ship passes over the players' ships in a flight group, a squad's too (Script VM). command reads the low byte of the word the command's number places past the section's offset, whatever the section's count. In the 36 missions of the template each word has a bit for each of the command's parameters, the first's bit 0, save the words of ClearAI, SetPatrolRoute, SetTriggerState, SetAnyTriggerState, MovingShipFollowCurve and MovingShipBackupCurve, which are 0. The other missions either leave the section unused, at 0xFFFF, which lies inside section 1, so that its operands serve as the flags, or start it at the file's end, where the game reads past its copy of the file. Fix: OpenReliant takes no flags past the file. In every mission script_flags holds twice the count of section 6: one entry per script byte.

OpenReliant's mission name¶

This is OpenReliant's convention, not the game's. OpenReliant keeps a name for a mission in section 21, which the game binds but never reads and no shipped mission uses. OpenReliant shows it (openreliant missions); the game plays a mission with it as it plays any other, and a mission is complete without it.

The section's count is its size in bytes. It holds an 8-byte header, then the name:

OpenReliant reads a name only where the tag is ORMN, the version 1, and the name fits in the section; anything else in section 21 it leaves alone. Other mission tools may not keep the section when they write a mission out.

String pool¶

A run of NUL-terminated names, referenced by byte offset into the pool, not by index, which is why a u16 suffices: the pool reserves 65,535 bytes. Byte offsets resolve every ship name in all 44 missions, for example Player_Ship, (A1)Naginata, (WL)Viper's Coyote, Convoy Nav Point.

Ships¶

Stride 0x4C, one per placed object, nav points included.

When the mission's script starts, the engine clears the flags at 0x17 and sets every bit at 0x30. Destroying component n of the ship clears bit n & 31, and destroying the ship sets bit 0 of the flags and raises its Destroyed event, which it raises no more.

Each angle sits two bytes after its runtime copy, at 0x2C, 0x38 and 0x48. Every record holds angles within [-360, 360]. Positions are absolute, on the order of 10^7. in_flight_group reads the flight group byte.

Flight groups¶

Stride 0x14.

Binding the mission works out 0x09 and 0x0C, whatever the file holds (Missions).

Curves¶

Stride 0x44: a cubic Hermite spline from one of the mission's ships to another, which the director's camera flies along (The director's camera).

Its ships are points of kind 0x3E4 in the shipped missions, and the record holds their places as the mission placed them. The engine weighs each tangent ten times as it stands.

Objects¶

Ships, flight groups and squads each start with an object ID, and events name their subject by one. Section 7 is indexed by it:

In all 44 missions every ship's ID is unique within its mission and lands on a kind-0 entry, and the kind-1 and kind-2 entries correspond one for one to the flight groups and squads. The squad membership walk behind in_squad reads the kind: a flight group member is tested with in_flight_group, and a squad member recursively.

A squad's +0x08 is the index of its first record in section 13, or 0xFFFF. A membership record holds the member's object ID at +0, the owning squad's index at +4, and at +8 one of the member's components by index, or 0xFF for the whole member. A squad's records are consecutive. Members may be ships, flight groups, other squads, or single components of a ship, such as a capital ship's turrets.

Triggers¶

Stride 0x30. A trigger runs a block of script when an event it watches happens to its subject.

A trigger holds no subject: it sits in its subject's slice of the trigger list, in the object table. When an event happens to an object, trigger_match (0x0045CEA0) walks the slice and fires each trigger that is armed, has the event's condition and qualifier, and whose operands pass. Firing starts a thread at script + link * 2, unless a thread the trigger started is still running. An operand whose low halfword is 0xFFFF is not checked. The VM at run time describes the matching in full.

No trigger is in two slices, and a trigger in no slice can never fire. The condition decides which kinds of object a trigger can belong to, and every trigger agrees with its condition's.

Repeat mode 0 disarms the trigger when it fires, 1 never disarms it, and 2 disarms it when the counter at 0x19 runs out. A trigger whose operands fail a check stays as it is.

The qualifier must equal the event's. A ship's components, such as a capital ship's turrets and subsystems, are numbered among the components of its live object. A hit on one raises ShotAt with its index and, except for hits of one kind, ShotAt for the ship; destroying one raises Destroyed with its index. Every other event carries 0xFF, the subject itself.

An event on a ship is raised on its flight group and on the squads that hold it too. Destroyed on a flight group or squad goes ahead only once every member, or the member's named component, is destroyed; until then it fires only the group's triggers with repeat mode 1. For ShotAt the group's event carries the members' average damage value instead of the ship's. See Events.

Operands¶

Operand n goes with value n of the condition's events, such as the attacker of ShotAt or the distance of Proximity. The matcher checks an operand against the event's value when the condition marks the value as checked and the operand's low halfword is not 0xFFFF. It reads the operand by the value's kind mask (trigger_operand_value, 0x004530A0):

• A number is taken as it is.
• For a ship value, bit 0x2000 of the low halfword matches any of the players' ships: in a game of one, the player's.
• Anything else is a reference to a ship, a flight group or a squad, which the matcher turns into the address of its record, the form in which events pass them:

Any other tag in a checked operand is a fatal error: the game reports NULL entity referenced in script, or oh dear dear, and exits. sltool dte triggers lists each trigger's set operands under their values' labels, naming referenced objects by object ID.

Conditions¶

The engine's descriptor table at 0x4F6698 lists 35 conditions, named in the payload as TT_* constants; the last two are internal. A descriptor gives the kinds of object the condition applies to, the values its events carry, and the handlers that can veto them: see Conditions. The table lies just past the VM's dispatch table, followed by the lists of event values. make vm-conditions regenerates src/engine/vm/conditions.zig from the binary alone.

Script¶

Section 6 is the mission's bytecode: count * 2 bytes. The interpreter is a dispatch loop:

handler = table[code[ip]]      // 86 entries at 0x004F6350
ip += 1
continue while handler() != 0

Instruction set¶

71 opcodes: 0x02 to 0x07 and 0x14 to 0x55, less 0x50. The other entries of the 86-entry table are null. The condition descriptor table follows it, and its handler pointers look like further entries.

Five opcodes run the same handler as another and are the same operation: 0x24 and 0x23, 0x2B and 0x2A, 0x25 and 0x43, 0x32 and 0x2E, 0x55 and 0x47.

Every opcode's size and effect on the instruction pointer is read from its handler. The dispatcher calls a handler with ECX pointing at the cell holding the instruction pointer, already advanced past the opcode, and execution resumes wherever the handler leaves that cell. src/tools/tablegen reads the dispatch table from the binary, parses each handler from Ghidra's exported disassembly, and symbolically executes every path through it, tracking that cell. Paths must agree, or it reports the handler instead of guessing. Its output is src/engine/vm/opcodes.zig:

make ghidra-annotate   # define and name the handlers, among the rest
make ghidra-export-game
make vm-opcodes

Nothing calls a handler directly, so auto-analysis leaves most of them undefined; make ghidra-annotate defines each one from the committed opcode table.

The rest are a fixed size, with up to three operand bytes. Three carry their own length:

• 0x2A push_string (and 0x2B) takes a length byte that counts itself, pushes a pointer to the bytes after it, and steps over them. They are a NUL-terminated string, usually the name of a .wav of speech or a .ut cutscene: mission81 opens by cueing new_sim02.wav.
• 0x51 random_branch takes a count, a big-endian default target, then that many four-byte arms of big-endian target, threshold and a byte the engine never reads: 3 + 4n bytes. It rolls a number below 100 once (vm_random_branch, 0x0045C910) and takes the first arm whose threshold exceeds it, or the default, which an arm targeting 0xFFFF also takes. Its targets count from the opcode. This is the one encoding read by hand: its length depends on a byte the analysis cannot follow. The shipped missions' four have two arms each but room for ten: the first arm's code starts 44 bytes past the opcode, and the eight slots between hold stale bytes nothing reaches.

The analysis also records whether any path leaves the instruction pointer just past the operands. None does for 0x42 jump, so it never falls through. The transfers are classified by name, and a compile-time check rejects any transfer in the table without a classification:

The analysis cannot classify these itself: a call's only sequential path is its missing-part early-out, and return's path that leaves the pointer alone is the one that ends the thread, which it signals through its return value.

Opcodes¶

A stack machine. Names follow the handlers; a is the second value from the top, b the top.

A compile-time check in src/formats/dte.zig keeps the names and the derived table in step.

push_component tags the stack slot it fills with the component, in a list at 0x537420 that empties after every command. A command whose argument can be a component, such as DestroySubObject, ReplaceSubObject, SetPrimaryTarget or SetPlayerTarget, looks its arguments up there (vm_argument_component, 0x0045D950) to learn which component they name.

Control flow¶

• call_part takes a part index into the runtime part table (stride 0x74: block pointer at +0, argument count at +4), pushes the argument count, return address, frame base and block end, sets the frame base to stack - (4n + 16), and enters the block. return unwinds that, or ends the thread when the call depth is zero.
• spawn_part moves the part's arguments from this thread's stack to a new thread's, starts the new thread on the part, and carries on. At most 32 threads run at once.
• call_part_b and spawn_part_b do the same through the second part table, which serves section 18. command_b reads the second command table (0x004F3AD0), whose one command, Test_AI_Function, has no implementation, so the table counts none; the game calls a stub in its place that gives 1 (0x0045D800), so command_b pops the command's arguments and gives 1. Sections 17, 18 and 25 are empty in every shipped mission, and no script uses these three opcodes.
• branch_if_zero and jump take a big-endian displacement, counted from its own position. The handler loads it as an unsigned 16-bit number and adds it to the instruction pointer (vm_jump, 0x0045C2B0), so a branch only goes forward. The script's other two-byte operands, the wide indices of push_constant_wide and push_ship_wide, are big-endian too; the rest of the format is little-endian.

A thread keeps its block's end in [0x5373F0], which is where push_constant reads from.

Commands¶

command n calls entry n of the Executor catalogue at 0x4F0F50, which vm_install_commands (0x0045CE30) installs and counts up to the first entry with no implementation: 95 commands. An entry is 0x74 bytes and describes itself in the developers' words:

A parameter's kind mask says what it accepts. The bits are named from the labels that carry them:

make vm-commands regenerates src/engine/game/executor/commands.zig from the binary alone. Every command call in the 44 missions resolves.

Parts¶

Section 8 holds one 28-byte descriptor per part, a named routine. The loader expands it into the 256-entry runtime part table.

The loader sets block = script + start * 2, which fixes the halfword unit. In every mission the parts are in address order and contiguous, each one's start + extent being the next one's start, and the last ends at the end of section 6.

Missions carry their authors' names for them, as in mission1:

  #  offset  bytes  args  block  name
  0    1740    192     0    168  (F)launchfunction
  1    1932    160     0    144  (F)Jumping to CONVOY
  2    2092    252     0    220  (F)Arrival at CONVOY
  ...
 31    7524     28     0     20  <F>Objective window

Nearly every part takes no arguments. Every mission has exactly one start part, with names such as <F>Start Launch, (F)start or (F)setup: mission_script_start, 0x0045CBC0, runs it before arming the triggers.

The other parts run when a trigger or another part calls them. To check a late moment of a mission, openreliant --mission <number> --part <name> also runs a part, on a thread of its own as part_run (0x0045BAA0) runs the start part, once the player's launch is over (Configuration).

Blocks¶

A block is a u16 length, which counts its own two bytes, then instructions: the engine starts a thread at block + 2 with its limit at block + length. The instructions end with a return, padded with up to three bytes to a four-byte boundary.

Routines¶

The script section is a sequence of routines, each a block followed by its constant table: dwords that push_constant n reads, starting at the block's end. First come the blocks triggers run, then the parts:

• A part's extent covers its block and its constants.
• A trigger block's constants run to the next routine. In mission1 the trigger blocks start at bytes 0, 36, 72 and so on, and the first part follows the last of them.

In every mission this tiles the section exactly, with one trigger block for each trigger that can fire and has a link; a trigger that can fire may also have no link and run nothing. Each constant table is exactly as long as the highest index its block pushes, rounded up to 8 bytes; the filler dword that rounding adds is not read.

sltool dte script <mission>    # every routine, with its constants

sltool dte script follows control flow from each block's entry rather than sweeping, because jump, return and random_branch never fall through, and shows the value behind each push_constant, the name of each command, and the part, ship or global an index names. Every routine disassembles completely, but for the unused arm slots of the four random_branches. The first block of mission1, which its first trigger runs, calls one of two parts depending on a global:

0 to 36: trigger 0
       2  22 01       call_part   1  (F)Jumping to CONVOY
       4  21 17       command   InterruptTriggerCode
       6  27 00       push_global   0  (GV)convoykilled
       8  28 00       push_constant   = 1
      10  02          equal
      11  24 00 07    branch_if_zero_alt   -> 19 if zero
      14  22 15       call_part   21  (F)GO HOME (Total Loss)
      16  42 00 04    jump   -> 21
      19  22 18       call_part   24  (F)Jumping to Sherman
      21  21 17       command   InterruptTriggerCode
      23  32 01       push_byte   1
      25  43          return
  constants: 1 220332040

The links of the triggers no slice holds are never followed, and most of them do not point at a block.

Open¶

• What the qualifier byte selects.

Writing¶

dte/write.zig writes a mission file laid out as 36 of the shipped missions are, mission1 among them: a directory of 128 slots, 0x400 bytes, each section at the same offset with the same room up to the next, and 850,919 bytes in all. The directory's 28th slot holds the file's size, and the rest are unused, as in those missions; every entry carries the flags 15. Section 21 has no room there, starting where section 22 does, so OpenReliant's name goes after the template's end, which a loose file's buffer of 0xFA000 bytes still holds.

A section's records are its count times its stride: bytes for the string pool, the script flags and OpenReliant's name, halfwords for the scripts, and the records' sizes for the rest. The strides of sections 9, 11 and 23, 4, 4 and 2 bytes, are Unverified: the engine reads nothing of 9 and 23, and 11 holds one record in every mission. Section 20's is not known, and no mission uses it.

sltool dte check <mission> writes a mission again and checks what comes back. The 36 missions of the template, written again from their sections' whole rooms, stale bytes and all, come back byte for byte. Every mission, written again from its records alone, reads back the same records.

A mission of OpenReliant's making holds what the template's missions hold: its section 24 is theirs (write.template.command_flags), and its records carry the values most of theirs carry where their fields are not known. Mission 0, the sandbox, is written so by the build (mission0.zig).

Writing the script¶

dte/assemble.zig builds a routine as the shipped scripts are built: the block's length word, which counts itself, the instructions, and zeros to a four-byte boundary; then the constant table, each constant once in the order first pushed, and zeros to an eight-byte boundary. Labels stand for the branches' targets: a branch's displacement counts from its own position and a random_branch's targets from its opcode, both big-endian, and a branch backwards is refused, since the engine would take it 64 KiB forward. push_string's length byte counts itself and the NUL after the text.

Assembled again from its disassembly, every routine of the 44 missions comes back the same, but for the padding after its last instruction, which in the shipped missions holds stale bytes, and the three routines that hold unused arm slots of a random_branch.

Mission source groundwork¶

Mission Source v1 defines a YAML tool input that compiles to a standard .DTE. The first implemented slice is source identity and typed symbol resolution (#609).

dte/source.zig provides Symbols(Record), a table for one collection of existing format records or source records. Each entry has an explicit source id and its record. IDs match [A-Za-z_][A-Za-z0-9_-]* and are unique within that collection. They are independent of display names, original object IDs and binary offsets.

Reference(Record) identifies the collection's record type. Resolution uses the selected table, so equal IDs in different collections or script banks do not conflict. There is no separate list of supported record kinds. Adding fields to a record or introducing another record type does not require changing the symbol table. Binary width and sentinel checks belong to the compiler that lowers resolved indices into the file.

Source IDs also do not depend on the base game's asset catalogue. A record can reference a numeric type introduced by a mod. Named content resolution in the future compiler must use the selected game's effective mod records and resources, including load order, rather than a fixed list of shipped types. Source identity and asset lookup are separate operations.

The table borrows immutable records and ID bytes. Rebuild it after changing IDs or collection order: a reference then resolves to the record's new index. Display names may repeat or change without affecting resolution. The caller selects the script bank explicitly.

Not implemented: YAML parsing, source compilation, export and preservation. These follow in separate slices under #608. The existing binary reader, writer and assembler remain the format implementation.

Prior art¶

The container, directory, record strides and condition list are from Starlancer-OSS docs/dte-format.md and its scripting reference, which build on Captain Foster's Starlancer ME work. Everything above was re-checked against the 44 shipped missions and the engine's own code. Where the two differ, this document follows the code: the trigger's condition is at 0x00 and its subject implicit, sections 4, 12 and 13 hold flight groups, squads and squad members, a ship's 0x00 is its object ID, 0x02 tests equality and 0x03 inequality, 0x28 pushes a constant, and 0x32 pushes a byte. The byte-offset string pool, the object table and everything about the script beyond the dispatch loop are additions. StarLancerEditor, which reads and writes missions through YAML, names sections 14 and 15 the ships' formations and their points, which the engine's formation code bears out, and its writer lays missions out on the same template.