neonrp 0.2.4

Agentic engine for AI role-playing — agents as a game

NeonRP

A developer-friendly command-line engine for playing and iterating on file-backed text RPGs — your whole world is plain files you can read, diff, and version.

Install

# macOS / Linux
curl -LsSf https://worldlines.gg/install.sh | sh

# Windows (PowerShell)
irm https://worldlines.gg/install.ps1 | iex

Installs uv (if missing) then uv tool install worldlines. Verify with neonrp --help — or just run worldlines. The curl/irm path avoids the macOS Gatekeeper and Windows SmartScreen prompts a downloaded file would trip.

Double-click launcher (no terminal)

Download a platform launcher and double-click it. It opens a terminal, runs the first-time install (or self-updates on later launches), then hands off to the TUI.

Platform	Download
macOS	WorldLines.dmg
Windows	WorldLines.bat

Because the app isn't signed yet, the first run only needs one approval:

• macOS — right-click WorldLines.app → Open → Open, or xattr -d com.apple.quarantine /Applications/WorldLines.app.
• Windows — SmartScreen → More info → Run anyway.

macOS/Windows remember the choice afterward. Linux uses the terminal install above.

Users in China (throttled GitHub / Cloudflare)

If curl https://worldlines.gg/install.sh times out:

# Force uv onto a China-hosted PyPI mirror, then install:
export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
uv tool install worldlines

# …or pass CHINA_MIRROR=1 to the installer in one shot:
CHINA_MIRROR=1 curl -LsSf https://worldlines.gg/install.sh | sh

Alternative mirrors: mirrors.aliyun.com/pypi/simple, mirrors.cloud.tencent.com/pypi/simple. neonrp self-update honors the same UV_DEFAULT_INDEX, so exporting it in your shell profile keeps upgrades on the mirror too.

Developers — editable install

uv tool install -e /path/to/NeonRP   # picks up local code changes
neonrp --help

Play

neonrp                       # launch the TUI → pick a built-in world → play

That's it. Prefer driving the engine from the shell?

neonrp init                  # scaffold a project in the current dir
neonrp run "look around"     # take a turn
neonrp save                  # checkpoint
neonrp undo                  # step back
neonrp branch "steal-route"  # fork an alternate timeline

neonrp init is enough to start in TUI build mode; fresh projects expose the packaged builtin worlds and skills automatically.

Why an engine, not a web chat

NeonRP is built around engine-like guarantees a chat box can't give you:

• Resume / Undo / Branch — checkpointed gameplay you can safely explore.
• Plan → Diff → Apply — changes are visible and validated before they land.
• Append-only events + snapshots — reproducible, debuggable runs.
• Minimal-context retrieval — fast even with large worlds.
• Sandbox & Replay — isolated experimentation and determinism checks.

Terminal UI

neonrp tui                          # interactive gameplay
neonrp tui --continue               # resume the last session
neonrp tui --provider lmstudio      # local OpenAI-compatible server
neonrp tui --import-card char.png   # import a SillyTavern card first

Single-pane Claude Code-style transcript + input, slash-command workflow with completion, live token counters, and streaming output.

Key	Action		Key	Action
q / Ctrl+Q	Quit		Ctrl+K / Ctrl+P	Command palette
Esc	Interrupt the in-flight turn		F6	Copy full transcript

See the TUI Guide for the full picture.

Testing

uv run pytest -q                                     # fast regression
uv run pytest --cov=neonrp --cov-report=term-missing # coverage
NEONRP_E2E_LLM=1 uv run pytest tests/test_llm_real_endpoint.py -q  # real LLM e2e

Documentation

• CLI Reference — every command: validate, index, agents, import, sandbox/replay, embedding retrieval, and more.
• Tutorial: Your First Game — zero to first turn.
• TUI Guide — terminal UI documentation.
• Architecture Overview — system design.
• Product Roadmap — release direction.
• Developer Guide — contributing and internals.