Metadata-Version: 2.4
Name: neonrp
Version: 0.2.12
Summary: Agentic engine for AI role-playing — agents as a game
Author: redoctober
Author-email: nikoloside <nikoloside@gmail.com>
License: LicenseRef-Proprietary
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: anthropic>=0.40.0
Requires-Dist: click>=8.1.7
Requires-Dist: jsonschema>=4.21.1
Requires-Dist: mcp>=1.0.0
Requires-Dist: openai>=2.16.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: regex>=2025.11.3
Requires-Dist: rich-pixels>=3.0.0
Requires-Dist: textual[syntax]<8.0,>=7.5.0
Provides-Extra: bridges
Requires-Dist: discord-py>=2.3.0; extra == 'bridges'
Requires-Dist: python-telegram-bot>=21.0; extra == 'bridges'
Provides-Extra: discord
Requires-Dist: discord-py>=2.3.0; extra == 'discord'
Provides-Extra: hub-publish
Requires-Dist: boto3>=1.34.0; extra == 'hub-publish'
Provides-Extra: telegram
Requires-Dist: python-telegram-bot>=21.0; extra == 'telegram'
Provides-Extra: tui-image
Requires-Dist: pillow>=10.0.0; extra == 'tui-image'
Requires-Dist: rich-pixels>=3.0.0; extra == 'tui-image'
Description-Content-Type: text/markdown

# 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

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

<details>
<summary><b>Double-click launcher (no terminal)</b></summary>

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`](https://github.com/LudicDynamics/WorldLines/releases/latest/download/WorldLines.dmg) |
| Windows | [`WorldLines.bat`](https://github.com/LudicDynamics/WorldLines/releases/latest/download/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.

</details>

<details>
<summary><b>Users in China (throttled GitHub / Cloudflare)</b></summary>

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

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

</details>

<details>
<summary><b>Developers — editable install</b></summary>

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

</details>

## Play

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

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

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

```bash
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](docs/TUI_GUIDE.md) for the full picture.

## Testing

```bash
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](docs/CLI_REFERENCE.md) — every command: validate, index, agents,
  import, sandbox/replay, embedding retrieval, and more.
- [Tutorial: Your First Game](docs/TUTORIAL.md) — zero to first turn.
- [TUI Guide](docs/TUI_GUIDE.md) — terminal UI documentation.
- [Architecture Overview](docs/ARCHITECTURE.md) — system design.
- [Product Roadmap](docs/PRODUCT_ROADMAP.md) — release direction.
- [Developer Guide](DEV_README.md) — contributing and internals.
</content>
