Multiplayer Command-Surface Contract
This is the 1.0 fail-closed inventory for player input. An action may change an online simulation only when all four layers exist: Unity submission, dedicated- server schema validation and sequencing, deterministic Unity replay, and a two-client checksum test. A local mutation is never a fallback for a rejected, loading, disconnected, or missing online sync component.
OnlineCommandPolicy.cs is the executable client inventory. COMMAND_SCHEMAS
and COMMAND_KINDS in server/src/server.js are the executable server inventory.
The Unity logic harness and server security suite compare these against the exact
shipping set so a new verb cannot silently become online-capable.
Authoritative 1.0 verbs
| Player action | Command kind | Principal entry point | Deterministic replay |
|---|---|---|---|
| Move | move |
Battlefield/minimap IssueSelectionMove |
Formation destinations and Unit.Order |
| Attack-move | attackMove |
Attack-move mode | Formation destinations and Unit.Order |
| Attack unit | attackUnit |
Enemy-unit contextual order | ApplyUnitTarget |
| Attack building | attackBuilding |
Enemy-building contextual order | Pinned AttackBuildingOrder |
| Stop | stop |
Selection command row | Unit.Stop |
| Stance | stance |
Selection command row | Validated stance assignment |
| Build | build |
Single-building placement | PlaceFactionBuilding |
| Train | train |
Unit production card | QueueFactionUnit |
| Rally | rally |
Producer right-click/rally mode | SetRally |
| Surrender | surrender |
Online match menu | Authenticated server result handling |
checksum and playerDefeated are protocol-internal reports, not player verbs.
The server rejects the historical placeholder kinds sell, repair, feat,
and superweapon with bad_command_kind; Unity never applies them.
Complete player-action inventory
| Action | Classification | Online behavior |
|---|---|---|
| Move | Authoritative | Submit and consume success or rejection; never local-fallback |
| Attack-move | Authoritative | Submit and consume success or rejection |
| Attack unit | Authoritative | Submit exact visible target |
| Attack building | Authoritative | Submit exact visible target |
| Stop | Authoritative | Submit selected net IDs |
| Stance | Authoritative | Submit selected net IDs and bounded stance |
| Build | Authoritative | Submit one non-wall building placement |
| Train | Authoritative | Submit bounded affordable batch as individual commands |
| Rally | Authoritative | Submit selected producer and point |
| Surrender | Authoritative | Submit authenticated self-surrender |
| Selection | Presentation only | Local selection/read-only inspection |
| Control group | Presentation only | Local assignment/recall |
| Formation choice | Presentation only | Local choice included in the next move command |
| Camera | Presentation only | Local pan/zoom/rotate |
| Minimap focus | Presentation only | Local camera focus |
| Ally ping | Presentation only | Relayed communication; no sim mutation |
| Chat | Presentation only | Relayed sanitized communication; no sim mutation |
| Match overlay | Presentation only | Local ESC overlay; simulation keeps advancing |
| Sell building | Offline only | Buttons hidden; modes and controller mutation hard-guarded |
| Bulldoze building/decor | Offline only | Mode/controller mutation hard-guarded |
| Repair building | Offline only | Buttons hidden; mode/controller mutation hard-guarded |
| Cancel production/refund | Offline only | Queue/card input denied; refund APIs hard-guarded |
| Wall/gate chain build | Offline only | Cards refuse arming; stale placement and direct placement guarded |
| Deploy MCV | Offline only | Selection control hidden; player/controller APIs guarded |
| Transport board | Offline only | Hover/context affordance removed; unit/controller APIs guarded |
| Transport unload | Offline only | Selection control hidden; hotkey/player API guarded |
| Repair-depot order | Offline only | Context order consumed with an honest denial |
| Engineer capture/repair | Offline only | Context order consumed with an honest denial |
| Aircraft manual return | Offline only | RTB control hidden; manual unit API guarded; automatic empty-payload RTB remains sim logic |
| Aircraft stow | Offline only | Context affordance removed; unit/controller APIs guarded |
| Aircraft scramble | Offline only | Selection/context controls hidden; player wrapper guarded |
| Garrison enter | Offline only | Hover/context affordance removed; player API guarded |
| Garrison exit | Offline only | Selection/context controls hidden; player wrapper guarded |
| Bridge rebuild | Offline only | Hover/context affordance removed; contextual order denied |
| Dam attack directive | Offline only | Context directive denied; ordinary authoritative structure attack is separate |
| Unit ability | Offline only | Ability bar disabled; arming/cast paths guarded |
| Support power | Offline only | Strike controls hidden; arming/cast paths guarded |
| Faction feat | Offline only | Strike controls hidden; activation guarded |
| Superweapon | Offline only | Strike controls hidden; targeting path guarded |
| Manual intercept | Offline only | Intercept control hidden; player/controller paths guarded |
| R&D research | Offline only | Overlay action denied; research backend guarded |
| Doctrine research | Offline only | Overlay action denied; doctrine backend guarded |
| Advanced/building upgrade | Offline only | Selection/overlay action hidden or denied; purchase backends guarded |
| Zavesa Protocol | Offline only | Player activation and controller mutation guarded |
Autonomous consequences remain legal where they are deterministic and not player input: passenger spill from a destroyed transport, occupant evacuation from a destroyed/captured building, automatic empty-payload aircraft RTB, and local bot simulation. Those must not be routed through player-only wrappers.
Adding an online verb
Do not reuse a placeholder command kind. A change is complete only when it:
- Moves the action to
AuthoritativeinOnlineCommandPolicyand adds its exact kind. - Adds a bounded, allow-listed server schema and adversarial validation tests.
- Submits stable entity IDs and immutable intent from every HUD/hotkey/context path.
- Applies only server-stamped commands at the negotiated tick on every peer.
- Consumes rejected input without calling a local sim method.
- Adds offline-parity, Unity logic, server relay, and real two-client checksum coverage.
- Updates this inventory and the multiplayer test checklist.
Release validation
Build.RunLogicChecksasserts 44 classified actions, the 10 exact authoritative kinds, the two protocol-only kinds, and fail-closed online modes.server/test/security.test.mjsaccepts canonical examples for the nine relayed gameplay kinds tested before surrender, removes every required field in turn, rejects coercible/wrong JSON types and former placeholders, and proves rejected packets are not broadcast.unity/mp-sync-test.shexercises the enabled command surface through player-facing adapters in two real player builds, requires local-sender acceptance plus concrete post-apply state for every non-terminal verb, requires one local surrender round trip across the reports, and requires matching expanded state checksums.