koronto11/ludo-npc-ai

A local narrative workbench for NPCs, branching dialogue and scene direction.
Bring your own AI. Keep the author's final say.

English · 简体中文

Overview · Workbench · AI Skills · Local MCP · Quick start · Example · Your data · Docs · Star History · Support

NPCs AI Studio turns a story outline into a visible authoring workspace. Establish the world's facts, build a cast, place characters in scenes, connect dialogue choices and rehearse what the player encounters. Use it for RPG quests, interactive fiction, narrative prototypes and NPC dialogue planning.

Your own AI can prepare the material through the bilingual Skills, or revise marked dialogue through local MCP. The built-in model connection can also generate focused candidates. Every workflow leaves you in control of the final text.

World brief → Characters → Scenes & appearances → Dialogue & events → Review → Rehearsal → Handoff

Arrange appearances along scene tracks and story time. NPC groups collect background characters while keeping each member's profile and dialogue independently editable. Muted green groups, plum events and copper character controls make the canvas easier to read.

_{One level · two scenes · three characters · a once-only event. Actual application capture.}

Connect dialogue cards and player choices. Put availability conditions beside the response that needs them, and see why a choice is unavailable. In temporary card play, adjust the player's test state and continue from the current card.

_{“I am injured. Please help.” becomes available when the test player is injured.}

Global rehearsal presents a scene story flow: enter a location, read environmental text, approach an available character and choose a response. Advance story time and inspect the events, character state and available text on the bottom timeline. Source links take you back to the authoring material.

_{Saved content and authored rules drive rehearsal; it does not ask a model to invent the next line.}

Use the AI assistant you already work with. The Skills explain how to translate prose into the tool's world, cast, scenes, relationships, appearances, events and dialogue structures.

English Skill   ·   中文 Skill   ·   Collaboration guide

Add one complete Skill folder to your AI tool's supported Skill location, or provide its SKILL.md and referenced resources as context. Choose the language you prefer; both packs have equivalent capabilities and include a bridge, Schema and runnable examples.

Try a prompt like:

Use the NPCs AI Studio Skill to turn this story into a new local project.
Start with one level, two scenes, a healer and a two-person background NPC group.
Give each NPC their own dialogue. Add a treatment choice gated by player injury.
Validate the project and rehearse both injured and healthy paths.
Explain your assumptions and tell me where to open the result.

An AI tool with local execution can use the bridge to validate, import and submit drafts. A cloud chat without access to your computer can prepare files for handoff; it cannot directly operate your local workbench. The bridge itself makes no model requests and does not need a platform API key. Supported collaboration Windows builds offer NPCsAIStudio.exe --skill-bridge; the standalone helper uses Python 3.10+.

Mark the dialogue in the editor, then ask your own agent to read the task. Local MCP provides the exact card IDs, saved text, world brief and relevant character/scene context. You can revise scattered cards together without copying passages, JSON or screenshots between tools.

Open a saved project and choose Agent collaboration → Connect Codex / Claude. Merge the generated configuration into your client's MCP settings, keeping existing connections. The editor supplies the actual Python/executable path, service URL and project ID.

Your client starts the local stdio adapter; keep the editor running and the configured project open. No cloud server deployment or additional workbench model key is needed for the connection. Your agent uses its own model/account. Update the configuration when the project or local service address changes. Source checkouts use scripts/npcs_mcp.py; newly built Windows packages can use NPCsAIStudio.exe --mcp.

1. Edit and mark. In the role canvas or Quick text, choose Mark dialogue and select Current text, Selected cards or Entire dialogue flow. Shift-select cards on the canvas or use the task checkboxes. A flow includes disconnected branches and authored ending lines; one task can cover up to 200 cards.
2. Create the task. Write your instructions and choose Save and create collaboration task. This saves a local task; it does not automatically send a message to your agent. Ask the agent to read it in your own chat.
3. Submit a candidate. The agent reads the exact task and submits text changes through MCP. Candidates appear in Agent collaboration → Agent tasks and Draft Review.
4. Review each card. Compare original speech and player choices with the candidate, edit if needed, then adopt or reject. Adopting one card preserves other cards already reviewed.

For example, tell your agent:

Read the latest collaboration task in NPCs.
Use the world and character context to make the dialogue voice consistent,
while preserving the story information.
Only revise marked NPC speech and player-choice text. Submit candidates for review.

Specify the task ID when several tasks are active. This workflow changes text only: speakers, card titles, connections, conditions, effects and stable IDs remain intact. Changes to the author baseline require a fresh comparison. Existing projects remain readable without migration.

Finished tasks can be deleted quickly, with immediate undo or restoration from Deleted. Deletion stops further submissions to that task while preserving its candidates and adopted dialogue. See the local MCP collaboration guide for setup, tools, storage and conflict handling.

Built-in generation uses your chosen chat/completions-compatible connection. Enable multiple model profiles, assign purpose defaults, or choose a model for a specific request.

• Choose the scope first. Generate a character profile, that character's story, a dialogue graph or a piece of environmental text.
• Make quantity explicit. NPC group generation distinguishes the number of people, dialogue cards per NPC and text length per card. Each request item targets one NPC.
• Keep the successful work. Batches contain 1–10 items with at most 2 concurrent provider calls. Cancel remaining work or retry failed items without rerunning successful ones.
• Review before adoption. Open a candidate card, read the text, inspect field differences and adopt only what you want. Confirmed fields are protected from model overwrite.

Scene NPC groups create actual character profiles and appearances. The advanced anonymous environmental text pool creates text only. Multiple enabled models provide a choice of connections; they do not automatically collaborate with each other.

Requirements: Node.js 22+ and Python 3.12+. From the repository root:

git clone https://github.com/koronto11/ludo-npc-ai.git
cd ludo-npc-ai
npm ci
npm run build
python -m venv backend/.venv
backend/.venv/Scripts/python.exe -m pip install -e './backend[dev,package]' -c backend/requirements-dev.lock
backend/.venv/Scripts/python.exe -m ludo_npc --open-browser

The service opens the local workbench after startup. Its default address is http://127.0.0.1:4174/; if the default port is occupied, it chooses an available port. Use the URL printed by the launcher. Projects and application settings use your user folders by default.

python3 -m venv backend/.venv
backend/.venv/bin/python -m pip install -e './backend[dev,package]' -c backend/requirements-dev.lock
backend/.venv/bin/python -m ludo_npc --open-browser

1. Create a local project and choose its parent folder. The tool creates a project folder with the same name.
2. Write the world brief: shared premise, confirmed rules and writing style. Add regional details in the level settings.
3. Create characters and scenes, then place appearances on the level canvas. Use an NPC group for a set of background residents.
4. Write or generate dialogue. For AI candidates, adopt the desired text in Draft Review before testing it.
5. Try the choices in the role workbench, then rehearse the scene flow globally.
6. Save and hand off a reopenable project, design notes or a dialogue table.

No API key is required for manual authoring, local rehearsal or Skill bridge operations. Configure a model and your own key only when using the workbench's remote generation or connection test. Those requests go to your selected provider.

The screenshots come from the original bilingual Skill example: a player arrives at a windy dock, meets two townsfolk, visits a healer and can request treatment when injured. A dock alarm occurs at story minute 10. A clinic note supplies environmental text.

With the workbench running at the address shown below, compile the English example from the repository root:

backend/.venv/Scripts/python.exe skills/npcs-ai-studio-en/scripts/npc_studio_bridge.py --base-url http://127.0.0.1:4174 compile --input skills/npcs-ai-studio-en/assets/storyboard-example.json --output tide-town.ludo.json

Replace the URL with your actual local address when it differs. Compilation validates through the running service and refuses an existing output file. Use Project → Open local project to select the new file. This is an authored demonstration, not a showcase of real provider output.

Project exports, templates and Skills do not include stored model credentials. Changing a connection destination requires re-entering its key; copying a model profile does not copy the key. Editing and deterministic rehearsal work offline. Built-in remote generation sends its story context to the connection you choose.

The interface and help switch between 中文 / English. This changes the UI language, not the project's story text or the model's output language.

Current mainline: 0.1.0 preview. Authoring, local storage, draft review, model connection workflows, bilingual Skills, local MCP collaboration and deterministic rehearsal are implemented. Provider compatibility and output quality depend on the selected service; protocol fixtures do not establish real-model quality acceptance.

Next milestones include clean Windows machine acceptance, release packaging, broader real-provider verification, and dedicated engine handoff adapters. Current exports are JSON, Markdown and CSV. The workbench plans narrative text; it does not create 3D characters or run a game engine. Knowledge, conditions and effects are authored explicitly; natural-language secrets and contradictions still need the author's review.

Built with React · Vite · React Flow · Python · FastAPI · Pydantic, backed by local JSON files. Start with Contributing, backend setup, Security and the Changelog. Historical visual evidence is indexed here.

Project-authored code, documentation and bilingual Skills are MIT licensed. Third-party fonts and libraries retain their upstream licenses. See asset and brand licensing for visual material and brand scope. Public installer acceptance remains a separate milestone.

If NPCs AI Studio helps your creative work, consider starring the repository, sharing it, reporting issues or contributing. You can also buy the maintainer a coffee through WeChat. Contributions are entirely voluntary; no payment is required to use the project.

_{Scan with WeChat · Click the image for full size}

Give every NPC a place, a voice and a reason to be there.
_{NPCs AI Studio · Story, cast, conversation.}