Jesse.Markowitz/interactive-story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Make NPCs a dedicated section with per-NPC stats

Browse Source 
Replace the single shared `npc` stat template (+ npc_card_types) with an
`npcs` section: each NPC keyed by a stable id, carrying its own name,
description, trigger keys, and its OWN stats block. The AI addresses NPCs
as npc.<id>.<stat> (id shown in context), which also fixes the old
card-id-guessing problem. On adventure creation each NPC auto-creates a
story card (name/keys/desc) for lore + in-scene detection, unless a
same-name card already exists. All NPCs instantiate up front.

- engine: npcs instantiate/apply/render/reference, npc_name/npc_triggers
- builder: _visible_npcs matches each NPC's own keys
- create_adventure: auto-create story cards from npcs
- WorldStateDrawer: render defined NPCs with their own stats + desc tooltip
- demo seed: Gwen (health/trust) + Bandit Leader (health/aggression)
- tests updated (34 pass); no new migration (npcs lives in stat_schema JSON)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parththakkar106
2026-07-21 15:17:47 +05:30
co-authored by Claude Opus 4.8
parent 4dac445f90
commit cf464a48b0
10 changed files with 206 additions and 106 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/app/context/builder.py
+6 -9
View File
@@ -57,19 +57,16 @@ def _script_memory(adventure: models.Adventure) -> dict:
def _visible_npcs(adventure: models.Adventure, stat_schema: dict) -> dict[str, str]:
"""NPC story cards (by schema-configured type) whose keys appear in the
recent story — the ones "in scene", so only their stats get injected."""
"""Defined NPCs whose trigger words appear in the recent story — the ones
"in scene", so only their stats get injected. Maps npc id -> display name."""
actions = [a for a in adventure.actions if a.text.strip()]
recent = SEPARATOR.join(a.text for a in actions[-6:]).lower()
types = worldstate.npc_types(stat_schema)
visible: dict[str, str] = {}
for card in adventure.story_cards:
if (card.type or "").lower() not in types:
for npc_key, ndef in (stat_schema.get("npcs") or {}).items():
if not isinstance(ndef, dict):
continue
for key in (k.strip().lower() for k in card.keys.split(",")):
if key and key in recent:
visible[str(card.id)] = card.name or f"NPC {card.id}"
break
if any(trigger in recent for trigger in worldstate.npc_triggers(ndef, npc_key)):
visible[npc_key] = worldstate.npc_name(ndef, npc_key)
return visible
backend/app/routers/adventures.py
+19
View File
@@ -98,6 +98,7 @@ def create_adventure(
db.flush()
if scenario:
existing_names = {(c.name or "").strip().lower() for c in scenario.story_cards}
for card in scenario.story_cards:
db.add(
models.StoryCard(
@@ -109,6 +110,24 @@ def create_adventure(
notes=card.notes,
)
)
# Phase 12: each defined NPC gets a story card (for its description as
# lore + in-scene triggering), unless a card with that name already exists.
for npc_key, ndef in (scenario.stat_schema or {}).get("npcs", {}).items():
if not isinstance(ndef, dict):
continue
name = worldstate.npc_name(ndef, npc_key)
if name.strip().lower() in existing_names:
continue
db.add(
models.StoryCard(
adventure_id=adventure.id,
type="character",
name=name,
keys=fill_placeholders(str(ndef.get("keys") or name), values),
entry=fill_placeholders(str(ndef.get("desc") or ""), values),
notes="",
)
)
for position, script in enumerate(scenario.scripts):
db.add(
models.AdventureScript(
backend/app/seed_data/04-rpg-world-state.json
+36 -19
View File
@@ -7,7 +7,6 @@
"ai_instructions": "Write in second person, present tense. End each reply where the player can act. Let the world state guide the fiction — if the player is badly hurt, show it.",
"tags": "demo, rpg, world-state, combat, short",
"stat_schema": {
"npc_card_types": ["character"],
"world": {
"day": { "type": "counter", "min": 1, "initial": 1, "desc": "Which in-game day it is; only ever counts up." }
},
@@ -28,18 +27,43 @@
"alarm_raised": { "desc": "True once the bandits know they're under attack; stealth is blown.", "initial": false },
"player_hidden": { "desc": "True while the player is out of sight in cover.", "initial": true }
},
"npc": {
"health": {
"desc": "This companion's physical health.",
"min": 0, "max": 100, "initial": 100, "max_delta_per_turn": 35,
"bands": [[0, 1, "dead"], [1, 25, "gravely wounded"], [25, 50, "hurt"],
[50, 80, "scratched"], [80, 101, "healthy"]]
"npcs": {
"gwen": {
"name": "Gwen",
"keys": "Gwen, ranger, her",
"desc": "A loyal ranger and the player's ally. Quick with a bow, dry-humoured, fiercely protective. Her trust rises when the player fights smart and watches her back, and falls when they are reckless with her life.",
"stats": {
"health": {
"desc": "Gwen's physical health.",
"min": 0, "max": 100, "initial": 100, "max_delta_per_turn": 35,
"bands": [[0, 1, "dead"], [1, 25, "gravely wounded"], [25, 50, "hurt"],
[50, 80, "scratched"], [80, 101, "healthy"]]
},
"trust": {
"desc": "How much Gwen trusts the player; rises with smart, loyal play and falls with recklessness.",
"min": -100, "max": 100, "initial": 20, "max_delta_per_turn": 20,
"bands": [[-100, -30, "hostile"], [-30, 30, "wary"], [30, 70, "friendly"],
[70, 101, "devoted"]]
}
}
},
"trust": {
"desc": "How much this companion trusts the player; rises with smart, loyal play and falls with recklessness.",
"min": -100, "max": 100, "initial": 20, "max_delta_per_turn": 20,
"bands": [[-100, -30, "hostile"], [-30, 30, "wary"], [30, 70, "friendly"],
[70, 101, "devoted"]]
"bandit_leader": {
"name": "Bandit Leader",
"keys": "leader, chief, boss, scarred",
"desc": "The scarred leader of the bandit camp, guarding the strongbox. Fights harder the more cornered he becomes.",
"stats": {
"health": {
"desc": "The leader's physical health.",
"min": 0, "max": 120, "initial": 120, "max_delta_per_turn": 40,
"bands": [[0, 1, "dead"], [1, 30, "near death"], [30, 70, "bloodied"],
[70, 121, "unhurt"]]
},
"aggression": {
"desc": "How aggressively the leader fights; climbs as the fight turns against him.",
"min": 0, "max": 100, "initial": 40, "max_delta_per_turn": 25,
"bands": [[0, 30, "cautious"], [30, 70, "fierce"], [70, 101, "berserk"]]
}
}
}
},
"milestones": {
@@ -49,13 +73,6 @@
}
},
"story_cards": [
{
"type": "character",
"name": "Gwen",
"keys": "Gwen, ranger, her",
"entry": "Gwen is a loyal ranger and the player's ally. Quick with a bow, dry-humoured, fiercely protective. Her trust in the player rises when they fight smart and watch her back, and falls when they are reckless with her life.",
"notes": ""
},
{
"type": "location",
"name": "Bandit Camp",
backend/app/worldstate/__init__.py
+4 -2
View File
@@ -8,7 +8,8 @@ from .engine import (
extract_delta,
has_schema,
instantiate,
npc_types,
npc_name,
npc_triggers,
render_reference,
render_state_section,
)
@@ -20,7 +21,8 @@ __all__ = [
"extract_delta",
"has_schema",
"instantiate",
"npc_types",
"npc_name",
"npc_triggers",
"render_reference",
"render_state_section",
]
backend/app/worldstate/engine.py
+53 -27
View File
@@ -16,18 +16,18 @@ import re
# stat_schema top-level sections that hold stat definitions.
STAT_SECTIONS = ("world", "player")
DEFAULT_NPC_TYPES = ("character", "npc")
# Appended once to the system prompt so the model knows how to report changes.
EMIT_RULE = (
"After your narration, if and ONLY IF something in the world state changed this "
"turn, append a fenced code block labelled `state` containing a JSON object of "
"the CHANGES ONLY, as deltas (not new totals). Use paths like "
'"player.hp", "world.day", "npc.<id>.trust"; "flags.<name>": true or false to '
'toggle an on/off state; and "milestones.<id>": true when an objective is '
"completed. Send only things that actually changed; never restate unchanged "
"values. If nothing changed, omit the block entirely. Example:\n"
'```state\n{"player.hp": -15, "flags.has_key": true, "milestones.escaped": true}\n```'
'"player.hp", "world.day", "npc.<id>.<stat>" (use the exact npc id shown in the '
'world state, e.g. npc.gwen.trust); "flags.<name>": true or false to toggle an '
'on/off state; and "milestones.<id>": true when an objective is completed. Send '
"only things that actually changed; never restate unchanged values. If nothing "
"changed, omit the block entirely. Example:\n"
'```state\n{"player.hp": -15, "npc.gwen.trust": 5, "milestones.escaped": true}\n```'
)
# ```state { ... } ``` (also tolerates ```json or an unlabelled fence); DOTALL.
@@ -42,14 +42,20 @@ def has_schema(stat_schema: dict | None) -> bool:
return False
return any(
isinstance(stat_schema.get(k), dict) and stat_schema[k]
for k in (*STAT_SECTIONS, "npc", "milestones", "flags")
for k in (*STAT_SECTIONS, "npcs", "milestones", "flags")
)
def npc_types(stat_schema: dict) -> set[str]:
raw = stat_schema.get("npc_card_types")
types = raw if isinstance(raw, list) and raw else DEFAULT_NPC_TYPES
return {str(t).lower() for t in types}
def npc_name(ndef: dict, key: str) -> str:
name = ndef.get("name")
return name.strip() if isinstance(name, str) and name.strip() else key
def npc_triggers(ndef: dict, key: str) -> list[str]:
"""Lower-cased trigger words for detecting an NPC in scene: its `keys`
field, falling back to its display name."""
raw = ndef.get("keys") or npc_name(ndef, key)
return [k.strip().lower() for k in str(raw).split(",") if k.strip()]
def _initials(defs: dict) -> dict:
@@ -67,7 +73,12 @@ def instantiate(stat_schema: dict | None) -> dict:
ws: dict = {}
for section in STAT_SECTIONS:
ws[section] = _initials(stat_schema.get(section) or {})
ws["npc"] = {} # per-card, filled lazily on first change
# Each defined NPC gets its own stat block from its own `stats` defs.
ws["npc"] = {
key: _initials(ndef.get("stats") or {})
for key, ndef in (stat_schema.get("npcs") or {}).items()
if isinstance(ndef, dict)
}
ws["milestones"] = {} # only reached ones are stored
ws["flags"] = {
name: bool(d.get("initial", False))
@@ -216,7 +227,7 @@ def apply_delta(world_state: dict, stat_schema: dict, delta: dict,
milestones = stat_schema.get("milestones") or {}
flag_defs = stat_schema.get("flags") or {}
npc_defs = stat_schema.get("npc") or {}
npcs = stat_schema.get("npcs") or {}
for raw_path, change in delta.items():
path = str(raw_path)
@@ -265,14 +276,19 @@ def apply_delta(world_state: dict, stat_schema: dict, delta: dict,
action_index, meta, report)
continue
# npc.<cardId>.<stat>
# npc.<npcId>.<stat> — each NPC has its own stat defs.
if parts[0] == "npc" and len(parts) == 3:
stat_def = npc_defs.get(parts[2])
ndef = npcs.get(parts[1])
if not isinstance(ndef, dict):
report["rejected"].append({"path": path, "reason": "unknown npc"})
continue
stat_defs = ndef.get("stats") or {}
stat_def = stat_defs.get(parts[2])
if not isinstance(stat_def, dict):
report["rejected"].append({"path": path, "reason": "unknown npc stat"})
continue
npcs = ws.setdefault("npc", {})
container = npcs.setdefault(parts[1], _initials(npc_defs))
npc_state = ws.setdefault("npc", {})
container = npc_state.setdefault(parts[1], _initials(stat_defs))
_apply_stat(container, parts[2], stat_def, change, path,
action_index, meta, report)
continue
@@ -316,13 +332,16 @@ def render_state_section(world_state: dict, stat_schema: dict,
if player_line:
lines.append(f"You: {player_line}.")
npc_defs = stat_schema.get("npc") or {}
npcs = stat_schema.get("npcs") or {}
npc_state = ws.get("npc") or {}
for card_id, name in visible_npcs.items():
values = npc_state.get(card_id) or _initials(npc_defs)
npc_line = _stat_line(npc_defs, values)
for npc_key, name in visible_npcs.items():
ndef = npcs.get(npc_key) or {}
stat_defs = ndef.get("stats") or {}
values = npc_state.get(npc_key) or _initials(stat_defs)
npc_line = _stat_line(stat_defs, values)
if npc_line:
lines.append(f"{name}: {npc_line}.")
# Show the id so the AI can address it as npc.<id>.<stat>.
lines.append(f"{name} (npc.{npc_key}): {npc_line}.")
flag_defs = stat_schema.get("flags") or {}
flag_state = ws.get("flags") or {}
@@ -380,11 +399,18 @@ def render_reference(stat_schema: dict) -> str:
row = _describe_stat(name, d)
if row:
lines.append(row)
for name, d in (stat_schema.get("npc") or {}).items():
if isinstance(d, dict):
row = _describe_stat(f"NPC {name}", d)
if row:
lines.append(row)
for npc_key, ndef in (stat_schema.get("npcs") or {}).items():
if not isinstance(ndef, dict):
continue
name = npc_name(ndef, npc_key)
desc = ndef.get("desc")
if isinstance(desc, str) and desc.strip():
lines.append(f"NPC {name} ({npc_key}) — {desc.strip().rstrip('.')}.")
for sname, sdef in (ndef.get("stats") or {}).items():
if isinstance(sdef, dict):
row = _describe_stat(f"{name} {sname}", sdef)
if row:
lines.append(row)
for name, d in (stat_schema.get("flags") or {}).items():
if isinstance(d, dict):
desc = d.get("desc")