Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 4 additions & 39 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ concurrency:
cancel-in-progress: true
jobs:
build:
timeout-minutes: 5
env:
POLYWORLD_DEPS: ${{ github.workspace }}/..
strategy:
Expand All @@ -20,50 +21,14 @@ jobs:
steps:
- uses: actions/checkout@v5
- uses: treeform/setup-nim-action@v6
- name: Install native HTTP library on Windows
if: runner.os == 'Windows'
shell: pwsh
run: |
vcpkg install curl:x64-windows
"$env:VCPKG_INSTALLATION_ROOT/installed/x64-windows/bin" | Out-File -FilePath $env:GITHUB_PATH -Encoding utf8 -Append
- name: Install dependencies
shell: bash
run: |
cd ..
nimby create
nimby sync "${{ github.event.repository.name }}/nimby.lock"
- name: Build relay without game sources
run: python tests/test_server_boundary.py
- name: Run release tests and all-game determinism
run: nim r -d:release -d:audioTest -d:bassyNativeStrict -d:replayEvents tests/all.nim
- name: Test Cards and Casters
run: nim r -d:release -d:audioTest -d:bassyNativeStrict games/cac/tests/tests.nim
- name: Test display settings
run: nim r -d:release tests/test_displays.nim
- name: Test lockstep training API
run: nim r -d:release -d:headless -d:bassyNativeStrict games/gods_of_the_arena/tests/test_lockstep.nim
- name: Test presentation audio without an output device
shell: bash
run: |
nim r -d:release -d:audioTest tests/test_sound_startup.nim
nim r -d:release -d:audioTest -d:nimAllocStats tests/test_sounds.nim
nim r -d:release -d:audioTest -d:nimAllocStats games/gods_of_the_arena/tests/test_audio.nim
nim r -d:release -d:audioTest -d:nimAllocStats games/light_vs_dark/tests/test_battle_sounds.nim
- name: Test browser launch arguments
run: |
node tests/test_webinputs.js
node tests/test_replay_audio.js
- name: Test Voice Lab browser transport and local server
run: |
node experiments/voice/tests/test_browser_transport.mjs
nim r experiments/voice/tests/test_web_server.nim
- name: Test Voice Lab signing selection
if: runner.os != 'Windows'
run: nim r experiments/voice/tests/test_signings.nim
- name: Test browser relay protocol
- name: Check and run unit tests
shell: bash
run: |
nim c -r --hints:off --nimcache:"$RUNNER_TEMP/room-wire-cache" -o:"$RUNNER_TEMP/room-wire-fixture" tests/room_protocol_fixture.nim > "$RUNNER_TEMP/room-wire.json"
node tests/test_room_protocol.cjs "$RUNNER_TEMP/room-wire.json"
- name: Check neural converters
run: python games/gods_of_the_arena/tests/test_neural_converters.py
nim check -d:release tests/unit_tests.nim
nim r -d:release tests/unit_tests.nim
108 changes: 108 additions & 0 deletions docs/command-line.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,108 @@
# Game command lines

Polyworld games share one parser for options that have the same meaning.
Run a game's `--help` for its supported options and game-specific setup.
An unsupported option produces an error rather than being silently ignored.

All valued options accept the same three forms:

```sh
./game --replay "replays/my match.replay"
./game --replay="replays/my match.replay"
./game --replay:"replays/my match.replay"
```

Paths are relative to the directory where the game was launched, including
clients that change their working directory to find assets. Quote paths or
names containing spaces. Repeated scalar options use their last value;
`--player` may appear only once and bot options accumulate.

| Option | Shared meaning |
| --- | --- |
| `--record PATH` | Save the current match's replay to this file, creating missing parent directories. |
| `--replay PATH` | Load and play this recording instead of running bots. |
| `--bot PATH[:N]` | Add N instances of a bot program, defaulting to one. Repeat to use different programs. |
| `--bots PATH[:N]` | Identical alias of `--bot`, including repetition and counts. |
| `--player [N]` | Reserve one human-controlled slot, numbered from one. Bare `--player` selects slot one. |
| `--name TEXT` | Set the local human's display name, or the multiplayer identity where supported. |
| `--seed N` | Set the new match's signed 32-bit random seed. |
| `--ticks N` | Set the new match's maximum simulation ticks. |
| `--seconds N`, `--minutes N` | Set the new match's duration using that game's simulation tick rate. |
| `--play [BOOL]` | Start local simulation or replay playback playing or paused; default true. |
| `--speed N` | Use this positive integer local simulation or playback multiplier; default one. |
| `--windowSize WIDTHxHEIGHT` | Set the graphical window dimensions. |
| `--vsync [BOOL]` | Enable or disable display synchronization; default true. |
| `--mute [BOOL]` | Override saved audio settings for this launch; bare `--mute` disables sound. |
| `--unmute [BOOL]` | Enable launch audio; false mutes it. This does not enable microphone input. |
| `--verbose [BOOL]` | Enable diagnostic output; default false. |
| `--headless-tick-rate N` | Pace headless simulation at N ticks per wall-clock second; zero is unlimited. |
| `--llm-mode async\|barrier` | Advance asynchronously or wait for the current batch of bot LLM requests, where supported. |
| `--server URL` | Select the multiplayer relay. |
| `--room CODE` | Select a multiplayer room. `--join CODE` is an identical alias. |
| `--screenshot PATH` | Capture one native rendered frame, save it, and exit. |
| `--frames N` | Select the screenshot's rendered frame, defaulting to 30. |

Booleans accept `true/false`, `on/off`, `yes/no`, and `1/0`. Explicit command-line
choices take precedence over saved window and audio preferences.

## Bots and human slots

An explicit bot roster fills every nonhuman slot exactly. Bot programs expand
in argument order and skip the reserved human slot. There is no implicit cycling
or padding of an explicitly supplied roster. Games can offer bundled bots when
no bot programs are specified, and their fixed or configurable roster sizes
remain game-specific.

For a four-player game, these commands select the same roster:

```sh
./game --player 2 --bot players/base.bas:3
./game --player=2 --bots=players/base.bas:3
./game --player:2 --bot:players/base.bas:3
```

Two different programs can fill the three bot slots:

```sh
./game --player 2 --name "Local player" \
--bot players/first.bas --bot players/second.bas:2
```

Use `--name` for a display name. `--player Alice` is an error. A headless build
cannot host a human controller.

## Recording and playback

`--record` selects a destination. In a client that opens a menu, the choice
persists into the match started from that menu; the flag alone does not select
a game setup. `--bot`, `--player`, or a game's explicit start option can launch
a configured match directly. Explicit replay files remain separate from optional
automatic desktop replay-library saving.

`--replay` cannot be combined with bots, a human controller, recording, an
explicit seed, or explicit duration flags. A replay carries its original setup;
game-specific seek options control which recorded position to display. Replay
format/version validation is unchanged, with no conversion of older recordings.

Local playback speed does not change simulation rules or a multiplayer server's
tick rate. A live network controller follows the authoritative match clock.
Games report when that prevents a requested pause or playback speed. GotA's
draft remains interactive before its battle simulation starts; `--play=false`
pauses the battle when the draft finishes.

## Game-specific capabilities

GotA, Light vs Dark, Cards and Casters, Call to Adventure, Heartleaf, Crewrift,
Galcon, Pudge Wars, Generals, and Mini Diplomacy use the shared replay and bot
vocabulary where their clients support those capabilities. Monster has no BASIC
roster or action-replay implementation and rejects those options. Its microphone
conversation mode is selected explicitly with `--conversation`.

Map generation, heroes, decks, tutorials, roles, calendar dates, and coaching
controls remain game-specific. Turn-based clients need not support a duration
in seconds. Graphical transport and window flags require a graphical build;
LLM barrier mode requires a client that implements LLM requests.

See [screenshot capture](screenshots.md) for capture behavior and
[testing](testing.md) for the unit-only CI policy. Parser, roster, and path
regressions are unit tests; CI does not open windows or simulate full games.
59 changes: 42 additions & 17 deletions docs/crewrift.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,17 @@ Run from the Polyworld repository root, with the usual dependencies and sibling
`polyworld_art` checkout:

```sh
nim r games/crewrift/crewrift.nim
nim r games/crewrift/crewrift.nim --player
```

The default match has eight players, with one human and seven local Bassy BASIC
bots. Roles are random. To choose a role or watch the bots:
The default match has eight local Bassy BASIC bots. `--player` reserves slot one
for a human, and `--player N` selects another one-based slot. Roles are random.
To choose a role or watch the bots:

```sh
nim r games/crewrift/crewrift.nim --role:imp
nim r games/crewrift/crewrift.nim --role:crew
nim r games/crewrift/crewrift.nim --spectate --seed:17
nim r games/crewrift/crewrift.nim --player --role imp
nim r games/crewrift/crewrift.nim --player --role crew
nim r games/crewrift/crewrift.nim --seed 17
```

| Control | Action |
Expand Down Expand Up @@ -52,8 +53,12 @@ and remaining task count, imposter kill count, or dead status. Scroll to see mor
crew. Click a visible living crew member's portrait to follow them.
The top-left **Room names** button shows or hides the large white room labels.
Room labels start visible and retain their setting while seeking or looping.
Use `--name:"Andre von Houck"` to name your human-controlled slot. Local bots
are labeled `base.bas`, or the filename supplied with `--bot PATH[:N]`. See the
Use `--player --name "Andre von Houck"` to name your human-controlled slot.
`--name` requires `--player`; bot identities come from their program files.
Local bots are labeled `base.bas`, or the filename supplied with the repeatable
`--bot PATH[:N]` option (`--bots` has the same meaning). Supplied groups must
fill every non-human slot in order. If no bot option is supplied, those slots
use the bundled program. See the
[BASIC bot guide](../games/crewrift/docs/bots.md) for custom policies and the
host API. New replays retain the names for each slot. Older recordings without
identities show `Unknown`.
Expand Down Expand Up @@ -124,18 +129,38 @@ faces, and boxes fully enclosed by solid meshes before auditing the ship.
Input recordings can be viewed graphically or verified without graphics:

```sh
nim r games/crewrift/crewrift.nim --record:tmp/crewrift.json
nim r games/crewrift/crewrift.nim --replay:tmp/crewrift.json
nim r -d:headless games/crewrift/crewrift.nim --record:tmp/crewrift.json
nim r -d:headless games/crewrift/crewrift.nim --replay:tmp/crewrift.json
nim r games/crewrift/crewrift.nim --player --record tmp/crewrift.json
nim r games/crewrift/crewrift.nim --replay tmp/crewrift.json
nim r -d:headless games/crewrift/crewrift.nim --record tmp/crewrift.json
nim r -d:headless games/crewrift/crewrift.nim --replay tmp/crewrift.json
nim r -d:headless games/crewrift/tests/test_sim.nim
```

`--players:8` through `--players:16` set the roster. `--ticks:N` bounds active
simulation ticks. `--windowSize:1440x900` changes the window. `--screenshot:PATH`
captures a frame and exits. `--capture-ticks:N` selects the simulation tick to
capture. Replays store input buttons, votes, and chat with a fingerprint for
every tick. Playback reports the first mismatch.
`--players 8` through `--players 16` set the roster. `--ticks N` bounds active
simulation ticks; `--seconds N` and `--minutes N` express the same limit in
time. `--play false` starts the viewer paused, `--speed N` selects its playback
speed, and `--vsync off` disables display synchronization. Headless runs accept
`--headless-tick-rate N` for wall-clock pacing; zero runs without waiting.
Graphical builds reject this headless-only pacing option.
Replay playback cannot be combined with bots, a human player, or recording.
Explicit `--seed N` values are deterministic signed 32-bit integers, including
negative values and `-1`. The exact seed is retained in recordings and rewinds.
Crewrift has no network-room or LLM request interface, so those options are
rejected. All value flags accept space, `=`, or `:` separators.

Screenshot capture uses the shared native arguments:

```sh
nim r games/crewrift/crewrift.nim --screenshot output/crewrift.png --frames 30 --windowSize 1280x720
```

The same flags accept space, `=`, or `:` separators. Capture uses a hidden,
muted window, writes the PNG after 30 rendered frames by default, and exits.
Parent output folders are created automatically. No special build is needed;
headless and browser builds cannot capture native screenshots.
`--capture-ticks:N` optionally advances N simulation ticks before the capture
frames; its default is zero. Replays store input buttons, votes, and chat with
a fingerprint for every tick. Playback reports the first mismatch.

This example is a local playable port. The original Bitworld websocket server,
league clients, pixel renderer, and `.bitreplay` format are not connected to it.
Expand Down
63 changes: 51 additions & 12 deletions docs/mailboxes.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,8 @@ Each player has one inbox with 100 message slots. A message is an integer ID
and a string, limited to 1024 bytes. Sending to a full inbox does nothing;
unread messages remain until the player pulls them.

Each game defines `sendChat` and its BASIC callbacks in its own `bots.nim`.
The BASIC host passes the sender’s roster slot, the destination, and the
message bytes to the game’s `sendChat`.
The [BASIC mailbox example](../examples/mailboxes/chat.bas) uses these routing
rules:

Expand All @@ -17,10 +18,9 @@ rules:
Broadcasts include the sender. CTA uses its existing Chebyshev tile distance:
the difference along each tile axis must be at most 16. Range and level are
checked when sending; moving afterward does not remove queued messages.
Each game owns this routing loop. There is no shared routing policy or
routing callback framework.
Each game selects recipients before writing to their inboxes.

`sendChat` returns the number of inboxes that accepted a copy. Empty or
In a local game, `sendChat` returns the number of inboxes that accepted a copy. Empty or
oversized messages and unsupported or invalid destinations return zero.
A broadcast can reach some players even when another player's inbox is full.

Expand All @@ -30,8 +30,9 @@ global, `-1` for team, or the sender's player ID for a DM. An empty pull sets
that ID to `-3`. There is no separate sender, channel name, or timestamp.

`mailboxCount()` counts unread messages, `mailboxSelf()` returns the caller's
roster ID, and `mailboxPlayers()` gives the roster size. GotA uses IDs 0 to 9,
CTA uses 0 to 3, and Light vs Dark uses 0 to 1.
roster ID, and `mailboxPlayers()` gives the roster size. Addresses run from
0 through `mailboxPlayers() - 1` in all three games. CTA has four party
slots. GotA uses the hero roster and LvD uses the configured player count.

```basic
sendChat(-2, "Hello everyone.")
Expand All @@ -46,15 +47,53 @@ while message$ <> ""
wend
```

Delivery follows script execution order. A later player can read a message
Local delivery follows script execution order. A later player can read a message
in the same tick. Players can send and pull multiple times per decision,
within their normal BASIC instruction and string limits. Inboxes persist
across decisions and are replaced when policies are loaded for a new run.
Recorded matches store chat in the same ordered command stream as gameplay
actions. Replay playback consumes those commands without rerunning the bots.

`mailboxes.nim` is only a bounded inbox: an array of IDs, an array of reserved
strings, and read/count fields. It has no BASIC dependency. Each game owns
one inbox per player and copies message text through Bassy's public API.
Bassy owns its string storage and reclaims temporary strings on `restart()`.
Polyworld does not inspect or manage BASIC's private storage.
## From submission to inbox

- **GotA** resolves the hero entity to a roster slot. Local policy chat goes
through `deliverChat` to `deliverPolicyChat`. In multiplayer, `sendChat`
returns 1 when it queues a submission. Each client receives the submission in an
authoritative tick packet. The game decodes category 1, checks hero/seat
ownership and destination, and applies an `ActionPolicyChat` with the sender
hero, target and text. Human chat uses category 2 and its own transcript.
See the [packet layout](../games/gods_of_the_arena/packets.md).
- **LvD** uses the player slot directly. Local sends call `deliverChat`.
Multiplayer queues a submission and returns 1 on acceptance. The client
decodes the packet’s chat payload (tag 0, player, target, byte-counted text),
checks ownership and destination, then applies nonempty chat at the packet
tick. The public HUD reads broadcast actions from the transcript. Reading
the HUD leaves BASIC inboxes untouched.
- **CTA** converts the hero ID to its party slot and selects nearby players
with room in their inboxes. When recording, it saves the accepted recipient
mask, target and text before pushing the broadcast to those same slots.

In each host, `pullMailbox$()` uses Bassy’s public string API to copy the front
message into the calling player’s runtime before popping the entry. The pop updates
`mailboxId()`. An inbox can fill between network submission and delivery.

## Local contract check

With the dependencies from `nimby.lock` available to `config.nims`, run this
from the repository root in a POSIX shell. Set `POLYWORLD_DEPS` if the pinned
dependencies live outside the checkout’s parent directory. This checks FIFO
wraparound, exercises all three BASIC hosts for 300 decisions, measures inbox
allocations, and checks LvD authoritative packet delivery and replay. The
tests run serially with one compiler worker.

```sh
(
scratch=$(mktemp -d) || exit 1
trap 'rm -rf "$scratch"' EXIT
for test in tests/test_mailboxes.nim tests/test_mailbox_allocations.nim \
games/light_vs_dark/tests/test_replay_chat.nim; do
nim c -r -d:headless -d:nimAllocStats --parallelBuild:1 \
--nimcache:"$scratch/cache" -o:"$scratch/check" "$test" || exit 1
done
)
```
Loading
Loading