From dc2054f0bea2eb97d1068ff07e738d7a2ee785c5 Mon Sep 17 00:00:00 2001
From: Sylpheed RE agent <agent@localhost>
Date: Tue, 25 Aug 2026 21:00:56 +0000
Subject: [PATCH] re: name the four squadron order classes

Three come from the game's own strings, verified present: 'Set Squadron order
attack/trace/escort' at 0x820AF17C/1A4/1CC, loaded once each at entry to the
unit message pump sub_8232C4C0 so the pairing is unambiguous. The printf is
compiled out (bl 0x82674028 = li r3,0; blr) but the format strings and arguments
survive, which is what makes them usable as labels. The same poster functions
serve both the message path and the interpreter-command path, so the identity
transfers to opcodes 517 trace / 784 attack / 790 escort, i.e. ISL built-ins
46/47/48, now named in isl.py.

The fourth, opcode 512, is recorded at LOWER confidence on purpose: those strings
name only three. Its label rests on the route-generation strings on its own
vtable, a symbol-table-1 (route) argument rather than the unit table, a route
point-count lookup, and the pre-existing move_order label -- four independent
lines, but none of them the game naming it.

Also records a trap: sub_82320B48's ORDER_{WINGMAN,SQUAD,SQUADRON}_{FORMATION,
ATTACK,COVER,EXTENDED} enum looks like it should map onto the order classes and
there is no evidence it does. It is a voice/comms axis; not connected.
---
 docs/re/structures/squadron-orders.md | 71 +++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/re/structures/squadron-orders.md

diff --git a/docs/re/structures/squadron-orders.md b/docs/re/structures/squadron-orders.md
new file mode 100644
index 0000000..8d0d59b
--- /dev/null
+++ b/docs/re/structures/squadron-orders.md
@@ -0,0 +1,71 @@
+# The four squadron order classes
+
+Status: ✅ three named from the game's own strings; 🟡 the fourth named from
+weaker, independent evidence — recorded at lower confidence deliberately.
+
+The script tells a squadron what to do by posting an interpreter command whose
+handler pushes an **order object** onto the unit's order deque at `obj+216`.
+Four such classes exist, distinguished by size, constructor and a type tag at
+`[order+4]`.
+
+## ✅ Three named directly by the game
+
+`sub_8232C4C0` is a unit **message pump**. Three of its arms build orders, and
+each loads its own format string — the strings are verified present at these
+addresses:
+
+```
+0x820AF17C  "Set Squadron order attack %08x %08x \r\n"
+0x820AF1A4  "Set Squadron order trace %08x %08x \r\n"
+0x820AF1CC  "Set Squadron order escort %08x %08x \r\n"
+```
+
+The three stack slots holding them are written **once** at function entry and
+never rewritten, so the pairing is unambiguous. The `printf` itself is
+`bl 0x82674028` — `li r3,0 ; blr`, i.e. compiled out — but the format strings and
+their arguments survive, which is exactly what makes them usable as labels.
+
+The join to the script side is that **the same poster functions serve both the
+message path and the interpreter-command path**, so the identity transfers:
+
+| opcode | size | vtable | tag | order | ISL built-in |
+|---|---|---|---|---|---|
+| 517 | 160 | `0x820AEB2C` | 2 | **trace** — follow a named unit | **46** |
+| 784 | 192 | `0x820AFB0C` | 3 | **attack** | **47** |
+| 790 | 240 | `0x820AFB34` | 4 | **escort** | **48** |
+| 512 | 124 | `0x820AFAEC` | 1 | route/waypoint move 🟡 | 3 (`move_order`) |
+
+Built-ins 46/47/48 share one blob shape: `blob+4` = actor (symtab-2 index),
+`blob+12` = target (symtab-2 index), `blob+16 == 1` = an immediate/override flag.
+48 additionally carries a 3-double position. All four orders keep the target at
+`[order+92]`.
+
+## 🟡 The fourth is named on weaker evidence
+
+**`Set Squadron order …` names only three.** Opcode 512's label rests on
+different ground:
+
+* its vtable slot 1 is the sole referencer of `"%08x Now Generating Routes
+  [%d]...."` (`0x820AFAA4`, verified present);
+* its `[order+92]` comes from a **symbol-table-1** name (routes/messages), not
+  the unit table the other three use;
+* the posting built-in resolves a route point count;
+* `isl.py` had already labelled built-in 3 `move_order` from handler behaviour.
+
+That is four independent lines, but none of them is the game naming it. Recorded
+as 🟡 rather than levelled up to match the other three.
+
+## 🔴 A different enum that is NOT this
+
+`sub_82320B48` selects a voice line from
+`ORDER_{WINGMAN,SQUAD,SQUADRON}_{FORMATION,ATTACK,COVER,EXTENDED}`
+(`0x820AEEB0`…). The names are tempting — ATTACK and COVER look like they should
+map onto the order classes — but there is **no evidence** they index the order
+types, and it is a UI/comms axis. Not connected; do not conflate them.
+
+## 🟡 Not settled
+
+* `[order+80]` is plausibly speed and `[unit+84]+16 / +20` plausibly
+  engagement range and standoff distance. Neither is established.
+* `[unit+628]`, set to 2/4/5/3 by the four message arms, is read by
+  `sub_82318EC8` — meaning unknown.