feat: the editor link's live scene, timeline and console, and --mods

docs/engine/editor-link.md

@@ -268,8 +268,10 @@ takes none.
 
 ### What it does
 
-- The editor's messages wait while no mission plays, as the original's wait in its block for the
-  next mission's start. Each attempt reads the mission's file again, so the flags last for one
+- While no mission plays, the original's messages wait for the next mission's start, as they wait
+  in the original's block, and any message after one of them waits too. OpenReliant's own messages
+  are read as they come: a console line runs, and a request for the mission's file or the script's
+  state is ignored. Each attempt reads the mission's file again, so the flags last for one
   attempt: an editor sends them again once the file comes with each `Mission started`, and the
   start parts wait for them.
 - The link opens as the game starts, so that an editor waiting for the game is there before the
@@ -321,13 +323,14 @@ still read.
 
 | Tag | Message | Payload | Sent | Why |
 |---|---|---|---|---|
-| `0x100` | Hello | `protocol` (1), `openreliant` (its version), `game` (`StarLancer`), `vm` (the script VM's dialect, `starlancer`) | By the game, as an editor connects | The original's editor worked only with StarLancer. A client learns which game and script dialect it's linked to, and the version of these messages |
+| `0x100` | Hello | `protocol` (2), `openreliant` (its version), `game` (`StarLancer`), `vm` (the script VM's dialect, `starlancer`) | By the game, as an editor connects | The original's editor worked only with StarLancer. A client learns which game and script dialect it's linked to, and the version of these messages |
 | `0x101` | Mission started | `number`, `file` (such as `mission1.dte`) | By the game, as a mission's script starts, and to an editor that connects while one plays | The original's messages never say which mission plays: its editor started its own. Tag `0x1B` says only whether the first thread has finished |
 | `0x102` | Mission ended | None | By the game, as the mission ends | The original's messages don't say when a mission ends |
 | `0x103` | Get mission | None | By the editor | Asks for `Mission file` |
 | `0x104` | Mission file | The mission's file as the game runs it, its globals as they stand | By the game, right after `Mission started`, and as the editor asks | The original's editor had its own copy of the mission, as an editor that builds the mission has. A client without one, such as `openreliant debug`, reads the script here, and an editor checks that the game plays its build |
 | `0x105` | Get state | None | By the editor | Asks for `State` |
-| `0x106` | State | The script's state, below | By the game, as the editor asks | The original's debugger hears only where the script stopped (`0x1A`). None of its messages carries the threads, the globals or the game's variables |
+| `0x106` | State | The script's state, below | By the game, as the editor asks | The original's debugger hears only where the script stopped (`0x1A`). None of its messages carries the threads, the globals, the game's variables, the ships' orders or what the script did |
+| `0x107` | Console line | `line`: a line for the game's console | By the editor | The original has no mods, and no console to run their scripts in |
 
 `State` gives, a line each:
 
@@ -341,8 +344,26 @@ still read.
 | `thread.N.trigger` | The trigger that started it, where one did |
 | `global.N` | Global `N`'s value |
 | `variable.NAME` | The game's variable `NAME`, such as `mission_over`; one with no name by its number, where it isn't 0 |
-
-Values are the script's words, unsigned.
+| `ship.N.order` | The current order of the mission's ship `N`: its name, such as `fight`, its number if it has no name, or `none`. Only the ships in play are listed: created, and not destroyed |
+| `ship.N.target` | The slot of the ship the order targets, if it targets one. For the mission's ships, the slot is the ship's index |
+| `event.N.kind`, `event.N.index` | What the script did since the last `State`, in order from 0: a trigger that fired (`trigger`), by its index in the trigger list, or a command that ran (`command`), by its number in the catalogue |
+| `event.N.time` | When it happened, on the script's clock, in milliseconds |
+| `events_dropped` | How many events were left out because more than 512 came between two states. The oldest are dropped first |
+
+Values are the script's words, unsigned, except the names of orders and of the events' kinds. The
+game keeps events only while an editor is linked, and clears them once a `State` has sent them.
+
+`Mission file` gives where the ships are. Every frame, the game copies each of the mission's ships'
+position and heading from its object into its record, as the original does
+(`mission_ships_sync`), and marks a destroyed ship in its flags
+([The mission file](../formats/dte.md)). With the orders from `State`, that's the live scene.
+
+`Console line` runs its line in the game's console, as if typed there
+([The console](../guide/scripting.md#the-console)): one of the console's commands, such as
+`reload`, or Luau. The console exists only with `--developer-mode` and a mod with scripts;
+otherwise the game logs that it ignores the line. The console's answers go to the game's log,
+`openreliant.log` in the game's folder, under `console`, next to what the scripts print
+([Log messages](../guide/modding.md#log-messages)).
 
 ### Adding a message
 
@@ -382,9 +403,8 @@ needs that OpenReliant doesn't carry yet:
 - the other games' script dialects, which `Hello`'s `vm` names
   ([#1017](https://github.com/OpenReliant/openreliant/issues/1017)).
 
-No message gives a live scene, each object's place, orientation and order as the game plays
-([#1059](https://github.com/OpenReliant/openreliant/issues/1059)). A message for it would have to
-make its case ([Adding a message](#adding-a-message)).
+The live scene, each ship's position, heading and order as the game plays, comes from
+`Mission file` and `State` ([OpenReliant's own messages](#openreliants-own-messages)).
 
 ### Writing a client
 
@@ -402,10 +422,13 @@ It works the way `openreliant debug` does:
 3. On tag `0x1A` (the original's), the script is held before the byte at the offset it gives: send
    tag `0x15` (the original's) with 1 to run on, 2 to step into the next statement, or 3 to step
    over it; or with 0 and 1 to pause the mission, and 0 and 0 to let it go on.
-4. Send `Get state` (OpenReliant's own) for the script's threads, globals and variables.
-
-`engine/link.zig` has a record for each of OpenReliant's own messages, which writes its payload and
-reads it back: `Hello`, `MissionStarted` and `State`. The game writes them, and `openreliant debug`
-reads them. A client that builds missions from source places its breakpoints with the compiler's
-map from the source's lines to the script's statements
-([Building a mission](../formats/mission-source.md#building-a-mission)).
+4. Send `Get state` (OpenReliant's own) for the script's threads, globals and variables, the ships'
+   orders, and what the script did since the last state.
+5. Send `Console line` (OpenReliant's own) to run a line in the game's console, and read what it
+   answers in `openreliant.log`.
+
+`engine/link.zig` has a record for each of OpenReliant's own messages with a payload, which writes
+the payload and reads it back: `Hello`, `MissionStarted`, `State` and `ConsoleLine`. The game writes
+the first three and reads the last, and `openreliant debug` reads the first three. A client that
+builds missions from source places its breakpoints with the compiler's map from the source's lines
+to the script's statements ([Building a mission](../formats/mission-source.md#building-a-mission)).

docs/guide/configuration.md

@@ -82,6 +82,7 @@ player doesn't launch, the launch counts as over 600 ticks, six seconds, into th
 | Option | Description |
 |---|---|
 | `--no-mods` | Start without the mods in the game's `mods` folder ([Modding](modding.md)) |
+| `--mods <mod,...>` | Start with only these mods, up to 64, in this order, whatever the mods screen has on. Give the name of a mod in the game's `mods` folder, or the path to a mod's folder or `.hog` file elsewhere. A mod that needs another loads only if that one comes before it. The mods screen stays shut, so its list doesn't change. `--no-mods` overrides it ([The mods screen](modding.md#the-mods-screen)) |
 | `--no-intro` | Start without the three movies the game plays as it starts, as `--mission` and `--screenshot` do |
 | `--developer-mode` | The tools for writing mods' scripts: the scripting console, which F11 brings up where a mod has scripts, and folder mods' scripts reloading when they or their shaders are saved ([Scripting](scripting.md#the-console)) |
 | `--editor-link` | Listen for a mission editor or a script debugger, such as `openreliant debug`, on this computer's own address, 127.0.0.1, which can then pause the mission and stop and step its script, as the original's editor link does ([Debugging mission scripts](debugging.md)) |

docs/guide/modding.md

@@ -182,6 +182,11 @@ The mods the section doesn't list are on, and load after the listed ones, in the
 Only 0 turns a mod off. To go back to loading every mod in the order of its name, delete the section.
 You can also edit it by hand.
 
+For a single run, `--mods` loads only the mods it names, in that order, and keeps the screen shut,
+so the section doesn't change. `--mods bananas` plays a mod on its own, and a path, such as
+`--mods dist/bananas.hog`, loads a mod from outside the `mods` folder
+([Configuration](configuration.md)).
+
 - A mod whose name has an equals sign, starts with a bracket or has spaces at either end can't be
   listed. It stays on and loads with the unlisted mods.
 - The screen lists up to 255 mods, and leaves out the ones that need a newer OpenReliant

docs/guide/scripting.md

@@ -2781,6 +2781,9 @@ wingmen global> exit
   the mouse wheel and the arrows scroll the output.
 - Any other line goes to the player and menu scripts' `on_console_command(text)`, so that a mod
   can add commands of its own.
+- The console's own answers also go to the log, under `console`, so that a linked editor that sends
+  the console lines can read the answers
+  ([The editor link](../engine/editor-link.md#openreliants-own-messages)).
 
 ### Reloading