station/README.md

Station

A persistent-world, RPG-style station simulation inspired by Space Station 13, built with Bevy in Rust.

• ECS – all game state lives in Bevy entities and components.
• Data driven – items, recipes, buildings, machines and skills are defined in rsn files under assets/data/.
• Scriptable – behaviour is written in Rune scripts under assets/scripts/.
• Tiled maps – maps are regular Tiled .tmx files.
• Persistent world – no rounds. The world and every character (inventory, skills, vitals, position) are saved and restored across restarts.
• Singleplayer and multiplayer – one authoritative server simulation, used locally in singleplayer and over UDP in multiplayer (bevy_replicon + renet).

Crates

Crate	Purpose
crates/game_core	Shared data definitions, components, Tiled loader, network protocol
crates/game_server	Authoritative simulation, Rune scripting, persistence, game-server binary
crates/game_client	Rendering, UI and input (game binary); embeds the server for singleplayer/host

The client never changes game state directly. It sends requests (Login, SetMoveDir, Interact, Craft, …) and the server replicates the resulting state back. In singleplayer the same server systems run inside the client process, so singleplayer and multiplayer behave identically.

Running

cargo run                                   # singleplayer (save game `singleplayer`)
cargo run -- --host 5000                    # singleplayer world that others can join
cargo run -- --connect 127.0.0.1:5000       # join a server or host
cargo run -p game_server --bin game-server  # dedicated server (saves/server.sqlite, world `main`)

Client options: --name NAME, --save NAME, --no-save, --map MAP. Server options: --config FILE, --port PORT, --password TEXT, --max-players N, --database URL, --world NAME|UUID, --no-save, --map MAP, --autosave SECS, --motd TEXT, --admin ID, --whitelist.

On Windows, release builds of the client open no console window, so command-line output such as --help and logs isn't shown. Use a debug build to see it.

The world autosaves periodically (in the background) and on exit (window close, Ctrl-C, SIGTERM). Characters are identified by name and are restored when that name logs in again.

Save games and databases

Worlds are stored with sqlx in SQLite or PostgreSQL. Every world has a UUID, and all rows are keyed by it, so any number of worlds can share one database.

• Singleplayer/host: each save game is its own SQLite file in the platform data directory: ~/.local/share/station/saves/ on Linux, %APPDATA%\station\data\saves\ on Windows and ~/Library/Application Support/station/saves/ on macOS.
• Dedicated server: --database takes a sqlx URL and defaults to sqlite://saves/server.sqlite. Use postgres://user:password@host/db for PostgreSQL. --world selects a world by name (created if missing) or by UUID.

game-server --database postgres://station:secret@db/station --world europa

The schema is created and migrated automatically. To run the PostgreSQL tests, set STATION_TEST_POSTGRES_URL to a database URL; without it they are skipped.

Dedicated server configuration

The dedicated server reads server.toml by default and creates it on first start. Command-line options override the file for one run only:

game-server --config prod.toml --port 5001 --database sqlite://saves/prod.sqlite

The config file also stores the server password, MOTD, max players, the database URL and world, plus access lists (admins, whitelist, bans). While the server is running, type commands into its terminal:

help
players
save
config get database.world
config set autosave_secs 30
stop

Controls

Key	Action
WASD / arrows	Move (you face the direction you move)
E	Pick up (own tile, otherwise the faced tile)
F / left click	Interact with the faced / clicked building
U	Use the selected item (eat, heal, …)
G	Drop the selected item
X	Deconstruct the faced building
1–9, 0, mouse wheel	Select an inventory slot
C / B	Crafting / build menu (W/S select, Enter confirm, Esc close)
H	Help

Modding

All content is loaded from assets/ at startup. Every .rsn file below assets/data/ (recursively) may contain any mix of items, recipes, buildings, machines and skills, so a feature can ship in a single file. References between prototypes and script hooks are validated at load time and errors name the offending file and id.

Items

items: [
    { id: "apple", name: "Apple", sprite: "sprites/items/apple.png", max_stack: 10,
      tags: ["food"], on_use: Some("food::eat"), consume_on_use: true,
      props: { "nutrition": 15 } },
]

Required: id, name, sprite. Optional: description, max_stack (default 50), tags, on_use (script hook), consume_on_use, props (numbers readable by scripts).

Recipes

recipes: [
    { id: "make_pickaxe", inputs: [("iron_plate", 2), ("plank", 1)],
      outputs: [("pickaxe", 1)], tools: ["wrench"], station: Some("workbench"),
      skill: Some({ skill: "smithing", level: 1 }), xp: 25 },
]

Required: id, inputs, outputs. Optional: name, tools (needed but not consumed), station (a tag provided by a building adjacent to the player), skill, xp, on_craft (script hook). Ingredients are written as ("item", count) or { item: "item", count: n }.

Buildings

Anything placed on the grid: walls, doors, machines, trees, rocks.

buildings: [
    { id: "door", name: "Door", sprite: "sprites/buildings/door_closed.png",
      variants: { "open": "sprites/buildings/door_open.png" },
      construction: Some({ materials: [("iron_plate", 2), ("plank", 1)],
                           tools: ["screwdriver"], xp: 10,
                           skill: Some({ skill: "construction", level: 1 }) }),
      on_interact: Some("door::toggle") },
]

Required: id, name, sprite. Optional: description, variants (name → sprite), solid (default true), max_health, stations (tags for recipes), construction (makes it buildable from the build menu), deconstructible (default true; refunds materials), on_interact (script hook), vars (integer state, persisted per building).

Machines

A machine adds item slots and its own recipes to the building with the same id. Interacting with it opens the machine window: put items into the input slots, the machine processes the first recipe whose inputs are present and whose outputs fit, and the results appear in the output slots. Machine contents are saved with the world and dropped when the machine is taken apart.

machines: [
    { id: "assembler", input_slots: 3, output_slots: 1, active_variant: Some("active"),
      recipes: [
          { id: "assemble_wrench", inputs: [("iron_plate", 2)], outputs: [("wrench", 1)],
            time: 3.0 },
      ],
      ui: { background: Some("ui/machines/assembler.png"), size: Some((260.0, 150.0)),
            inputs: [(16.0, 14.0), (16.0, 96.0), (70.0, 55.0)], outputs: [(200.0, 55.0)],
            progress: Some((124.0, 69.0, 60.0, 12.0)) } },
]

Required: id (an existing building), recipes (id, inputs, outputs, optional name and time in seconds, default 1). Optional: input_slots and output_slots (default 1), active_variant (building variant shown while working) and ui. Without ui positions, inputs are stacked on the left and outputs on the right with a progress bar between them. ui fields: background (PNG drawn behind the slots), size (window content size in pixels), slot_size (default 40), inputs/outputs (one (x, y) per slot, measured from the top-left corner) and progress ((x, y, width, height)).

Skills

skills: [ { id: "smithing", name: "Smithing" } ]

Scripts

Each .rn file in assets/scripts/ is a module named after its path (scripts/door.rn → door, scripts/npc/guard.rn → npc::guard). Data files refer to public functions as "module::function". Every hook receives one argument, ctx; returning false signals failure (for example, a used item is then not consumed). Script errors are logged and have no effect on the world.

// assets/scripts/door.rn
pub fn toggle(ctx) {
    if ctx.is_solid() {
        ctx.set_solid(false);
        ctx.set_variant("open");
        ctx.message("You open the door.");
    } else {
        ctx.set_solid(true);
        ctx.set_variant("");
        ctx.message("You close the door.");
    }
}

ctx methods:

Area	Methods
Actor	actor_name(), message(text)
Inventory	item_count(id), has_item(id, n), give_item(id, n), take_item(id, n) -> bool, spawn_item(id, n) (on the ground)
Vitals	health(), max_health(), heal(n), damage(n), nutrition(), feed(n) (integers)
Skills	skill_level(id), add_xp(id, n)
Used item	item_id(), item_prop(key)
Building	target_name(), get_var(key), set_var(key, n), is_solid(), set_solid(b), variant(), set_variant(name) ("" = default sprite), destroy_target()
Misc	random(max) → 0..max

Maps (Tiled)

Maps are orthogonal .tmx files with embedded or external tilesets. Each map cell is one game tile (drawn at 32×32; 32 px tilesets look best).

• Tile layers are rendered in order. A tile is solid if the tile has the boolean custom property solid = true in its tileset, or its layer has solid = true.
• Object layers spawn gameplay entities by object class:
  • spawn – player spawn point.
  • building – custom property proto = building id; any integer properties override the building's vars.
  • item – custom property proto = item id and optional count.
• Objects are placed on the tile containing their position (point objects work well).

A map is only used to create a new world; after that the saved world is authoritative. Start a new save game (or world) to get a fresh copy of the map.

tools/gen_placeholder_assets.py regenerates the placeholder sprites and example map.

Development

cargo nextest run --workspace   # unit tests + headless full-simulation test
cargo clippy --workspace --all-targets

Tests run with cargo-nextest (cargo install cargo-nextest --locked); its configuration is in .config/nextest.toml. CI uses --profile ci, which writes a JUnit report to target/nextest/ci/junit.xml.

Packaging

cargo xtask pack                                  # for the host platform
cargo xtask pack --target x86_64-pc-windows-gnu   # cross-compile for Windows (needs MinGW)

pack builds the client (game) and the dedicated server (game-server) with the stripped dist profile and writes dist/station-<version>-<target>.zip (Windows) or .tar.gz (other platforms). The archive contains both binaries, assets/, the README and the changelog. Unpack it and run the binaries from that directory. The unpacked staging directory is kept next to the archive. Options: --format zip|tar.gz, --out-dir DIR, --debug.

The GitHub Package workflow (.github/workflows/package.yml) runs pack for Windows (zip), Linux and macOS (tar.gz), uploads each archive as an artifact and attaches them to the release when a v* tag is pushed. The Gitea workflow cross-compiles the Windows package with MinGW.