feat(gameplay): enforce core SRD d20 rules

Co-authored-by: multica-agent <github@multica.ai>

apps/web/components/CoauthorWorldPreview.vue

@@ -29,7 +29,7 @@ function updateInventory(companion: CharacterDraft, event: Event) {
       <section class="wide private-truth"><label>PRIVATE GM TRUTH</label><textarea v-model="draft.hiddenThreat" rows="4" /><small>This hidden threat or goal is visible only to the owner and the Groundkeeper.</small></section>
       <section class="wide"><label>KEY PEOPLE</label><div class="entities"><article v-for="npc in draft.npcs" :key="npc.id"><small>NPC</small><input v-model="npc.name"><textarea v-model="npc.summary" rows="3" /></article></div></section>
       <section class="wide"><label>FACTIONS</label><div class="entities two"><article v-for="faction in draft.factions" :key="faction.id"><small>FACTION</small><input v-model="faction.name"><textarea v-model="faction.summary" rows="3" /></article></div></section>
-      <section class="wide"><label>AI COMPANIONS</label><p class="section-note">These universe-specific heroes join the campaign automatically.</p><div class="entities companion-grid"><article v-for="(companion, index) in draft.companions" :key="index" class="companion-card"><small>AI HERO</small><input v-model="companion.name" maxlength="80" aria-label="Companion name"><textarea v-model="companion.concept" maxlength="600" rows="4" aria-label="Companion concept" /><div class="companion-stats"><label>HP<input v-model.number="companion.hp" type="number" min="1" :max="companion.maxHp"></label><label>MAX<input v-model.number="companion.maxHp" type="number" min="1" max="100"></label><label>DEF<input v-model.number="companion.defense" type="number" min="1" max="40"></label><label>PROF<input v-model.number="companion.proficiency" type="number" min="1" max="10"></label><label v-for="ability in (['str','dex','con','int','wis','cha'] as const)" :key="ability">{{ ability }}<input v-model.number="companion.abilities[ability]" type="number" min="1" max="30"></label></div><label class="inventory-label">INVENTORY<input :value="companion.inventory.join(', ')" maxlength="800" @input="updateInventory(companion, $event)"></label><details><summary>VOICE & PERSONALITY</summary><input v-model="companion.persona.voice" maxlength="240" placeholder="Voice"><input v-model="companion.persona.motivation" maxlength="300" placeholder="Motivation"><input v-model="companion.persona.flaw" maxlength="300" placeholder="Flaw"><input v-model="companion.persona.bond" maxlength="300" placeholder="Bond"></details></article></div></section>
+      <section class="wide"><label>AI COMPANIONS</label><p class="section-note">These universe-specific heroes join the campaign automatically.</p><div class="entities companion-grid"><article v-for="(companion, index) in draft.companions" :key="index" class="companion-card"><small>AI HERO</small><input v-model="companion.name" maxlength="80" aria-label="Companion name"><textarea v-model="companion.concept" maxlength="600" rows="4" aria-label="Companion concept" /><div class="companion-stats"><label>HP<input v-model.number="companion.hp" type="number" min="1" :max="companion.maxHp"></label><label>MAX<input v-model.number="companion.maxHp" type="number" min="1" max="100"></label><label>AC<input v-model.number="companion.defense" type="number" min="1" max="40"></label><label>PROF<input v-model.number="companion.proficiency" type="number" min="1" max="10"></label><label v-for="ability in (['str','dex','con','int','wis','cha'] as const)" :key="ability">{{ ability }}<input v-model.number="companion.abilities[ability]" type="number" min="1" max="30"></label></div><label class="inventory-label">INVENTORY<input :value="companion.inventory.join(', ')" maxlength="800" @input="updateInventory(companion, $event)"></label><details><summary>VOICE & PERSONALITY</summary><input v-model="companion.persona.voice" maxlength="240" placeholder="Voice"><input v-model="companion.persona.motivation" maxlength="300" placeholder="Motivation"><input v-model="companion.persona.flaw" maxlength="300" placeholder="Flaw"><input v-model="companion.persona.bond" maxlength="300" placeholder="Bond"></details></article></div></section>
       <section><label>OPENING SCENE</label><textarea v-model="draft.openingScene" rows="6" /></section>
       <section><label>CONTENT BOUNDARIES</label><div v-for="(_, index) in draft.contentBoundaries" :key="index" class="boundary"><input v-model="draft.contentBoundaries[index]"><button type="button" aria-label="Remove boundary" @click="draft.contentBoundaries.splice(index, 1)">×</button></div><button class="add" type="button" @click="draft.contentBoundaries.push('')">＋ ADD BOUNDARY</button></section>
     </div>

apps/web/composables/useDemo.ts

@@ -41,7 +41,7 @@ export function useDemo() {
   const history = useState<Array<{ type: 'narration' | 'action' | 'roll'; author: string; body: string; meta?: string }>>('history', () => [
     { type: 'narration', author: 'GROUNDKEEPER', body: defaultWorld.openingScene, meta: 'ROUND 03 · NOW' },
     { type: 'action', author: 'MARA VALE', body: 'I ask the Orison to isolate the transmission and compare the voiceprint to mine.', meta: 'READY' },
-    { type: 'roll', author: 'SYSTEM CHECK', body: 'Intelligence check · 1d20 + 3 = 17', meta: 'SUCCESS · DC 14' },
+    { type: 'roll', author: 'SYSTEM CHECK', body: 'Intelligence check · 1d20 + 1 = 15', meta: 'SUCCESS · DC 14' },
   ])
   const currentAction = useState('current-action', () => '')
   const ready = useState('ready', () => false)

apps/web/pages/campaign/[id].vue

@@ -74,7 +74,7 @@ const timeline = computed(() => {
     })),
     ...payload.value.diceRolls.map(roll => ({
       id: `roll-${roll.id}`, type: 'roll', at: roll.created_at ?? '', label: 'SERVER ROLL',
-      meta: roll.success === null || roll.success === undefined ? roll.check_kind : roll.success ? 'SUCCESS' : 'FAILED',
+      meta: rollMeta(roll),
       body: `${roll.formula} · [${(roll.rolls ?? []).join(', ')}] ${signed(Number(roll.modifier ?? 0))} = ${roll.total}`,
     })),
     ...payload.value.events.map(event => ({
@@ -89,6 +89,29 @@ function signed(value: number) {
   return value >= 0 ? `+ ${value}` : `− ${Math.abs(value)}`
 }
 
+function abilityModifier(score: number) {
+  return Math.floor((Number(score) - 10) / 2)
+}
+
+function abilityLabel(score: number) {
+  const modifier = abilityModifier(score)
+  return modifier >= 0 ? `+${modifier}` : String(modifier)
+}
+
+function rollMeta(roll: Record<string, any>) {
+  if (roll.success === null || roll.success === undefined) return String(roll.check_kind ?? 'ROLL').toUpperCase()
+  const kept = Number(roll.kept?.[0])
+  const outcome = roll.check_kind === 'attack' && kept === 20
+    ? 'CRITICAL HIT'
+    : roll.check_kind === 'attack' && kept === 1
+      ? 'CRITICAL MISS'
+      : roll.success ? 'SUCCESS' : 'FAILED'
+  const target = roll.difficulty === null || roll.difficulty === undefined
+    ? ''
+    : ` · ${roll.check_kind === 'attack' ? 'AC' : 'DC'} ${roll.difficulty}`
+  return `${outcome}${target}`
+}
+
 function initials(name: string) {
   return name.split(/\s+/).map(part => part[0]).join('').slice(0, 2).toUpperCase()
 }
@@ -274,7 +297,7 @@ onBeforeUnmount(() => {
           <textarea v-model="characterForm.concept" required maxlength="600" placeholder="Concept, role, personality" />
           <button type="button" class="ai-draft" :disabled="suggestingCharacter || mutating" @click="suggestCharacter">{{ suggestingCharacter ? 'COAUTHOR IS DRAFTING…' : '✦ DRAFT WITH AI' }}</button>
           <div class="ability-editor"><label v-for="key in (['str','dex','con','int','wis','cha'] as AbilityKey[])" :key="key"><span>{{ key }}</span><input v-model.number="characterForm.abilities[key]" type="number" min="1" max="30"></label></div>
-          <div class="stat-editor"><label>HP <input v-model.number="characterForm.hp" type="number" min="1" :max="characterForm.maxHp"></label><label>MAX <input v-model.number="characterForm.maxHp" type="number" min="1"></label><label>DEF <input v-model.number="characterForm.defense" type="number" min="1" max="40"></label></div>
+          <div class="stat-editor"><label>HP <input v-model.number="characterForm.hp" type="number" min="1" :max="characterForm.maxHp"></label><label>MAX <input v-model.number="characterForm.maxHp" type="number" min="1"></label><label>AC <input v-model.number="characterForm.defense" type="number" min="1" max="40"></label></div>
           <textarea v-model="inventoryText" maxlength="800" placeholder="Starting items, one per line" />
           <details class="persona-editor"><summary>VOICE & PERSONALITY</summary><input v-model="characterForm.persona.voice" maxlength="240" placeholder="Voice"><input v-model="characterForm.persona.motivation" maxlength="300" placeholder="Motivation"><input v-model="characterForm.persona.flaw" maxlength="300" placeholder="Flaw"><input v-model="characterForm.persona.bond" maxlength="300" placeholder="Bond"></details>
           <button class="acid-button" :disabled="mutating">{{ mutating ? 'CREATING…' : 'ADD TO PARTY' }}</button>
@@ -285,8 +308,8 @@ onBeforeUnmount(() => {
         </article>
         <section v-if="myCharacter" class="sheet">
           <small>YOUR CHARACTER</small><h2>{{ myCharacter.name }}</h2><p>{{ myCharacter.concept }}</p>
-          <div class="vitals"><span><b>{{ myCharacter.hp }}</b>/{{ myCharacter.max_hp }} HP</span><span><b>{{ myCharacter.defense }}</b> DEF</span></div>
-          <div class="abilities"><span v-for="(score,key) in myCharacter.abilities" :key="key"><small>{{ key }}</small><b>{{ score }}</b></span></div>
+          <div class="vitals"><span><b>{{ myCharacter.hp }}</b>/{{ myCharacter.max_hp }} HP</span><span><b>{{ myCharacter.defense }}</b> AC</span></div>
+          <div class="abilities"><span v-for="(score,key) in myCharacter.abilities" :key="key"><small>{{ key }} {{ abilityLabel(Number(score)) }}</small><b>{{ score }}</b></span></div>
         </section>
       </aside>
 
@@ -320,7 +343,7 @@ onBeforeUnmount(() => {
         <section class="ai-order"><small>AI TURN ORDER</small><p v-if="!payload.characters.some(character=>character.controller!=='human')">No AI heroes in this party.</p><div v-for="(character,index) in payload.characters.filter(character=>character.controller!=='human')" :key="character.id"><b>{{ String(index+1).padStart(2,'0') }}</b><span>{{ character.name }}<small>{{ character.controller === 'delegated' ? 'Temporary stand-in' : 'Acts after all humans' }}</small></span></div></section>
         <button v-if="isOwner && currentRound?.status==='open'" class="force-button" :disabled="mutating" @click="forceRound">CONTINUE WITHOUT WAITING <span>↗</span></button>
         <button v-if="isOwner && currentRound?.status==='failed'" class="force-button" :disabled="mutating" @click="retryFailedRound">RETRY FAILED ROUND <span>↗</span></button>
-        <div class="mechanics-note"><i /> Dice, HP and mechanical state are resolved by the server and recorded in the campaign log.</div>
+        <div class="mechanics-note"><i /> D20 tests, AC, HP and mechanical state are resolved by the server and recorded in the campaign log.</div>
       </aside>
     </div>
   </AppShell>

apps/web/pages/campaign/demo.vue

@@ -5,6 +5,11 @@ const forceOpen = ref(false)
 const errorMessage = ref('')
 const submittedActionIndex = ref<number | null>(null)
 
+function abilityLabel(score: number) {
+  const modifier = Math.floor((Number(score) - 10) / 2)
+  return modifier >= 0 ? `+${modifier}` : String(modifier)
+}
+
 async function submitAction() {
   if (!currentAction.value.trim() || submitting.value || ready.value) return
   submitting.value = true
@@ -67,8 +72,8 @@ async function continueRound() {
         </article>
         <div class="character-sheet">
           <small>ACTIVE CHARACTER</small><h2>{{ characters[0]?.name }}</h2><p>{{ characters[0]?.concept }}</p>
-          <div class="vitals"><span><b>{{ characters[0]?.hp }}</b>/{{ characters[0]?.maxHp }} HP</span><span><b>{{ characters[0]?.defense }}</b> DEF</span></div>
-          <div class="abilities"><span v-for="(score,key) in characters[0]?.abilities" :key="key"><small>{{ key }}</small><b>{{ score }}</b></span></div>
+          <div class="vitals"><span><b>{{ characters[0]?.hp }}</b>/{{ characters[0]?.maxHp }} HP</span><span><b>{{ characters[0]?.defense }}</b> AC</span></div>
+          <div class="abilities"><span v-for="(score,key) in characters[0]?.abilities" :key="key"><small>{{ key }} {{ abilityLabel(score) }}</small><b>{{ score }}</b></span></div>
           <details><summary>INVENTORY</summary><ul><li v-for="item in characters[0]?.inventory" :key="item">{{ item }}</li></ul></details>
         </div>
       </aside>

apps/web/server/api/v1/campaigns/[id]/characters/suggest.post.ts

@@ -34,7 +34,7 @@ export default defineEventHandler(async (event) => {
     if (!world) throw createError({ statusCode: 404, statusMessage: 'Campaign world not found.' })
 
     const completion = buildJsonCompletion(useRuntimeConfig(), {
-      system: `You create an original, editable Dungeons & Ground character draft for a private 13+ TTRPG campaign. Adapt archetype, equipment and voice to the supplied genre, but always use STR, DEX, CON, INT, WIS and CHA. Keep an alpha hero grounded: ability scores 7–16, max HP 8–20, Defense 10–16, proficiency 2. Give 2–5 useful starting items and a distinctive persona. Never use protected franchise characters. Return only the requested JSON.`,
+      system: `You create an original, editable Dungeons & Ground character draft for a private 13+ TTRPG campaign. Adapt archetype, equipment and voice to the supplied genre, but always use STR, DEX, CON, INT, WIS and CHA. Keep an alpha hero grounded: ability scores 7–16, max HP 8–20, Armor Class (AC) 10–16, proficiency 2. Give 2–5 useful starting items and a distinctive persona. Never use protected franchise characters. Return only the requested JSON.`,
       messages: [{
         role: 'user',
         content: JSON.stringify({

apps/worker/src/ai.ts

@@ -100,7 +100,7 @@ export async function generateWorld(messages: Array<{ role: 'user' | 'assistant'
 
 export async function planRound(input: RoundContext): Promise<RoundPlan> {
   const plan = await structuredRequest('round_plan', RoundPlanSchema.toJSONSchema(), [
-    { role: 'system', content: 'You plan one asynchronous TTRPG round. Human intents are authoritative and happen first. Then provide at most one action for each supplied aiCharacter, in the supplied order; never create AI actions for human-controlled characters. You may request checks and propose story events. Never invent dice results and never directly mutate mechanical state. The server owns rules, HP, inventory, statuses and randomness.' },
+    { role: 'system', content: 'You plan one asynchronous SRD 5.2.1 TTRPG round. Human intents are authoritative and happen first. Then provide at most one action for each supplied aiCharacter, in the supplied order; never create AI actions for human-controlled characters. Request a d20 test only when the outcome is uncertain: ability, skill, savingThrow, attack, or initiative. Skill checks require a skill and DC; saving throws require an ability and DC; attacks require an active targetId and use that target\'s server-owned Armor Class. Set proficient true for a skill or saving throw only when the character concept supports it; ordinary equipped-weapon attacks default to proficient. Request separate damage or healing dice only after an applicable action. Never invent dice results and never directly mutate mechanical state. The server owns rules, AC, HP, inventory, statuses and randomness.' },
     { role: 'user', content: JSON.stringify(input) },
   ], value => RoundPlanSchema.parse(value))
   assert13Plus(JSON.stringify(plan.aiActions), JSON.stringify(plan.proposedEvents))

apps/worker/src/index.ts

@@ -1,7 +1,7 @@
 import './env'
 import { Worker } from 'bullmq'
 import IORedis from 'ioredis'
-import { applyMechanicalEvents, bindMechanicalEventsToRolls, resolveCheck } from '@dng/game-engine'
+import { applyMechanicalEvents, bindMechanicalEventsToRolls, resolveChecks } from '@dng/game-engine'
 import { CharacterSchema, PlayerIntentSchema, makeId } from '@dng/shared'
 import { generateWorld, narrateRound, planRound, summarizeStory } from './ai'
 import { buildActionSequence, buildRoundContext, sanitizeRoundMemory, shouldUpdateStorySummary, validateAndOrderRoundPlan } from './orchestration'
@@ -153,11 +153,7 @@ if (!supabaseUrl || !serviceKey) {
       })),
     })
     const plan = validateAndOrderRoundPlan(await planRound(context), context)
-    const rolls = plan.checks.map(check => {
-      const actor = characters.find(character => character.id === check.actorId)
-      if (!actor) throw new Error(`Unknown check actor ${check.actorId}`)
-      return resolveCheck(check, actor)
-    })
+    const rolls = resolveChecks(plan.checks, characters)
     const permittedEvents = bindMechanicalEventsToRolls(plan.proposedEvents, rolls)
     const resolution = await narrateRound({ context, actionSequence: buildActionSequence(context, plan), rolls, permittedEvents })
     const safeEvents = resolution.events.filter(event => permittedEvents.some(permitted => JSON.stringify(permitted) === JSON.stringify(event)))

apps/worker/src/orchestration.test.ts

@@ -41,6 +41,21 @@ describe('round orchestration', () => {
     }, context)).toThrow('Unknown check actor outsider')
   })
 
+  it('requires complete SRD check inputs before rolling', () => {
+    const context = buildRoundContext({
+      scene: 'Scene', recentRounds: [], intents: [],
+      characters: [character('hero', 'human'), character('foe', 'ai')], memories: [],
+    })
+    const basePlan = { aiActions: [], proposedEvents: [], relevantMemoryQueries: [] }
+
+    expect(() => validateAndOrderRoundPlan({
+      ...basePlan, checks: [{ actorId: 'hero', kind: 'skill', mode: 'normal', reason: 'Search' }],
+    }, context)).toThrow('Skill checks require a skill')
+    expect(() => validateAndOrderRoundPlan({
+      ...basePlan, checks: [{ actorId: 'hero', kind: 'attack', mode: 'normal', reason: 'Strike' }],
+    }, context)).toThrow('Attack rolls require a target')
+  })
+
   it('schedules durable story summaries every third completed round', () => {
     expect([1, 2, 3, 4, 5, 6].filter(shouldUpdateStorySummary)).toEqual([3, 6])
   })

apps/worker/src/orchestration.ts

@@ -64,6 +64,13 @@ export function validateAndOrderRoundPlan(planInput: unknown, context: RoundCont
   for (const check of plan.checks) {
     if (!characterIds.has(check.actorId)) throw new Error(`Unknown check actor ${check.actorId}`)
     if (check.targetId && !characterIds.has(check.targetId)) throw new Error(`Unknown check target ${check.targetId}`)
+    if (check.kind === 'skill' && !check.skill) throw new Error('Skill checks require a skill')
+    if (['ability', 'savingThrow'].includes(check.kind) && !check.ability) throw new Error(`${check.kind} checks require an ability`)
+    if (['ability', 'skill', 'savingThrow'].includes(check.kind) && check.difficulty === undefined) {
+      throw new Error(`${check.kind} checks require a Difficulty Class`)
+    }
+    if (check.kind === 'attack' && !check.targetId) throw new Error('Attack rolls require a target')
+    if (['damage', 'healing'].includes(check.kind) && !check.targetId) throw new Error(`${check.kind} rolls require a target`)
   }
   for (const event of plan.proposedEvents) {
     if (event.actorId && !characterIds.has(event.actorId)) throw new Error(`Unknown event actor ${event.actorId}`)