This directory contains the YAML schema files that define the WebSocket message protocol used by Robocode Tank Royale for network communication between the server, bots, observers, and controllers.
Each .schema.yaml file is a JSON Schema Draft 2020-12 definition. They are the authoritative contract for every message exchanged on the wire.
For sequence diagrams and flow documentation — how these messages participate in the battle lifecycle, connection handshake, turn loop, and controller commands — see:
docs/architecture/models/flows/
Initial messages exchanged when clients connect to the server.
| Schema | Direction | Purpose |
|---|---|---|
| server-handshake.schema.yaml | Server → Client | Server identity + sessionId assignment |
| bot-handshake.schema.yaml | Bot → Server | Bot registration with metadata |
| observer-handshake.schema.yaml | Observer → Server | Observer registration |
| controller-handshake.schema.yaml | Controller → Server | Controller registration |
| bot-ready.schema.yaml | Bot → Server | Bot ready to start battle |
Commands sent by controllers to manage game state.
| Schema | Direction | Purpose |
|---|---|---|
| start-game.schema.yaml | Controller → Server | Initiate battle with selected bots |
| stop-game.schema.yaml | Controller → Server | Terminate current battle |
| pause-game.schema.yaml | Controller → Server | Pause battle execution |
| resume-game.schema.yaml | Controller → Server | Resume paused battle |
| next-turn.schema.yaml | Controller → Server | Execute single turn (debug stepping) |
| change-tps.schema.yaml | Controller → Server | Change turns per second |
| bot-policy-update.schema.yaml | Controller → Server | Update per-bot policy (debug graphics, breakpoint mode) |
| enable-debug-mode.schema.yaml | Controller → Server | Enable turn-by-turn debug stepping |
| disable-debug-mode.schema.yaml | Controller → Server | Disable debug stepping |
Events broadcast by the server to inform clients of state changes.
| Schema | Recipients | Purpose |
|---|---|---|
| game-started-event-for-bot.schema.yaml | Bots | Battle started, includes initial state |
| game-started-event-for-observer.schema.yaml | Observers, Controllers | Battle started, full state |
| game-ended-event-for-bot.schema.yaml | Bots | Battle ended, personal results |
| game-ended-event-for-observer.schema.yaml | Observers, Controllers | Battle ended, complete results |
| game-aborted-event.schema.yaml | All | Battle cancelled/aborted |
| game-paused-event-for-observer.schema.yaml | Observers, Controllers | Battle paused |
| game-resumed-event-for-observer.schema.yaml | Observers, Controllers | Battle resumed |
| Schema | Recipients | Purpose |
|---|---|---|
| round-started-event.schema.yaml | All | New round began |
| round-ended-event-for-bot.schema.yaml | Bots | Round ended, personal stats |
| round-ended-event-for-observer.schema.yaml | Observers, Controllers | Round ended, full stats |
| Schema | Recipients | Purpose |
|---|---|---|
| tick-event-for-bot.schema.yaml | Bots | Turn state, events, bot own state |
| tick-event-for-observer.schema.yaml | Observers, Controllers | Turn state, all bots' states |
| skipped-turn-event.schema.yaml | Bot | Bot failed to send intent in time |
| Schema | Recipients | Purpose |
|---|---|---|
| scanned-bot-event.schema.yaml | Bot | Radar detected another bot |
| hit-by-bullet-event.schema.yaml | Bot | Bot took damage from bullet |
| bullet-fired-event.schema.yaml | Bot | Bot fired a bullet |
| bullet-hit-bot-event.schema.yaml | Bot | Bot's bullet hit target |
| bullet-hit-bullet-event.schema.yaml | Bot | Bot's bullet hit another bullet |
| bullet-hit-wall-event.schema.yaml | Bot | Bot's bullet hit wall |
| bot-hit-bot-event.schema.yaml | Bot | Bot collided with another bot |
| bot-hit-wall-event.schema.yaml | Bot | Bot collided with wall |
| bot-death-event.schema.yaml | Bot | Bot destroyed |
| won-round-event.schema.yaml | Bot | Bot won the round |
| Schema | Recipients | Purpose |
|---|---|---|
| team-message-event.schema.yaml | Team Bot | Message from teammate |
| Schema | Recipients | Purpose |
|---|---|---|
| bot-list-update.schema.yaml | Observers, Controllers | Available bots changed |
| tps-changed-event.schema.yaml | Observers, Controllers | Turns per second changed |
Messages sent by bots to declare their desired actions for the next turn.
| Schema | Direction | Purpose |
|---|---|---|
| bot-intent.schema.yaml | Bot → Server | Bot's desired movement, rotation, firing |
| team-message.schema.yaml | Bot → Server | Message to a teammate |
Reusable data structures embedded in events and commands.
| Schema | Purpose |
|---|---|
| bot-state.schema.yaml | Bot position, energy, direction (no ID) |
| bot-state-with-id.schema.yaml | Bot state including bot ID |
| bot-info.schema.yaml | Bot metadata (name, version, authors) |
| bot-address.schema.yaml | Bot network address |
| bullet-state.schema.yaml | Bullet position, direction, power |
| participant.schema.yaml | Bot participating in battle |
| game-setup.schema.yaml | Battle configuration (arena, rules) |
| initial-position.schema.yaml | Starting position for a bot |
| results-for-bot.schema.yaml | Personal battle results |
| results-for-observer.schema.yaml | Complete battle results |
| color.schema.yaml | RGB color value |
| event.schema.yaml | Base event structure |
| message.schema.yaml | Base message structure |
- Protocol Flow Diagrams — Sequence diagrams for all protocol flows
- Message Schema Reference — Detailed message contracts with examples
- ADR-0006: Schema-Driven Contracts — Design rationale
- ADR-0009: WebSocket Protocol — Protocol design