Skip to content

cli.md

Latest commit

 

History

History
143 lines (108 loc) · 5.68 KB

cli.md

File metadata and controls

143 lines (108 loc) · 5.68 KB
Raw

The NationSim command line

There are two ways to drive the simulation: the console application (the interactive REPL and the batch commands) and the headless server (see the API contract).

dotnet run --project src/NationSim.UI.Console -- [options]
dotnet run --project src/NationSim.Server -- [options]

1. The options of the console application

Option Default Description
--seed <ulong> 20260101 The seed of the deterministic random source
--agents <int> 1000 The number of citizens
--grid <int> 32 The width and the height of the world in cells
--regions <int> 4 The columns and the rows of the administrative region grid (4 means 16 regions)
--ticks <long> 0 The ticks to run before the interactive loop starts
--snapshots <path> snapshots The directory the snapshots and the sessions are written to
--once off Run the requested ticks and exit without the interactive loop
replay record <file.replay> – Record the commands of the session into a file
replay play <file.replay> – Replay a recorded session and verify its hash
server start --port <int> 5000 Start the headless server for external clients
-h, --help – Show the usage text 
# a run of a simulated year that prints the dashboard and exits
dotnet run --project src/NationSim.UI.Console -- --seed 42 --agents 2000 --ticks 365 --once

# the headless server
dotnet run --project src/NationSim.UI.Console -- server start --port 5000

2. The interactive commands

The REPL accepts the commands below. When no terminal is attached it falls back to the standard input, so it can be scripted:

printf 'bill income-tax 0.30\nstatus\nquit\n' | dotnet run --project src/NationSim.UI.Console

The simulation

Command Description
run [ticks] Advance the simulation by the given number of ticks (default 1)
step [ticks] Advance the simulation by the given number of ticks
status Render the dashboard: tick, date, population, regions, treasury, GDP, inflation, unemployment, debt, the tax rates, the active laws, the approval, the health quality, the tax efficiency and the state hash
auto [on|off] [batch] The continuous runner. In this mode the keyboard is polled: p pauses and resumes, s steps one tick, d renders the dashboard, + and - change the speed, q quits
pause / resume Pause or resume the simulation

The institutions

Command Description
bill <type> <value> Submit a bill. The types are income-tax, corp-tax, spending, rate and subsidy
ministry list Show the ministries, their budgets, the laws they enforce and the active global modifiers
ministry budget <type> <amount> Fund health, infrastructure or finance with an annual budget
laws List the laws of the parliament with their status
policy Show the macro policy and the parliamentary factions
reports Show the latest fiscal reports (one per simulated month)
relief Enact the emergency relief act

The inspection

Command Description
region list The breakdown of every region: population, local GDP, the share of the national output, the capacities, the infrastructure, the unemployment, the tax and the trade
region inspect <id> The details of a single region and the regions that are connected to it
agents count The census: the active, the deceased, the employed and the unemployed citizens, the firms, the payroll, the capital and the output
agents sample <id> A sample of ten citizens and ten firms of a region
telemetry The recorded telemetry of the session

The sessions

Command Description
save [name] Write a snapshot of the current state into the snapshot directory
load <file> Read a snapshot and print its metadata
autosave [on|off] [every] Write a snapshot every every ticks
replay record <file> Start recording the commands of the session
replay stop Close the recording and write the session file
replay play <file> Replay a recorded session and verify its state hash
help The command list
quit Leave the application

3. Examples

A bill that is accepted

printf 'bill income-tax 0.20\nrun 50\nquit\n' | dotnet run --project src/NationSim.UI.Console -- --seed 42 --agents 300
nation> Passed Income Tax Act with 300 of 300 seats.

A tax increase is usually rejected: the factions score a bill against the economic indicators, and a tax increase in a healthy economy has no support.

Recording and replaying a session

# the recording is written when the application quits
printf 'bill income-tax 0.20\nrun 50\nministry budget health 3000000\nrun 30\nquit\n' \
  | dotnet run --project src/NationSim.UI.Console -- --seed 42 replay record session.replay

# the replay runs in another process and verifies the hash
dotnet run --project src/NationSim.UI.Console -- replay play session.replay
Recorded hash : 0x728C4D232ED79DE4
Replayed hash : 0x728C4D232ED79DE4
The replay reproduced the recorded session exactly.

Inspecting the nation

printf 'agents count\nregion inspect 3\nquit\n' \
  | dotnet run --project src/NationSim.UI.Console -- --seed 42 --agents 400 --ticks 60

4. The headless server

dotnet run --project src/NationSim.Server -- --port 5000 --seed 42 --agents 2000

The server exposes the telemetry stream, the command endpoint and the region details. The full contract is documented in the API reference.