Add roleplay, relationships, adventure log, and cross-adventure carry-over

Persistent campaign characters: ideals/bonds/flaws/appearance (captured in
the creator, fed to the DM for portrayal); relationships and an adventure
log carried on the canonical character. New DM tools — grant_item,
adjust_gold, award_xp (with SRD level-up that recomputes HP/prof/slots),
and record_relationship — write back to the stored character so gains
persist across adventures (the engine tool layer now takes the store).
Postgres gains an `extra` JSONB column for xp/adventureLog; roleplay and
relationships ride in the sheet JSONB. ensureCharacterFields backfills the
new fields. Sheet UI shows XP, roleplay, relationships, and the log.
1 carry-over test (34 server, 80 engine).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: SociableSteve

packages/engine/src/creature.ts

@@ -41,6 +41,23 @@ export interface Spellcasting {
   known: SpellRef[];
 }
 
+/** Free-text roleplay cues (not used by rules; carried with the sheet for the DM). */
+export interface Roleplay {
+  ideals?: string;
+  bonds?: string;
+  flaws?: string;
+  traits?: string;
+  appearance?: string;
+}
+
+/** A known NPC/faction relationship, accrued through play. */
+export interface Relationship {
+  name: string;
+  kind: string; // ally | rival | mentor | faction | contact …
+  disposition: string; // friendly | hostile | wary | owes-a-debt …
+  notes?: string;
+}
+
 /** An inventory item. */
 export interface Item {
   id: string;
@@ -93,6 +110,10 @@ export interface Creature {
   inventory?: Item[];
   /** Gold pieces. */
   gold?: number;
+  /** Roleplay cues (for the DM's portrayal). */
+  roleplay?: Roleplay;
+  /** Known NPCs/factions (accrued through play; carried between adventures). */
+  relationships?: Relationship[];
 }
 
 /** A fully-derived skill line for display / DM context. */

packages/server/src/backend.test.ts

@@ -11,7 +11,7 @@ import { createRealtime } from "./realtime.js";
 import { GameRuntime } from "./runtime.js";
 import { getAdventureTemplate } from "./adventureTemplates.js";
 import { buildStateContext } from "./dm.js";
-import { appendLog, createSession, fromSnapshot, toSnapshot } from "./session.js";
+import { addCharacterToSession, appendLog, createSession, fromSnapshot, toSnapshot } from "./session.js";
 import { buildCharacter, ensureCharacterFields } from "./srd.js";
 import { suggestCharacterBuild } from "./suggest.js";
 import { JsonStore, newId, type Character, type User } from "./store.js";
@@ -114,6 +114,37 @@ describe("character sheet: spells, inventory, gold", () => {
   });
 });
 
+describe("carry-over tools persist to the canonical character", () => {
+  it("grant_item, award_xp (with level-up), and record_relationship write back to the store", async () => {
+    const store = tmpStore();
+    const images = new PlaceholderImageProvider();
+    const d = buildCharacter({
+      name: "Kael", raceId: "human", classId: "fighter", backgroundId: "soldier",
+      level: 1, baseScores: ARRAY, chosenSkills: ["athletics", "perception"],
+    });
+    const character: Character = {
+      id: d.creature.id, userId: "u", name: d.creature.name, createdAt: Date.now(), xp: 0, adventureLog: [],
+      meta: { race: d.meta.race, className: d.meta.className, background: d.meta.background, level: d.meta.level },
+      sheet: { creature: d.creature, attack: d.attack },
+    };
+    await store.createCharacter(character);
+
+    const session = createSession("adv", "A", 1);
+    addCharacterToSession(session, structuredClone(d.creature), d.attack);
+    const tools = createTools(session, images, store);
+
+    await tools.grantItem(character.id, "Healing Potion", 2, "consumable");
+    await tools.awardXp(character.id, 350); // crosses the level-2 threshold (300)
+    await tools.recordRelationship(character.id, { name: "Duke Aldric", kind: "noble", disposition: "owes-a-debt" });
+
+    const saved = (await store.getCharacter(character.id))!;
+    expect(saved.sheet.creature.inventory!.some((i) => i.name === "Healing Potion")).toBe(true);
+    expect(saved.xp).toBe(350);
+    expect(saved.meta.level).toBe(2); // leveled up
+    expect(saved.sheet.creature.relationships!.some((r) => r.name === "Duke Aldric")).toBe(true);
+  });
+});
+
 describe("suggestCharacterBuild (heuristic, no model configured)", () => {
   it("maps a devout back-story to a cleric", async () => {
     const s = await suggestCharacterBuild("A devout priest raised in a mountain temple, sworn to her god.");

packages/server/src/dm.ts

@@ -251,6 +251,93 @@ const DM_TOOLS: DMTool[] = [
         : `No level-${level} spell slots remaining.`;
     },
   },
+  {
+    spec: {
+      type: "function",
+      function: {
+        name: "grant_item",
+        description: "Give the player an item (loot, reward, purchase). Persists to their character across adventures.",
+        parameters: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            quantity: { type: "integer" },
+            item_type: { type: "string", description: "weapon | armor | gear | consumable | treasure | wondrous" },
+            description: { type: "string" },
+          },
+          required: ["name"],
+        },
+      },
+    },
+    async execute(ctx, a) {
+      const pc = ctx.tools.playerCharacter(ctx.playerId);
+      if (!pc) return "No character.";
+      await ctx.tools.grantItem(pc.id, str(a.name, "an item"), num(a.quantity, 1), str(a.item_type, "gear"), a.description ? str(a.description) : undefined);
+      return `Granted ${str(a.name)}.`;
+    },
+  },
+  {
+    spec: {
+      type: "function",
+      function: {
+        name: "adjust_gold",
+        description: "Add or subtract gold pieces from the player (negative to spend). Persists across adventures.",
+        parameters: { type: "object", properties: { amount: { type: "integer" } }, required: ["amount"] },
+      },
+    },
+    async execute(ctx, a) {
+      const pc = ctx.tools.playerCharacter(ctx.playerId);
+      if (!pc) return "No character.";
+      const total = await ctx.tools.adjustGold(pc.id, num(a.amount, 0));
+      return `Gold is now ${total} gp.`;
+    },
+  },
+  {
+    spec: {
+      type: "function",
+      function: {
+        name: "award_xp",
+        description: "Award experience points for overcoming a challenge. Persists and may level the character up.",
+        parameters: { type: "object", properties: { amount: { type: "integer" } }, required: ["amount"] },
+      },
+    },
+    async execute(ctx, a) {
+      const pc = ctx.tools.playerCharacter(ctx.playerId);
+      if (!pc) return "No character.";
+      const r = await ctx.tools.awardXp(pc.id, num(a.amount, 0));
+      return r.leveledUp ? `Awarded XP — leveled up to ${r.level}!` : "XP awarded.";
+    },
+  },
+  {
+    spec: {
+      type: "function",
+      function: {
+        name: "record_relationship",
+        description: "Record or update a relationship with an NPC or faction the player has met. Persists across adventures.",
+        parameters: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+            kind: { type: "string", description: "ally | rival | mentor | faction | contact" },
+            disposition: { type: "string", description: "friendly | hostile | wary | owes-a-debt …" },
+            notes: { type: "string" },
+          },
+          required: ["name", "disposition"],
+        },
+      },
+    },
+    async execute(ctx, a) {
+      const pc = ctx.tools.playerCharacter(ctx.playerId);
+      if (!pc) return "No character.";
+      await ctx.tools.recordRelationship(pc.id, {
+        name: str(a.name),
+        kind: str(a.kind, "contact"),
+        disposition: str(a.disposition, "neutral"),
+        notes: a.notes ? str(a.notes) : undefined,
+      });
+      return `Noted relationship with ${str(a.name)}.`;
+    },
+  },
   {
     spec: {
       type: "function",
@@ -389,6 +476,7 @@ TOOLS:
 - start_combat when a fight begins (name the enemies + count + difficulty).
 - player_attack when the player attacks a target on their turn — the engine also resolves the enemies' turns and tells you what happened.
 - end_combat when the fight is over or the party flees.
+- grant_item / adjust_gold when the player finds loot, is rewarded, or spends; award_xp for overcoming challenges; record_relationship when they meet or change standing with an NPC/faction. These persist on the character across adventures — use the PC's roleplay cues and relationships (in CURRENT STATE) to make the story personal.
 
 After calling tools, write the narration the player will read. If no mechanics are needed, just narrate. NEVER write a tool name or its JSON arguments in your narration text — either call the tool or speak as the DM, never both.`;
 
@@ -432,6 +520,21 @@ function describePlayerSheet(c: Creature): string {
     }
   }
 
+  const rp = c.roleplay;
+  if (rp && (rp.ideals || rp.bonds || rp.flaws || rp.traits)) {
+    const bits = [
+      rp.traits && `traits: ${rp.traits}`,
+      rp.ideals && `ideals: ${rp.ideals}`,
+      rp.bonds && `bonds: ${rp.bonds}`,
+      rp.flaws && `flaws: ${rp.flaws}`,
+    ].filter(Boolean);
+    out.push(`      Roleplay — ${bits.join("; ")}`);
+  }
+
+  if (c.relationships?.length) {
+    out.push(`      Relationships: ${c.relationships.map((r) => `${r.name} (${r.disposition})`).join(", ")}`);
+  }
+
   const inv = c.inventory ?? [];
   if (inv.length || c.gold != null) {
     const equipped = inv.filter((i) => i.equipped).map((i) => i.name);

packages/server/src/gameEngine.ts

@@ -12,7 +12,9 @@ import {
   currentCombatantId,
   distanceFeet,
   endEncounter,
+  type Item,
   nextTurn,
+  type Relationship,
   resolveAttack,
   roll,
   type RollResult,
@@ -22,6 +24,8 @@ import {
 import { makeGoblin, makeMonster } from "./content.js";
 import { type ImageKind, type ImageProvider } from "./images.js";
 import { addSheet, appendLog, type Session } from "./session.js";
+import { awardXp as awardCharacterXp } from "./srd.js";
+import { newId, type Store } from "./store.js";
 
 export interface CombatStatus {
   over: boolean;
@@ -34,6 +38,11 @@ export interface DMTools {
   findLivingEnemy(name?: string): Creature | undefined;
   rollDice(notation: string, reason?: string): RollResult;
   castSpell(casterId: string, level: number, spellName: string): { ok: boolean; remaining: number };
+  /** Persistent character changes (carry over to the canonical sheet across adventures). */
+  grantItem(casterId: string, name: string, qty: number, type: string, description?: string): Promise<void>;
+  adjustGold(casterId: string, delta: number): Promise<number>;
+  awardXp(casterId: string, amount: number): Promise<{ level: number; leveledUp: boolean }>;
+  recordRelationship(casterId: string, rel: Relationship): Promise<void>;
   setScene(title: string, description: string): void;
   generateImage(kind: ImageKind, subject: string): Promise<string | undefined>;
   startCombat(enemyCount: number, opts?: { name?: string; difficulty?: string }): void;
@@ -49,7 +58,15 @@ export interface DMTools {
 const isDown = (c: Creature | undefined): boolean =>
   !c || Boolean(c.isDead) || c.currentHp === 0;
 
-export function createTools(session: Session, images: ImageProvider): DMTools {
+export function createTools(session: Session, images: ImageProvider, store?: Store): DMTools {
+  // Apply a change to the canonical stored character (carry-over) if we have a store.
+  async function updateCanonical(id: string, fn: (creatureOrChar: { creature: Creature }) => void): Promise<void> {
+    if (!store) return;
+    const ch = await store.getCharacter(id);
+    if (!ch) return;
+    fn({ creature: ch.sheet.creature });
+    await store.createCharacter(ch);
+  }
   const skipDead = (id: string) => isDown(session.creatures.get(id));
 
   function livingPCs(): Creature[] {
@@ -158,6 +175,62 @@ export function createTools(session: Session, images: ImageProvider): DMTools {
       return { ok, remaining };
     },
 
+    async grantItem(casterId, name, qty, type, description) {
+      const item: Item = { id: newId("item"), name, qty: Math.max(1, qty || 1), type, description };
+      const c = session.creatures.get(casterId);
+      if (c) c.inventory = [...(c.inventory ?? []), item];
+      await updateCanonical(casterId, ({ creature }) => {
+        creature.inventory = [...(creature.inventory ?? []), { ...item, id: newId("item") }];
+      });
+      appendLog(session, { kind: "system", text: `${c?.name ?? "Someone"} obtains ${qty > 1 ? `${qty}× ` : ""}${name}.` });
+    },
+
+    async adjustGold(casterId, delta) {
+      const c = session.creatures.get(casterId);
+      const next = Math.max(0, (c?.gold ?? 0) + delta);
+      if (c) c.gold = next;
+      await updateCanonical(casterId, ({ creature }) => {
+        creature.gold = Math.max(0, (creature.gold ?? 0) + delta);
+      });
+      appendLog(session, { kind: "system", text: `${c?.name ?? "Someone"} ${delta >= 0 ? "gains" : "spends"} ${Math.abs(delta)} gp.` });
+      return next;
+    },
+
+    async awardXp(casterId, amount) {
+      const c = session.creatures.get(casterId);
+      let result = { level: 0, leveledUp: false };
+      if (store) {
+        const ch = await store.getCharacter(casterId);
+        if (ch) {
+          result = awardCharacterXp(ch, amount);
+          await store.createCharacter(ch);
+        }
+      }
+      appendLog(session, {
+        kind: "system",
+        text: `${c?.name ?? "Someone"} gains ${amount} XP${result.leveledUp ? ` and reaches level ${result.level}! (takes effect next rest)` : ""}.`,
+      });
+      return result;
+    },
+
+    async recordRelationship(casterId, rel) {
+      const upsert = (list: Relationship[] = []): Relationship[] => {
+        const i = list.findIndex((r) => r.name.toLowerCase() === rel.name.toLowerCase());
+        if (i >= 0) {
+          const next = [...list];
+          next[i] = rel;
+          return next;
+        }
+        return [...list, rel];
+      };
+      const c = session.creatures.get(casterId);
+      if (c) c.relationships = upsert(c.relationships);
+      await updateCanonical(casterId, ({ creature }) => {
+        creature.relationships = upsert(creature.relationships);
+      });
+      appendLog(session, { kind: "system", text: `${c?.name ?? "Someone"}'s relationship with ${rel.name} is noted (${rel.disposition}).` });
+    },
+
     setScene(title, description) {
       session.scene.title = title;
       session.scene.description = description;

packages/server/src/index.ts

@@ -79,7 +79,7 @@ async function processTurn(session: Session, userId: string, text: string): Prom
   await broadcastSnapshot(session);
 
   try {
-    const tools = createTools(session, images);
+    const tools = createTools(session, images, store);
     const narration = await dm.respond({ session, playerId: userId, text, tools });
     appendLog(session, { kind: "narration", author: "Dungeon Master", text: narration });
   } catch (err) {

packages/server/src/postgres.ts

@@ -38,9 +38,12 @@ CREATE TABLE IF NOT EXISTS characters (
   portrait_description text,
   meta                jsonb NOT NULL,
   sheet               jsonb NOT NULL,
+  extra               jsonb,
   created_at          bigint NOT NULL
 );
 CREATE INDEX IF NOT EXISTS characters_user_id_idx ON characters (user_id);
+-- For tables created before the extra column existed:
+ALTER TABLE characters ADD COLUMN IF NOT EXISTS extra jsonb;
 
 CREATE TABLE IF NOT EXISTS adventures (
   id                   text PRIMARY KEY,
@@ -71,6 +74,7 @@ function rowToUser(r: Record<string, unknown>): User {
 }
 
 function rowToCharacter(r: Record<string, unknown>): Character {
+  const extra = (r.extra as { xp?: number; adventureLog?: Character["adventureLog"] } | null) ?? {};
   return {
     id: r.id as string,
     userId: r.user_id as string,
@@ -79,6 +83,8 @@ function rowToCharacter(r: Record<string, unknown>): Character {
     portraitUrl: (r.portrait_url as string) ?? undefined,
     portraitVariant: (r.portrait_variant as number) ?? undefined,
     portraitDescription: (r.portrait_description as string) ?? undefined,
+    xp: extra.xp,
+    adventureLog: extra.adventureLog,
     meta: r.meta as Character["meta"],
     sheet: r.sheet as Character["sheet"],
     createdAt: Number(r.created_at),
@@ -136,14 +142,14 @@ export class PostgresStore implements Store {
   async createCharacter(c: Character): Promise<void> {
     // Upsert — also used to persist portrait regeneration.
     await this.pool.query(
-      `INSERT INTO characters (id,user_id,name,backstory,portrait_url,portrait_variant,portrait_description,meta,sheet,created_at)
-       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10)
+      `INSERT INTO characters (id,user_id,name,backstory,portrait_url,portrait_variant,portrait_description,meta,sheet,extra,created_at)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
        ON CONFLICT (id) DO UPDATE SET
          name=EXCLUDED.name, backstory=EXCLUDED.backstory, portrait_url=EXCLUDED.portrait_url,
          portrait_variant=EXCLUDED.portrait_variant, portrait_description=EXCLUDED.portrait_description,
-         meta=EXCLUDED.meta, sheet=EXCLUDED.sheet`,
+         meta=EXCLUDED.meta, sheet=EXCLUDED.sheet, extra=EXCLUDED.extra`,
       [c.id, c.userId, c.name, c.backstory ?? null, c.portraitUrl ?? null, c.portraitVariant ?? null,
-        c.portraitDescription ?? null, J(c.meta), J(c.sheet), c.createdAt],
+        c.portraitDescription ?? null, J(c.meta), J(c.sheet), J({ xp: c.xp ?? 0, adventureLog: c.adventureLog ?? [] }), c.createdAt],
     );
   }
   async listCharacters(userId: string): Promise<Character[]> {

packages/server/src/routes.ts

@@ -136,6 +136,8 @@ export async function registerRoutes(app: FastifyInstance, store: Store, images:
         createdAt: Date.now(),
         backstory: typeof body.backstory === "string" ? body.backstory.slice(0, 4000) : undefined,
         portraitVariant: 0,
+        xp: 0,
+        adventureLog: [],
         meta: {
           race: derived.meta.race,
           className: derived.meta.className,