station/README.md

# Station

A persistent-world, RPG-style station simulation inspired by Space Station 13, built
with [Bevy](https://bevy.org) in Rust.

- **ECS** – all game state lives in Bevy entities and components.
- **Data driven** – items, recipes, buildings and skills are defined in
  [rsn](https://crates.io/crates/rsn) files under `assets/data/`.
- **Scriptable** – behaviour is written in [Rune](https://rune-rs.github.io) scripts
  under `assets/scripts/`.
- **Tiled maps** – maps are regular [Tiled](https://www.mapeditor.org) `.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](https://crates.io/crates/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

```sh
cargo run                                   # singleplayer (world: saves/singleplayer.rsn)
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 (world: saves/server.rsn)
```

Client options: `--name NAME`, `--save FILE`, `--no-save`, `--map MAP`.
Server options: `--port PORT`, `--save FILE`, `--no-save`, `--map MAP`.

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 and on exit (window close, Ctrl-C, SIGTERM).
Characters are identified by name and are restored when that name logs in again.

## 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` 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

```rsn
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

```rsn
recipes: [
    { id: "smelt_iron", name: Some("Smelt iron plate"),
      inputs: [("iron_ore", 2)], outputs: [("iron_plate", 1)],
      tools: [], station: Some("furnace"),
      skill: Some({ skill: "smithing", level: 1 }), xp: 10 },
]
```

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.

```rsn
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).

### Skills

```rsn
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.

```rune
// 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 save file is authoritative.
Delete the save file to start a fresh world.

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

## Development

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

Tests run with [cargo-nextest](https://nexte.st) (`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

```sh
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.