Npcforge
Branching NPC dialogue generator with Yarn Spinner export, powered by afterimage.
Ask AI about Npcforge
Powered by Claude Β· Grounded in docs
I know everything about Npcforge. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
npcforge
Lore-grounded NPC cast and dialogue for games: structured synthetic text (character sheets, branching walk-up lines, bark pools) with Yarn Spinner export, linting, and optional engine sync for Unity and Unreal.
Powered by afterimage (structured LLM calls and multi-provider support). The same workflows run from the CLI, Python async tools, or an MCP server so agents and CI can drive generation locally with your API keys.
What you get
| Layer | Role |
|---|---|
| World | lore/*.md β cached world profile (genre, tone, rating, taboo terms). |
| Cast | characters.yaml β full NpcSheet rows or _generate stubs; optional tier / status for production tracking. |
| Player | player_intents.yaml β what the player does per turn; NPCs may whitelist via allowed_intents. |
| Pipeline | npcforge build β one branch per (NPC, intent) walk-up dialogue, plus barks from barks.yaml. |
| Artefacts | out/*.yarn, manifest.json, lines.csv, lint.md β diffable, engine-ready synthetic dialogue data. |
Repository layout
src/npcforge/ # installable package
βββ cli.py # Command-line entrypoint
βββ tools.py # Pydantic tool inputs/outputs + TOOL_REGISTRY
βββ generation.py # gen_npcs, gen_intents, gen_barks, resolve_stubs, greetings, β¦
βββ pipeline.py # walk-up + barks β Yarn (run_all)
βββ schemas.py # NpcSheet, intents, barks, factions, memory, β¦
βββ prompts.py # Respondent / generator prompt bodies
βββ world_profile.py # Infer + cache setting profile
βββ project_config.py # npcforge_project.yaml: topology, depth, experimental, review_workflow
βββ narrative_preset.py
βββ narrative_scope.py # layers.yaml + scope_tags filtering
βββ game.py # Stateful terminal loop over built walk-up Yarn
βββ tape_game.py # Terminal βtapeβ demo (optional Pillow)
βββ doctor.py # npcforge doctor sanity checks
βββ export_cast.py # export cast β CSV
βββ project_init.py # npcforge init scaffold
βββ engines/ # unity / unreal sync adapters
βββ audio.py, lint.py, yarn.py, manifest.py, β¦
examples/ # demo worlds + Unity UPM sample under unity_integration/
docs/ # TOOLS, MCP, NARRATIVE_PRESET, AFTERIMAGE, β¦
tests/ # pytest suite
recording_sim/ # Static HTML playback demo (Fallen Oak Inn style)
Install
pip install -e . # CLI + library
pip install -e '.[mcp]' # MCP stdio server
pip install -e '.[tape]' # npcforge tape (GIF / terminal capture helpers)
- Python 3.10+ (see
pyproject.toml). - Optional: Yarn Spinner compiler (
ysconPATH) sonpcforge buildcan runysc compile.
API keys (override with --api-key-env / --provider / --model on LLM commands):
| Provider | Typical env var |
|---|---|
| gemini (default) | GEMINI_API_KEY |
| openai | OPENAI_API_KEY |
| deepseek | DEEPSEEK_API_KEY |
| openrouter | OPENROUTER_API_KEY |
| local | LOCAL_API_KEY |
Quick start
export GEMINI_API_KEY=...
# Optional: scaffold narrative defaults next to your YAML
npcforge init --demo-dir examples/rusted_lantern
npcforge doctor --demo-dir examples/rusted_lantern
npcforge world infer --demo-dir examples/rusted_lantern
npcforge build --demo-dir examples/rusted_lantern --mode all
npcforge play --demo-dir examples/rusted_lantern --npc mira_vesser
Narrow rebuild: npcforge build --demo-dir β¦ --only-npcs id1,id2
Voice scoring (embeddings): --score-voice on build
Skip Yarn compile: --no-validate on build
Cast spreadsheet: npcforge export cast --demo-dir β¦ β out/cast.csv
Project file: npcforge_project.yaml
Drop this beside characters.yaml (or run npcforge init). It steers how much character detail and how tight walk-up dialogue should feel.
topologyβ one of six narrative shapes (e.g.quest_rpg,social_sim,immersive_sim).depthβlean|standard|cinematic.experimentalβ optional string list for future flags.review_workflowβ whentrue, optionalNpcSheet.statusis meaningful for writer pipelines.- Legacy: a single
narrative_presetline (indie_minimal|rpg_standard|cinematic_rpg) still works; topology + depth are inferred if omitted.
CLI overrides for one run: --topology, --depth, --narrative-preset on build, gen npcs, resolve stubs.
Details: docs/NARRATIVE_PRESET.md.
Command overview
| Area | Commands |
|---|---|
| Project | init, doctor |
| Pipeline | build β walk_up / barks / all β out/, manifest, lint |
| World | world infer, world show |
| Cast | list-npcs, list-factions, resolve stubs, export cast |
Generators (gen) | npcs, intents, barks, greetings, repeat-greeting, scene, lines |
| Playback | play β one branch / bark / greeting; game β stateful loop from built .yarn |
| Demos | tape β terminal tape + optional GIF (pip install -e '.[tape]') |
| Narrative state | memory β¦, quest β¦, arc β¦ |
| Depth systems | voice β¦, player β¦, trajectory β¦, ethics β¦, emotion β¦, unseen β¦ |
| Quality | eval β curated suite β out/eval_report.* (exit 2 on failure) |
| Runtime bundles | export improv-context β JSON for engine-side improv |
| Off-script | improv β single-turn lore-grounded reply |
| Engine | engine-sync β copy .yarn + lines.csv into Unity / Unreal |
| Agents | mcp β stdio MCP server |
Run npcforge <command> --help for flags. MCP-registered tools today: infer_world_profile, show_world_profile, list_npcs, gen_npcs, gen_intents, gen_barks, resolve_stubs, gen_greetings, gen_repeat_greeting, engine_sync, build_pipeline (see docs/MCP.md).
Python API
import asyncio
from pathlib import Path
from npcforge import BuildPipelineInput, GenNpcsInput, build_pipeline, gen_npcs
async def main():
demo = Path("examples/rusted_lantern")
key = "..." # or os.environ["GEMINI_API_KEY"]
await gen_npcs(GenNpcsInput(demo_dir=demo, roles=["traveling bard"], api_key=key))
out = await build_pipeline(BuildPipelineInput(demo_dir=demo, mode="all", api_key=key))
print(out.manifest.elapsed_seconds, "s")
asyncio.run(main())
Schema reference: docs/TOOLS.md.
Example worlds
| Path | Notes |
|---|---|
examples/rusted_lantern/ | Low-fantasy tavern cast; relationships, knowledge, state evolution. |
examples/night_city_2077/ | Cyberpunk noir reference demo. |
examples/night_city_game/ | Alternate / slimmer night-city sample. |
examples/saint_denis_1899/ | Frontier western tone. |
examples/tape_game/ | Minimal demo for npcforge tape + small lore footprint. |
examples/fallen_oak_inn/ | Sword Coast inn slice (lore + cast). |
Authoring checklist for your folder: examples/AUTHORING.md.
Engine integration
npcforge engine-sync --engine unity --demo-dir path/to/world --project-dir path/to/UnityProject --install-scripts
npcforge engine-sync --engine unreal --demo-dir path/to/world --project-dir path/to/UnrealProject
Unity UPM package tree: examples/unity_integration/npcforge-unity/ (see package README inside). A mirrored Assets layout also lives under examples/unity_integration/Assets/NpcForge/ for non-UPM workflows.
Static playback demo
recording_sim/index.html β self-contained HTML terminal-style playback (no Python server); open in a browser after pointing it at exported dialogue if you wire paths for your project.
Documentation
| Doc | Purpose |
|---|---|
docs/TOOLS.md | Tool I/O models, manifest shape |
docs/MCP.md | MCP client configuration |
docs/NARRATIVE_PRESET.md | npcforge_project.yaml narrative knobs |
docs/AFTERIMAGE.md | afterimage / walk-up pipeline notes |
CHANGELOG.md | Version history |
Tests
pip install -e '.[dev]'
pytest
License
Apache License 2.0 β see LICENSE.
