<p align="center">
  <img src="https://codeberg.org/torch-rs/realm-rs/raw/branch/main/logo.svg" width="200" alt="Realm">
</p>

# Realm

A collaborative, real-time toolkit for building and playing a 2D top-down RPG together, simultaneously.

Realm ships as a single binary with two modes: a **server** that hosts the game world and a **client** that connects to it. The world starts empty: no items, NPCs, maps, spells, abilities, or loot tables. Players with the right permissions create and modify all of this live while others play.

## Install

```sh
curl -fsSL https://realm.rs/install.sh | bash
```

Uninstall:

```sh
curl -fsSL https://realm.rs/install.sh | bash -s -- --uninstall
```

Or build from source:

```sh
cargo install realm-rs
```

## Concept

Game authoring and gameplay are the same activity. A DM or trusted players sculpt the world in real time while other players explore it.

Permissions use the game's own systems. Every account has a skill called **Authority** that gates the abilities used to modify game data. Because authoring tools are game abilities themselves, scripted events can grant or revoke editing powers, and game mechanics can interact with world-building directly.

## Usage

```
realm serve                          # Start the server on 0.0.0.0:9000
realm serve -H 192.168.1.5 -p 8080  # Bind to a specific host and port
realm client                         # Connect to 127.0.0.1:9000
realm client -H 10.0.0.1 -p 8080    # Connect to a specific server
```

### Server commands

The server TUI accepts `/` commands powered by Rhai scripts:

- `/players` -- list connected players
- `/kick <name>` -- kick a player by name

Plain text typed into the server TUI is broadcast as a system message.

### Client commands

- `/name <name>` -- set your display name

## Architecture

Single Rust crate (`realm-rs`), one binary.

### Networking

- **tokio** for async I/O
- **postcard** serialization with length-delimited, opcode-prefixed framing
- Protocol version exchanged on connection. Mismatched versions are rejected.

### Scripting

Game behaviors, triggers, and commands are scripted in [Rhai](https://rhai.rs). Scripts live in the `data/scripts/` directory and are loaded at runtime. Both server and client embed a Rhai engine with their own API surface.

### Data Directory

Realm looks for its `data/` directory in this order:

1. `REALM_DATA` environment variable
2. Next to the binary (portable installs, .app bundles)
3. Current working directory (development)
4. Platform user data directory:
   - Linux: `$XDG_DATA_HOME/realm/data` or `~/.local/share/realm/data`
   - macOS: `~/Library/Application Support/realm/data`
   - Windows: `%APPDATA%\realm\data`

## Status

Early development.

## License

[AGPL-3.0](https://www.gnu.org/licenses/agpl-3.0.html). A commercial license is available for closed-source distribution.
