# Training scenarios This guide is for engineers who build training simulations: driving, maritime, emergency response, ground operations. It takes you from installing Talos to a scored scenario an instructor can run and review afterwards. The path is two working days. Day 1 builds the scenario with what every Talos project has. Day 2 adds the Training plugin, which brings scoring, the instructor's console and the after-action review. You can build each step by asking an AI assistant connected to Talos, or by hand in the editor and the project's files. The guides show both. Talos sends nothing to an AI unless you connect one. ## What you will build **Crossing Drive.** A trainee drives a car along a town route with a 50 km/h limit: 1. a stop line, where the car must come to a full stop; 2. a pedestrian crossing, where a pedestrian may step out as the car approaches; 3. a green post at the destination. - **During the run**, the trainee sees speed, the limit and the next objective. - **Scoring:** the run is scored on speed over the limit, a full stop at the line, reaction time to the pedestrian, collisions and the time taken, with pass or fail per item. - **The instructor** can pause, send the pedestrian out, change the time of day and the fog, and take over the car. - **Afterwards**, the run plays back on a timeline with its events marked. It can be watched from any camera and taken over from any moment. The finished project ships as the **Crossing Drive** sample (the launcher's **Samples** tab; the Linux build has no launcher, so install it on Windows and copy the folder across, as [Start here](START-HERE.md), "On Linux", says). It is day 1's scene and scripts with some scenery for its look, plus day 2's `journal.json` and scorecard. Its project file does not list the Training plugin, so it opens in an engine without plugins: `argus plugin add training` lists it ([Plugins](PLUGINS.md) says how plugins are added, set up and removed, DIS included). Open it to compare with your own at any step. ## The path | When | You | Guide | |---|---|---| | Day 1, first hour | Install, open a sample, play it, connect an AI assistant if you want one | [Start here](START-HERE.md) | | Day 1, hours 2 to 5 | Build the world: the ground, the road, the car, the stop line, the crossing, the pedestrian, the destination | [Your first scenario](TRAINING-FIRST-SCENARIO.md), part 1 | | Day 1, hours 6 to 8 | Add the rules: the speed limit, the stop, the pedestrian, the HUD, the end of the run, a self-test | [Your first scenario](TRAINING-FIRST-SCENARIO.md), part 2 | | Day 2, hours 1 to 3 | Add the Training plugin; declare the events and metrics; write the scorecard | [Events, metrics and scorecards](TRAINING-EVENTS-SCORECARDS.md) | | Day 2, hours 4 and 5 | Run a session as an instructor: pause, inject, time of day, take over | [The instructor](TRAINING-INSTRUCTOR.md) | | Day 2, hours 6 and 7 | Review the run: the timeline, the markers, cameras, taking over from a moment; the report | [Reviewing a run](TRAINING-REVIEW.md) | | Day 2, last hour | Export for the training room, and run it on the other OS | [Export](EXPORT.md), and [The training room](#the-training-room) below | Later: several trainees and observers in one session ([Netcode](NETCODE.md)), and DIS to other simulators (the DIS plugin's guide). ## Five ideas the rest depends on 1. **A scenario is files you can read.** A project is a folder: `argus.project.json`, scenes as JSON (`scenes/main.scene.json`), behaviours in TypeScript (`scenes/behaviors/*.ts`), and small JSON files for roads, materials and the rest. The editor, your AI assistant and a text editor all change the same files. 2. **Entities with components.** Everything in a scene is an entity with an id, a transform and components: a `mesh` to draw it, a `collider` and a `rigidbody` for physics, a `vehicle`, a `trigger`, a `script` that runs a behaviour. A behaviour reacts to the engine (`update` every tick, `onTrigger`, `onCollision`) and emits events. 3. **The run is deterministic.** The simulation steps at a fixed 60 ticks a second. Same inputs, same simulation on Windows and Linux, checked every night. A recording is the inputs, a text file of about a line a tick (Crossing Drive's one-minute run is about 340 KB with its journal and metrics, under 50 KB zipped), and it plays back to the same result. That is what makes a score and a review trustworthy. 4. **What the trainee does becomes events.** Your behaviours emit an event at each moment that matters (`stop-line`, `brake-applied`, `trainee-collision`, and so on). On day 2 you declare those events. The engine then keeps them in the session's journal, computes metrics from them, and the scorecard reads the metrics. 5. **The instructor acts through session commands.** Pause, inject an event, change the environment, take over an entity: each is a command applied at a tick and recorded with the run. The review therefore shows everything that happened, and a recording replays exactly. ## Words used in these guides | Word | Meaning | |---|---| | Scenario | A project (or one scene of it) that a trainee runs | | Trainee | The person being trained; their vehicle or character carries the tag `trainee` | | Instructor | The person running the session from the console | | Behaviour | A TypeScript module attached to an entity by a `script` component | | Event | A named message a behaviour emits (`ctx.events.emit`) | | Journal | The session's record of declared events, each at its tick | | Metric | A value computed from the journal: a counter, a timer, an interval, a gauge, a threshold or a window | | Scorecard | A file listing what is scored, how it is measured and what passes | | Session command | Something done to a running session from outside it: pause, inject, possess, environment | | Inject | Raising an event in a running session (a hazard, a fault) from the instructor's palette | | Take over (possess) | The instructor drives an entity in place of its own input or AI, then hands it back | | Recording | The session's inputs, commands and journal in one file; it plays back exactly | | After-action review | Playing a recording back on a timeline to debrief | | DIS | The IEEE 1278.1 protocol simulators use to share entity positions | ## The training room What to check before a session on the training PCs: - **Export, don't run the editor.** An exported scenario is one executable that runs without the editor or the launcher ([Export](EXPORT.md)). - **Which export.** The instructor's console talks to the running scenario through its session server. A development export has that server and a release export does not, so a session with a console runs a development export for now. - **Plugins go with it.** A desktop export packs the plugins the project lists (the Training plugin included), so the training PC needs nothing else. For a plugin of your own, build its `dist/` before you export. A web export of a project with plugins is refused. - **Each platform.** Export for each platform the training room uses ([Export](EXPORT.md) lists which builds run where). Run the scenario's self-test on each PC (` --self-test `, [Self-test](SELF-TEST.md)): it is the quickest proof that the PC can run it. - **Recordings.** Keep the recordings with the scores: a recording plays back to the same run on any PC with the same scenario and the same engine version. Another engine version refuses it (`replay-engine-mismatch`), so update the training room's engine (or its exported build) between courses, not during one, and keep the old one while its recordings may still be reviewed. - **The console** is a browser page on the PC that runs the scenario ([The instructor](TRAINING-INSTRUCTOR.md)). Instructing from a second machine comes later. ## Where to get help - **Your AI assistant** can read every Talos guide (`argus://docs/`), including this one (`training`). - **Known issues** are listed in [Known issues](KNOWN-ISSUES.md). - **Report a problem** from the editor's Help menu ([Start here](START-HERE.md), "Report a bug, ask for a feature").