An AI-powered real-time visual novel engine.
No Python required.
Download storyloom-v{VERSION}-{platform}.zip from
Releases, extract,
and run Storyloom.
Requires Python ≥ 3.10.
pip install storyloom-engineOptional extras:
pip install "storyloom-engine[desktop,bg]" # native window + background removal| Extra | Adds |
|---|---|
desktop |
Native desktop window via pywebview — falls back to browser if unavailable |
bg |
Background removal for generated images (onnxruntime; model already bundled) |
System media assets are not included in the wheel. Download them via Settings → Updates on first launch.
git clone https://github.com/SiriLee/Storyloom.git
cd Storyloom
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[desktop,bg]"User data — config.json, saves/, media/, system_media/ — lives
outside the app payload (app/):
| Install | Data directory |
|---|---|
| Standalone binary | Next to the Storyloom executable |
| Wheel (pip) | ~/.local/share/Storyloom (Linux), ~/Library/Application Support/Storyloom (macOS), %APPDATA%\Storyloom (Windows) |
| From source | The repository root |
Override with the STORYLOOM_APP_DIR environment variable.
pip uninstall storyloom-engine removes only the package — not your data.
Saves and media are kept. To remove everything:
pip uninstall storyloom-engine
rm -rf ~/.local/share/Storyloom # adjust path per the table aboveUpdates are fetched from GitHub Releases. Behind a firewall or in regions where GitHub is restricted, set a proxy in Settings → System → Network Proxy (HTTP/SOCKS5).
storyloom-web # native desktop window (or browser fallback)
storyloom-web --browser # always open in browser
storyloom-web --port 8080 # custom port (default: auto-assign)
storyloom-web --help # show all options
# or
python3 -m storyloom.webOn first launch, open the Settings page. Enter your API key, select a mode (Text or Graph), and start a new game.
System media assets (character portraits and background images) are included in the standalone release zip. Wheel and source users can download them via Settings → Updates inside the app.
 Main menu |
 Co-creation |
 Story settings |
 Asset pre-build |
Gameplay |
 Saves |
 Settings |
 Assets |
| Streaming XML pipeline | StreamParser → StateManager → EventDispatcher — parsed line-by-line, no buffering |
| Bridge pre-fetch | Next API call fires mid-paragraph; latency hidden behind reading time |
| State validation | LLM suggests writes; engine type-checks before applying; rejected writes feed back |
| Two-layer branching | In-scene choices + outline-level route forks at checkpoints |
| Asset pipeline | O(1) catalog match → LLM fallback → AI generation; async, non-blocking |
| Context management | Sliding window + system prompt (permanent anchor) + checkpoint compression; ~50K tokens |
| Co-creation | AI interviews you about your idea before generating world, characters, and plot |
| Save / load | Atomic JSON saves; mode-agnostic — switch text/graph any time |
| i18n | English, 简体中文, 繁體中文 (gettext) |
| Web UI | FastAPI + SSE + vanilla JS SPA |
| Packaging | Standalone binary (PyInstaller) + pip wheel + system asset pack |
graph TD
LLM[Director LLM]
Parser[Stream Parser]
State[State Manager]
Tasks[Task Generator + Pool]
Dispatcher[Event Dispatcher]
UI[UI]
LLM -- "token stream" --> Parser
Parser -- "event" --> State
Parser -. "asset trigger" .-> Tasks
State -- "processed event" --> Dispatcher
Tasks -- "completed task" --> Dispatcher
Dispatcher -- "bound event" --> UI
UI -. "choice" .-> State
State -. "pre-fetch" .-> LLM
Solid lines are streaming data flow. Dotted lines are one-shot triggers. Graph-mode asset tags spawn tasks that resolve asynchronously, without blocking the text pipeline.
| Theory | First principles · Bridge mechanism · Streaming parse · Asset generation |
| Spec | Phase 1 pipeline · XML elements · Prompts · Data model |
| Graph mode | Design |
| API | GameSession · Co-create |
| Log | Engineering journal |
# Clone and install. `[test]` (pytest + babel) covers all core tests;
# add `[bg]` / `[desktop]` only when developing those features.
git clone https://github.com/SiriLee/Storyloom.git
cd Storyloom
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
# Tests (no API key needed)
pytest
# Build (can be run automatically by CI)
bash scripts/build.sh # standalone binary + wheel
bash scripts/pack_system_media.sh # system asset pack for release
# Generate system assets from source definitions (requires image API key)
python scripts/sysgen/generate_system_assets.py
python scripts/sysgen/generate_manifest.pyConventions: Python ≥ 3.10 · stdlib-first · Conventional Commits · English code & docs · mock tests (no real API calls).
AI context: AGENTS.md