ludo-npc-ai

A story deserves more than a wall of text

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

Inside the workbench

01 · Direct the scene

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.

02 · Write the branch, then try it

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.

03 · Walk through the story

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.

Your AI, working alongside your workbench

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.

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+.

Revise dialogue with your local Codex or Claude Code

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.

Connect once

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.

Mark → Read → Propose → Review

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.

Generate less guesswork, review more deliberately

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.

Get started

Run from source

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.

After cloning the repository and running npm ci and npm run build:

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

These are source-run instructions. Windows packaging and encrypted credential remembering are separate platform features; macOS/Linux credentials currently stay in the session.

When you have a built folder package, keep its whole directory and launch NPCsAIStudio.exe. It starts the same local service and opens the browser workbench. See the Windows preview guide for packaging and acceptance details. Clean-machine release acceptance and public distribution are still pending; this README does not link a public installer.

Build your first playable slice

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.

Try Tide Town

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.

A local project you can keep

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.

Find your next step

Preview status & next milestones

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.

Star History

Support the project

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.