@ai-rpg-engine/starter-template 2.4.0 → 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCP Tool Shop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,47 @@
-# Starter Template
+# My Game
 
-Copy this directory to `packages/starter-yourname/` to create a new game.
+An [ai-rpg-engine](https://mcp-tool-shop-org.github.io/ai-rpg-engine/) content
+pack, scaffolded from the starter template. The project is **standalone**: it
+carries its own `tsconfig.json` and declares every dependency it needs
+(including `typescript` and `vitest` as devDependencies), so it builds and
+tests anywhere — no engine monorepo required.
+
+## Getting started
+
+If you are reading this inside `templates/starter`, scaffold your own copy
+first (it names everything for you):
 
 ```bash
-cp -r templates/starter packages/starter-mygame
+npx --package=@ai-rpg-engine/cli ai-rpg-engine create-starter my-game --out=./my-game
 ```
 
-Then edit:
-- `package.json` — name and description
-- `src/ruleset.ts` — your stats, resources, verbs
-- `src/content.ts` — entities and zones
-- `src/setup.ts` — wire your modules alongside `buildCombatStack`
+Then, from the project directory:
+
+```bash
+npm install        # pulls @ai-rpg-engine/* plus typescript + vitest
+npx tsc --noEmit   # typecheck
+npx vitest run     # run the pack's tests
+```
+
+## Make it yours
+
+| File | What to edit |
+|------|--------------|
+| `package.json` | name and description |
+| `src/ruleset.ts` | your stats, resources, verbs |
+| `src/content.ts` | entities and zones — keep each enemy's `ai.profileId` paired with a profile in setup |
+| `src/setup.ts` | wire your modules alongside `buildCombatStack`; the intent profiles list lives here |
+| `src/starter.test.ts` | grows with your content — register dialogues/abilities in the integrity lists |
+
+Two wiring rules worth knowing from day one:
+
+- **Enemies act only if their `ai.profileId` resolves.** Every profile id
+  declared in `src/content.ts` must appear in the `cognition.profiles` list in
+  `src/setup.ts` (built-ins: `aggressive`, `cautious`). An empty profiles list
+  means enemies never select an intent.
+- **`buildCombatStack` owns the combat stack** (cognition, tactics, resources,
+  intent, recovery, narration). Your custom modules go in the marked
+  starter-owned section of `src/setup.ts`.
 
-See [Chapter 58 — Create Your Own Starter](../../site/src/content/docs/handbook/58-create-your-own-starter.md) for the full walkthrough.
+See [Chapter 58 — Create Your Own Starter](https://mcp-tool-shop-org.github.io/ai-rpg-engine/handbook/58-create-your-own-starter/)
+in the handbook for the full walkthrough.

package/package.json

@@ -1,21 +1,27 @@
 {
   "name": "@ai-rpg-engine/starter-template",
-  "version": "2.4.0",
-  "description": "Starter template for ai-rpg-engine — copy, rename, and build your own game",
+  "version": "2.6.0",
+  "description": "Starter template for ai-rpg-engine \u00e2\u20ac\u201d scaffold a standalone game project from it",
   "type": "module",
   "files": [
     "src",
     "README.md",
+    "LICENSE",
     "tsconfig.json"
   ],
   "scripts": {
     "build": "tsc",
+    "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
   "dependencies": {
-    "@ai-rpg-engine/core": "*",
-    "@ai-rpg-engine/content-schema": "*",
-    "@ai-rpg-engine/modules": "*"
+    "@ai-rpg-engine/core": "^2.6.0",
+    "@ai-rpg-engine/content-schema": "^2.6.0",
+    "@ai-rpg-engine/modules": "^2.6.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   },
   "license": "MIT",
   "author": "mcp-tool-shop",

package/src/content.ts

@@ -15,7 +15,13 @@ export const manifest: GameManifest = {
 };
 
 // ═══════════════════════════════════════════════════════════════════
-// PACK METADATA (used by the CLI pack selector)
+// PACK METADATA
+// This is a minimal subset to keep the template dependency-light. To list
+// your pack in the CLI pack selector, export the full PackMetadata shape
+// from @ai-rpg-engine/pack-registry (adds: tagline, genres, difficulty,
+// tones, tags, engineVersion, narratorTone) plus a BuildCatalog from
+// @ai-rpg-engine/character-creation — see any packages/starter-* content.ts
+// for a complete example.
 // ═══════════════════════════════════════════════════════════════════
 
 export const packMeta = {
@@ -56,6 +62,11 @@ export const enemy: EntityState = {
     resources: { hp: 12 },
     statuses: [],
     zoneId: 'danger-zone',
+    // ai.profileId picks this enemy's combat brain. It must match a profile
+    // provided in setup.ts (`cognition: { profiles: [...] }`) — without that
+    // pairing the enemy never selects an intent and just stands there.
+    // Built-ins: 'aggressive' (attack on sight) and 'cautious' (observe first).
+    ai: { profileId: 'aggressive', goals: ['guard-zone'], fears: [], alertLevel: 0, knowledge: {} },
 };
 
 // ═══════════════════════════════════════════════════════════════════

package/src/index.ts

@@ -1,5 +1,5 @@
 // @ai-rpg-engine/starter-YOURNAME
 
-export { createGame } from './setup.js';
+export { createGame, myIntentProfiles } from './setup.js';
 export { manifest, packMeta } from './content.js';
 export { myRuleset } from './ruleset.js';

package/src/setup.ts

@@ -14,7 +14,9 @@ import {
     traversalCore,
     statusCore,
     buildCombatStack,
+    aggressiveProfile,
 } from '@ai-rpg-engine/modules';
+import type { IntentProfile } from '@ai-rpg-engine/modules';
 import { manifest, player, enemy, zones } from './content.js';
 import { myRuleset } from './ruleset.js';
 
@@ -24,13 +26,17 @@ import { myRuleset } from './ruleset.js';
 // your starter feel different from other starters.
 // ═══════════════════════════════════════════════════════════════════
 
-// Example: a custom module that ticks your "tension" resource each combat round
+// Example: a custom module that raises your "tension" resource whenever
+// damage lands in combat. It listens on 'combat.damage.applied' — a real
+// event emitted by combat-core every time an attack connects (other engine
+// events you can hook: 'combat.contact.hit', 'combat.contact.miss',
+// 'combat.entity.defeated', 'status.applied', 'world.zone.entered').
 function createTensionPressure(): EngineModule {
     return {
         id: 'tension-pressure',
         version: '1.0.0',
         register(ctx) {
-            ctx.events.on('combat.round.end', (event: ResolvedEvent, world: WorldState) => {
+            ctx.events.on('combat.damage.applied', (event: ResolvedEvent, world: WorldState) => {
                 const p = world.entities['player'];
                 if (p && p.resources.tension !== undefined) {
                     p.resources.tension = Math.min(100, (p.resources.tension ?? 0) + 5);
@@ -40,6 +46,19 @@ function createTensionPressure(): EngineModule {
     };
 }
 
+// ═══════════════════════════════════════════════════════════════════
+// INTENT PROFILES — required for enemies to act
+// Every entity in content.ts that declares an `ai.profileId` must find a
+// matching profile in this list: cognition builds its profile map from
+// `cognition.profiles`, and with an empty map no enemy ever selects an
+// intent — they stand still forever. Built-ins from @ai-rpg-engine/modules:
+// aggressiveProfile ('aggressive': attack visible hostiles, flee at low
+// morale) and cautiousProfile ('cautious': observe first, strike when
+// confident). Add your own IntentProfile objects here for custom brains.
+// ═══════════════════════════════════════════════════════════════════
+
+export const myIntentProfiles: IntentProfile[] = [aggressiveProfile];
+
 // ═══════════════════════════════════════════════════════════════════
 // GAME FACTORY
 // ═══════════════════════════════════════════════════════════════════
@@ -49,18 +68,34 @@ export function createGame(seed?: number): Engine {
     const combat = buildCombatStack({
         statMapping: { attack: 'power', precision: 'speed', resolve: 'grit' },
         playerId: 'player',
-        // resourceProfile — uncomment and customize for your game's resource pressure:
+        // resourceProfile — uncomment and customize for your game's resource
+        // pressure. A CombatResourceProfile needs packId + the four arrays
+        // (gains / spends / drains / aiModifiers — empty arrays are fine):
         // resourceProfile: {
+        //   packId: 'my-game',
+        //   gains: [
+        //     // +2 tension every time an attack you make lands
+        //     { trigger: 'attack-hit', resourceId: 'tension', amount: 2 },
+        //   ],
         //   spends: [
-        //     { verbId: 'attack', costStat: 'stamina', amount: 2 },
+        //     // spend 2 stamina on each attack for +1 damage
+        //     { action: 'attack', resourceId: 'stamina', amount: 2, effects: { damageBonus: 1 } },
         //   ],
+        //   drains: [],
+        //   aiModifiers: [],
         // },
-        // biasTags — entity tags that cognition uses for faction bias:
-        // biasTags: ['enemy'],
-        // engagement — customize if your game uses ranged/melee distance:
-        // engagement: { defaultRange: 'melee' },
+        // biasTags — built-in pack bias tags that shape combat AI intent.
+        // Must come from PACK_BIAS_TAGS (exported by @ai-rpg-engine/modules,
+        // e.g. 'undead', 'beast', 'feral'); unknown tags warn and are dropped:
+        // biasTags: ['undead', 'beast'],
+        // engagement — backline/protector behavior for ranged parties
+        // (fields: backlineTags, protectorTags, chokepointTag, ambushTag):
+        // engagement: { backlineTags: ['ranged', 'caster'], protectorTags: ['bodyguard'] },
         // recovery — safe zone recovery:
         recovery: { safeZoneTags: ['safe'] },
+        // cognition — wires the intent profiles above into the enemy AI.
+        // Every ai.profileId declared in content.ts must resolve here.
+        cognition: { profiles: myIntentProfiles },
     });
 
     const engine = new Engine({
@@ -84,8 +119,8 @@ export function createGame(seed?: number): Engine {
     }
 
     // Register entities
-    engine.store.addEntity({ ...player });
-    engine.store.addEntity({ ...enemy });
+    engine.store.addEntity(structuredClone(player));
+    engine.store.addEntity(structuredClone(enemy));
 
     // Set player context
     engine.store.state.playerId = 'player';

package/src/starter.test.ts

@@ -1,7 +1,12 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { describe, it, expect } from 'vitest';
-import { validateRulesetDefinition } from '@ai-rpg-engine/content-schema';
+import { validateRulesetDefinition, validateGameContent, validateAbilityPack } from '@ai-rpg-engine/content-schema';
+import type { ContentPack, AbilityDefinition, DialogueDefinition } from '@ai-rpg-engine/content-schema';
+import { selectIntent } from '@ai-rpg-engine/modules';
+import type { CognitionState } from '@ai-rpg-engine/modules';
 import { myRuleset } from './ruleset.js';
-import { createGame } from './setup.js';
+import { createGame, myIntentProfiles } from './setup.js';
 
 describe('starter template', () => {
     it('ruleset validates against schema', () => {
@@ -27,9 +32,211 @@ describe('starter template', () => {
         expect(engine).toBeDefined();
     });
 
-    it('tension pressure module is wired', () => {
+    it('tension rises when combat damage lands (tension-pressure fires)', () => {
         const engine = createGame(1);
-        const p = engine.world.entities['player'];
-        expect(p?.resources.tension).toBe(0);
+        expect(engine.world.entities['player']?.resources.tension).toBe(0);
+
+        // Walk into the danger zone and fight. combat-core emits
+        // 'combat.damage.applied' whenever a hit lands — that is the event
+        // the tension-pressure module listens on.
+        engine.submitAction('move', { targetIds: ['danger-zone'] });
+        for (let i = 0; i < 8; i++) {
+            engine.submitAction('attack', { targetIds: ['grunt'] });
+            if ((engine.world.entities['player']?.resources.tension ?? 0) > 0) break;
+        }
+
+        // Meta-test property: deleting the tension-pressure listener in
+        // setup.ts turns this RED — nothing else writes the tension resource.
+        expect(engine.world.entities['player']?.resources.tension).toBeGreaterThan(0);
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════
+// CROSS-REFERENCE INTEGRITY
+// The schema test above checks each piece in isolation. These tests check
+// the connections BETWEEN pieces: dangling zone neighbors, duplicate ids,
+// dialogue speakers that name an entity's display name instead of its id,
+// abilities that reference undeclared stats/resources. They validate the
+// REAL composed game (createGame()'s world state), so they automatically
+// cover content you add — as long as you keep the two lists below in sync.
+//
+// Why this matters: dialogue-core finds a dialogue by matching its
+// speakers[] against the target ENTITY ID. Writing the display name
+// ('Grunt') instead of the id ('grunt') doesn't error — "talk to NPC"
+// just silently reports "has nothing to say". validateGameContent catches
+// exactly that class of bug at test time.
+// ═══════════════════════════════════════════════════════════════════
+describe('starter template — cross-reference integrity', () => {
+    // Register your DialogueDefinitions here as you write them. Remember:
+    // speakers: ['grunt'] (entity id), never speakers: ['Grunt'] (name).
+    const myDialogues: DialogueDefinition[] = [];
+    // Register your AbilityDefinitions here as you write them.
+    const myAbilities: AbilityDefinition[] = [];
+
+    function builtContentPack(): ContentPack {
+        const engine = createGame(1);
+        return {
+            zones: Object.values(engine.store.state.zones) as unknown as ContentPack['zones'],
+            entities: Object.values(engine.store.state.entities) as unknown as ContentPack['entities'],
+            dialogues: myDialogues,
+            abilities: myAbilities,
+        };
+    }
+
+    it('zones, entities, dialogues, and abilities have no dangling references or duplicate ids', () => {
+        const result = validateGameContent(builtContentPack());
+        expect(result.errors).toEqual([]);
+        expect(result.ok).toBe(true);
+    });
+
+    it('has no one-way zone passages (neighbor symmetry advisory)', () => {
+        // A zone listing a neighbor that doesn't list it back is legal but
+        // almost always a mistake — the player can walk in and never back out.
+        const result = validateGameContent(builtContentPack());
+        expect(result.advisories).toEqual([]);
+    });
+
+    it('abilities reference only stats/resources declared in the ruleset', () => {
+        const result = validateAbilityPack(myAbilities, myRuleset);
+        expect(result.errors).toEqual([]);
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════
+// INTENT PROFILE WIRING
+// Enemies act only if their ai.profileId resolves to a profile provided
+// in setup.ts's `cognition.profiles`. An empty profiles list is the #1
+// reason a pack's enemies stand still forever. These tests keep every
+// declared profileId resolvable as you add content.
+// ═══════════════════════════════════════════════════════════════════
+describe('starter template — intent profile wiring', () => {
+    it('provides a non-empty intent profile list to cognition', () => {
+        expect(myIntentProfiles.length).toBeGreaterThan(0);
+        for (const profile of myIntentProfiles) {
+            expect(typeof profile.id).toBe('string');
+            expect(typeof profile.evaluate).toBe('function');
+        }
+    });
+
+    it('every hostile entity declares a profileId that resolves to a provided profile', () => {
+        const engine = createGame(1);
+        const hostiles = Object.values(engine.world.entities).filter(
+            (e) => e.type === 'enemy' || e.tags.includes('enemy'),
+        );
+        expect(hostiles.length).toBeGreaterThan(0);
+
+        const provided = new Set(myIntentProfiles.map((p) => p.id));
+        for (const hostile of hostiles) {
+            expect(hostile.ai?.profileId, `${hostile.id} must declare ai.profileId`).toBeTruthy();
+            expect(
+                provided.has(hostile.ai!.profileId),
+                `${hostile.id} declares "${hostile.ai!.profileId}" — not in cognition.profiles`,
+            ).toBe(true);
+        }
+    });
+
+    it('resolved profiles produce intents — hostiles can act on an intruder', () => {
+        const engine = createGame(1);
+        const world = engine.world;
+        const player = world.entities[world.playerId || 'player'];
+        expect(player).toBeDefined();
+
+        for (const hostile of Object.values(world.entities)) {
+            if (!(hostile.type === 'enemy' || hostile.tags.includes('enemy'))) continue;
+            const profile = myIntentProfiles.find((p) => p.id === hostile.ai?.profileId);
+            expect(profile, `${hostile.id} must resolve an intent profile`).toBeDefined();
+
+            // Stand the player in the hostile's zone as a believed-hostile intruder.
+            player!.zoneId = hostile.zoneId;
+            const cognition: CognitionState = {
+                beliefs: [{
+                    subject: player!.id,
+                    key: 'hostile',
+                    value: true,
+                    confidence: 1,
+                    source: 'observed',
+                    tick: world.meta.tick,
+                }],
+                memories: [],
+                currentIntent: null,
+                morale: 80,
+                suspicion: 60,
+            };
+            const intent = selectIntent(hostile, cognition, world, profile!);
+            expect(intent, `${hostile.id} (${profile!.id}) selected no intent`).not.toBeNull();
+        }
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════
+// STANDALONE SCAFFOLD
+// The scaffold must work OUTSIDE the engine monorepo: its tsconfig may
+// not reach for ../../tsconfig.json or ../../packages/* (that is TS5083
+// for anyone who scaffolds a project of their own), and its package.json
+// must carry real dependency versions plus the typescript/vitest
+// devDependencies the printed "next steps" rely on.
+// ═══════════════════════════════════════════════════════════════════
+describe('starter template — standalone scaffold', () => {
+    const read = (rel: string): string =>
+        readFileSync(fileURLToPath(new URL(rel, import.meta.url)), 'utf-8');
+
+    it('tsconfig is self-contained (no extends, no references, no ../.. paths)', () => {
+        const raw = read('../tsconfig.json');
+        expect(raw).not.toContain('../..');
+        const tsconfig = JSON.parse(raw) as Record<string, unknown>;
+        expect(tsconfig.extends).toBeUndefined();
+        expect(tsconfig.references).toBeUndefined();
+        expect(tsconfig.compilerOptions).toBeDefined();
+        // The inlined options every scaffold needs to compile on its own:
+        const opts = tsconfig.compilerOptions as Record<string, unknown>;
+        expect(opts.module).toBeDefined();
+        expect(opts.moduleResolution).toBeDefined();
+        expect(opts.strict).toBe(true);
+    });
+
+    it('package.json declares real dependency versions and its own toolchain', () => {
+        const pkg = JSON.parse(read('../package.json')) as {
+            dependencies?: Record<string, string>;
+            devDependencies?: Record<string, string>;
+        };
+        const deps = pkg.dependencies ?? {};
+        expect(Object.keys(deps).length).toBeGreaterThan(0);
+        for (const [name, range] of Object.entries(deps)) {
+            expect(range, `${name} must pin a real semver range, not "*"`).not.toBe('*');
+        }
+        const devDeps = pkg.devDependencies ?? {};
+        expect(devDeps.typescript, 'typescript devDependency required for `npx tsc`').toBeTruthy();
+        expect(devDeps.vitest, 'vitest devDependency required for `npx vitest`').toBeTruthy();
+    });
+
+    it('README does not send users into the monorepo', () => {
+        const readme = read('../README.md');
+        expect(readme).not.toContain('../../');
+        expect(readme.toLowerCase()).not.toContain('copy this directory to `packages/');
+        expect(readme).not.toMatch(/cp -r templates\/starter/);
+    });
+});
+
+// ═══════════════════════════════════════════════════════════════════
+// CROSS-INSTANCE STATE ISOLATION
+// setup.ts inserts entities from module-level constants. A shallow spread
+// (`addEntity({ ...enemy })`) shares the nested resources/stats/statuses
+// objects across every engine built in one process, so combat damage (or
+// the NPC turn driver killing the grunt) in engine A would permanently
+// mutate the constant and a LATER createGame() would boot with a dead
+// grunt. structuredClone at insertion is the fix. Same class as F-71ec5dcd.
+// ═══════════════════════════════════════════════════════════════════
+describe('starter template — cross-instance state isolation', () => {
+    it('killing the enemy in engine A does not carry into a fresh engine B', () => {
+        const a = createGame(1);
+        const fullHp = a.world.entities['grunt'].resources.hp;
+        expect(fullHp).toBeGreaterThan(0);
+
+        a.world.entities['grunt'].resources.hp = 0;
+
+        const b = createGame(1);
+        expect(b.world.entities['grunt'].resources.hp).toBe(fullHp);
+        expect(b.world.entities['grunt'].resources)
+            .not.toBe(a.world.entities['grunt'].resources);
     });
 });

package/tsconfig.json

@@ -1,24 +1,23 @@
 {
-    "extends": "../../tsconfig.json",
     "compilerOptions": {
+        "target": "ES2022",
+        "module": "Node16",
+        "moduleResolution": "Node16",
+        "declaration": true,
+        "sourceMap": true,
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "forceConsistentCasingInFileNames": true,
+        "resolveJsonModule": true,
+        "isolatedModules": true,
         "outDir": "dist",
         "rootDir": "src"
     },
     "include": [
         "src"
     ],
-    "references": [
-        {
-            "path": "../../packages/core"
-        },
-        {
-            "path": "../../packages/content-schema"
-        },
-        {
-            "path": "../../packages/modules"
-        }
-    ],
     "exclude": [
         "**/*.test.ts"
     ]
-}
+}