callai-rpg 0.1.5

LLM-powered top-down RPG game

My RPG (Multiplayer-Ready)

A fully networked, Thick-Host/Thin-Client RPG engine driven by autonomous LLM agents.

Run

First, install dependencies:

pip install -r requirements.txt

Multiplayer Mode

1. Start the Dedicated Host Server (Headless):

python main.py --host

(The server will start listening on 0.0.0.0:5555 by default).

2. Start a Thin Client:

python main.py --join 127.0.0.1

(You can launch as many clients as you want. The server will dynamically assign them IDs like remote_1, remote_2 and replicate the state).

Singleplayer / Dev Mode (Local Bypass)

To run the game locally without network serialization overhead:

python main.py

Example

Player 1 (The Host):

1. Runs python main.py --host
2. Opens a new terminal and runs an HTTP tunnel wrapper: ngrok http 5555
3. Copies the forwarding URL provided by ngrok/your tunelling service (e.g., https://1234-abcd.ngrok-free.app).

Player 2 (The Client):

Runs python main.py --join 1234-abcd.ngrok-free.app (The engine automatically maps this to wss://1234-abcd.ngrok-free.app and successfully routes the TCP streams through the HTTPS tunnel).

LLM Setup

OpenAI

Set the following environment variables:

• OPENAI_API_KEY
• OPENAI_BASE_URL (optional; defaults to https://api.openai.com/v1)
• OPENAI_MODEL (optional; required if OPENAI_BASE_URL is specified)

You can place these in a local .env file, then specify their path: `python main.py --env-file .env'

Controls

• Arrows: move player
• SPACE: interact with nearby NPC, objects, doors, containers, and items.
• ENTER: Open a dialogue -> Type + ENTER: speak aloud, will be broadcasted to all nearby NPCs.

Note: For best performance, prefix your message to a specific NPC with '(To npc_name)', or Whisper to them via the interaction menu (must be standing close to them).

• TAB: open inventory
• D: drop the currently selected item in your inventory, will prompt a dialogue to specify amount to drop.
• L: Global NPCs and event log.
• ESC: close dialogue

Interaction options

The following options are available in the interaction menu, subject to each object/entity type:

• NPCs: Get their attention, Whisper to them, Give them gold
• Doors: Openning them (if unlocked, or when the correct key is possessed in inventory when locked), Knock on them
• Containers: Take away or Store items.
• Workstations/Harvestable objects (e.g. trees): harvest/craft new items from them at the expense of some specific resources (if applicable).

Modding & Plugins

The engine features a Zero-Touch Plugin System to ensure core files remain pristine.

To add custom items, tools, status effects, or physical actions:

1. Create a .py file containing your logic and @register_* decorators.
2. Drop the file into a plugins/ folder at the root of the repository.
3. The engine will dynamically discover and load your modules upon boot.