gametui

A tiny terminal platformer prototype built with Bun and OpenTUI.

The world is procedurally generated from a fixed seed and loaded in chunks. This gives us deterministic terrain for future multiplayer: every client can derive the same base world from the same realm id and seed, while player edits can be synced later.

Run it with:

bun install
bun run dev

Run from npm once published:

bunx gametui
npx gametui

Join a named world by passing the world name as the first positional argument:

bunx gametui Ryan-World
npx gametui Dax-World

Named worlds all use the same server, but each name maps to an isolated multiplayer room and deterministic world seed. Rejoining the same world name generates the same terrain; different names generate different worlds.

The default main world is superflat. World names beginning with superflat also generate flat terrain, for example:

bunx gametui superflat
bunx gametui superflat-ryan

gametui uses Bun at runtime, so bun must be installed and available on your PATH.

Each install keeps a stable local client id in ~/.config/gametui/game.json so reconnecting does not create duplicate player ghosts.

By default the client connects to the shared multiplayer server:

wss://gametui.raavcorp.com/rooms/main

Use a different server or run offline with:

gametui --server ws://localhost:47921/rooms/main
gametui Ryan-World --server ws://localhost:47921/rooms/main
gametui --offline
gametui -v

Controls:

• Left/right arrows or A/D: move
• Up arrow, W, or Space: jump (press again in air for double jump)
• Up/down arrows or W/S: climb ladders
• Down arrow or S: fast fall
• 1-0: select a hotbar block
• 0: selects a brown transparent door block you can walk through
• F: fire one bullet per second in the direction you last moved; getting hit flashes the terminal red
• T: teleport to the current mouse cursor position if the target is safe and within 500 blocks
• G: open the X-position teleport modal; entering X moves you 20 blocks above that ground level, clamped to 500 blocks from your current X
• L: spawn falling lava at the mouse cursor if available (30 second cooldown)
• Left-click solid blocks: mine/damage them until they break
• Right-click empty sky: place the selected hotbar block; hold and drag to paint blocks
• C: cycle your player icon
• R: reset player (20 second cooldown)
• Q or Escape: quit

The HUD shows the current multiplayer connection status, off-screen player direction counts, and a top-right player roster in five-row columns. Respawns are randomized, lava sinks away after 10 seconds, and the camera follows vertical movement only near the top/bottom viewport edges to avoid bounce.

The player is the one-cell triangle glyph ▲. Resizing the terminal changes how much of the world is visible, not the scale of the world or character. The vertical camera is anchored so jumping moves the character instead of moving the whole ground line.

On launch, the game asks for your name and saves it to:

~/.config/gametui/game.json

If a name is already saved, the game starts without prompting. To clear the saved name and answer again, run:

bun run dev -- --clear

The config also stores your last position per world name and restores it when you rejoin that same world.

World model:

• Default game seed: 0x1a11a6a
• Chunk width: 64 cells
• Current realm: overworld
• Named worlds derive their own deterministic seed from the world name while staying consistent for all players in that room.
• main and superflat* worlds use the same room/seed model with flat terrain generation.

Multiplayer Server

The Dockerized Bun WebSocket server lives in server/. It owns the shared seed, rooms, player snapshots, falling block physics, lava cells, tile ops, and block spawn ops. The OpenTUI client keeps deterministic terrain generation locally and applies the server's shared mutations.

Run locally:

bun run server:dev

Health check:

curl http://localhost:47921/health

WebSocket room URL:

ws://localhost:47921/rooms/main

Build/run with Docker:

docker build -f server/Dockerfile -t gametui-server .
docker run --rm -p 47921:47921 -v gametui-data:/data gametui-server

Run persistently with Docker Compose:

docker compose up -d --build

The shared server is proxied at:

https://gametui.raavcorp.com
wss://gametui.raavcorp.com/rooms/main

Server persistence defaults to:

/data/game-state.json