叙事引擎

Getting Started

1. Clone the repo

   git clone https://github.com/Sagesheep/NarrativeEngine-P.git
   cd NarrativeEngine-P
   

1. Install & run

Windows — double-click Start_Narrative_Engine.bat

Linux / macOS — run start.sh

Or manually:

   npm install
   npm run build --prefix packages/engine
   npm run dev
   

1. Open your browser at http://localhost:5173

1. Configure your LLM — open Settings → Providers and add your API key + endpoint. Supports OpenAI, Ollama, DeepSeek, and any OpenAI-compatible API.

1. Create your first campaign — see Setting Up Your First Campaign below. The Example_Setup/ folder ships with ready-to-play worlds, so you can be playing in about two minutes.

Requirements: Node.js 20.19 or newer (the LTS build from nodejs.org is fine). Nothing else — no Python, no Docker, no database server.

Playing from another device on your network: run npm run dev:lan instead of npm run dev, then open http://<your-pc-ip>:5173 from the tablet or phone.

---

Writing your own setup

• Lore — write your world in Markdown with ## / ### headers. Each section becomes a lore chunk the GM can recall. Use [CHUNK: TYPE -- NAME] prefixes to classify entries (world_overview, faction, location, character, power_system, economy, event, rules, culture, misc). Start from Example_Setup/World_compendium/lore_template.md.
• Rules — define how the GM behaves: tone, output format, NPC behaviour rules, dice resolution, event protocols. The engine handles memory and recall — you define the style.
• First Message — set the scene, ask for character creation, or simply say "begin".
• World Lore Builder — prefer a form to a blank page? The 📖 button on the campaign hub opens a structured world editor that exports a ready-to-upload Markdown file.

Installing a mod

Put the folder under mods/ at the app root — next to data/. It is created for you on first run.

Narrative Engine/
├── data/        ← your campaigns
└── mods/        ← your mods
    └── grimdark-tone/
        └── manifest.json

No restart needed. Drop the folder in, open Settings → Extensions, press Rescan, enable it.

Disabling a mod freezes its data — it does not delete it. Re-enable and everything is where you left it. Deleting a mod drops only that mod's own tables; the rest of your campaign is untouched.

World Building Tools

World Lore Builder

A structured pre-game world editor, reachable from the 📖 button on the campaign hub:

• Dedicated fields for world background, languages, power systems, technology level, timeline, tone, and house rules
• Expandable lists for geography, factions, cultures, threats, and pre-seeded NPCs
• Export to Markdown with one click — the result drops straight into the World Lore slot of the New Campaign form
• Import Markdown with a smart review modal that merges changes without overwriting your work
• Multiple draft worlds — switch between them or delete old ones

Quick start with an example world (≈2 minutes)

1. On the campaign hub, press New Campaign. 2. Campaign Name — anything, e.g. Spirit Card World. 3. World Lore (.md) — pick a world file, e.g. Example_Setup/World_compendium/Spirit Card World/Spirit_Card_World_Lore.md 4. Rules (.md) — pick the current ruleset: Example_Setup/Ruleset/AI_GM_OS_v4.5 - Immersive Mode (Hybrid).md 5. World Loot (.json) — optional. Some worlds ship one, e.g. Example_Setup/World_compendium/Class Scroll World/loot.json 6. Cover Image — optional, any image file. 7. Press Create & Enter. 8. Open the matching start prompt from the same world folder (here, Spirit_card_world_start_prompt.md), paste it as your first chat message, and send.

The GM will walk you through character creation and drop you into the world. Every turn after that is handled by the engine.

Images, Vision & the Gallery

Every picture in a campaign carries text with it, which is what makes an image usable at turn 700 instead of only at turn 7.

• Paste an image into chat — a vision-capable model captions it, and the caption becomes part of the turn
• Campaign gallery — every generated scene image and every upload in one place, filterable, bulk-importable
• @mention an image — pull a picture back into the GM's context by name. Its caption is injected for that turn only, so recalling the same costume fifty times doesn't stack fifty copies in your history
• Standing offers — if you're clearly talking about an image already in the gallery, the engine offers it, and sending accepts the offer
• Scene illustration — generate artwork for the current scene through any OpenAI-compatible image API or a local ComfyUI install

---

Setting Up Your First Campaign

You do not paste lore into a text box. The New Campaign form takes files directly, and the engine chunks and indexes them for you.

The Example_Setup/ folder that ships with the repo contains everything you need:

Example_Setup/
├── Ruleset/                    ← how the GM behaves (the system prompt)
├── World_compendium/           ← ready-made worlds, one folder each
└── Ability Compendium/         ← optional power/spell libraries

Quick Reference

Extensions (Mods)

Version 2.0 moved whole features out of the core app and behind a frozen mod API. Open Settings → Extensions to see what's installed, toggle anything off, or press Rescan after dropping in something new.

World Map *(extension — work in progress)*

A pixel-art overworld that reads the Location Ledger rather than replacing it. It ships enabled but unfinished — version 0.6.0-wip — because a half-built map that draws real terrain and walks a real journey is more useful than a hidden one. public/bundled-mods/worldmap/STATUS.md is an honest account of what is and isn't done.

What works today:

• Terrain — twelve biomes, eight textured variants each, hillshade, contour lines, coastal shading
• Places from the ledger — anchored by their recorded relations and distance bands, not by a coordinate you have to author
• Travel as an engine action — A* routing over the grid, terrain-priced day counts, camps placed on real cost. One press moves one day, with no LLM call and no chat spam
• Fog of war — cells harden as you visit them; trails persist
• Discoveries and encounters — spaced, setting-aware events on the road

Travel can be started from the map, the Places panel, or the composer — all through the same code path.

Troubleshooting

"Node.js is not installed" when running the start script Install the LTS version from https://nodejs.org/ and run the script again.

"needs Node 20 or newer" when running the start script Your Node.js is too old. Upgrade to the LTS version at https://nodejs.org/.

"NODE_MODULE_VERSION mismatch" error after upgrading Node Your database module was built for the old Node version. Run the repair script and choose option 1 (Quick fix): - Windows — double-click Repair_Narrative_Engine.bat - Linux / macOS — run ./Repair_Narrative_Engine.sh

If the repair fails on Windows with a C++ build tools error, install the Visual C++ Build Tools (select "Desktop development with C++") and run the repair again. Alternatively, run the repair script and choose option 2 (Full clean reinstall) — it may succeed without needing the C++ build tools.

"Cannot find native binding" / "rolldown" / "is not a valid Win32 application" when starting the app Your dependency install was incomplete (a known npm bug with optional dependencies). Run the repair script and choose option 2 (Full clean reinstall): - Windows — double-click Repair_Narrative_Engine.bat - Linux / macOS — run ./Repair_Narrative_Engine.sh

CORS errors with a cloud provider (NVIDIA NIM and similar) Some providers refuse requests made straight from a browser. The engine relays those calls through its own local backend, so this should just work — if it doesn't, check that the server on port 3001 is actually running (npm run dev starts both halves).

---