1

src/types/customWorld.ts

@@ -318,6 +318,43 @@ export interface CustomWorldSceneConnection {
   summary: string;
 }
 
+export type SceneActStage =
+  | 'opening'
+  | 'expansion'
+  | 'turning_point'
+  | 'climax'
+  | 'aftermath';
+
+export type SceneActAdvanceRule =
+  | 'after_primary_contact'
+  | 'after_active_step_complete'
+  | 'after_chapter_resolution';
+
+export interface SceneActBlueprint {
+  id: string;
+  sceneId: string;
+  title: string;
+  summary: string;
+  stageCoverage: SceneActStage[];
+  backgroundImageSrc?: string | null;
+  encounterNpcIds: string[];
+  primaryNpcId: string;
+  linkedThreadIds: string[];
+  advanceRule: SceneActAdvanceRule;
+  actGoal: string;
+  transitionHook: string;
+}
+
+export interface SceneChapterBlueprint {
+  id: string;
+  sceneId: string;
+  title: string;
+  summary: string;
+  linkedThreadIds: string[];
+  linkedLandmarkIds: string[];
+  acts: SceneActBlueprint[];
+}
+
 export interface CustomWorldCampScene {
   name: string;
   description: string;
@@ -360,6 +397,7 @@ export interface CustomWorldProfile {
   storyGraph?: WorldStoryGraph | null;
   knowledgeFacts?: KnowledgeFact[] | null;
   threadContracts?: ThreadContract[] | null;
+  sceneChapterBlueprints?: SceneChapterBlueprint[] | null;
   anchorContent?: EightAnchorContent | null;
   creatorIntent?: CustomWorldCreatorIntent | null;
   anchorPack?: CustomWorldAnchorPack | null;

src/types/game.ts

@@ -1,5 +1,5 @@
-import type {TimedBuildBuff} from './build';
-import type {Character} from './characters';
+import type { TimedBuildBuff } from './build';
+import type { Character } from './characters';
 import {
   AnimationState,
   type CombatActionMode,
@@ -7,8 +7,8 @@ import {
   type NpcBattleOutcome,
   WorldType,
 } from './core';
-import type {CustomWorldProfile} from './customWorld';
-import type {EquipmentLoadout, InventoryItem} from './items';
+import type { CustomWorldProfile } from './customWorld';
+import type { EquipmentLoadout, InventoryItem } from './items';
 import type {
   CombatVisualEffect,
   CompanionState,
@@ -18,8 +18,12 @@ import type {
   SceneHostileNpc,
   ScenePresetInfo,
 } from './scene';
-import type {CharacterChatRecord, QuestLogEntry, StoryMoment} from './story';
-import type {CampaignState, ChapterState, StoryEngineMemoryState} from './storyEngine';
+import type { CharacterChatRecord, QuestLogEntry, StoryMoment } from './story';
+import type {
+  CampaignState,
+  ChapterState,
+  StoryEngineMemoryState,
+} from './storyEngine';
 
 export interface GameRuntimeStats {
   playTimeMs: number;
@@ -30,6 +34,17 @@ export interface GameRuntimeStats {
   scenesTraveled: number;
 }
 
+export type PlayerProgressionGrantSource = 'quest' | 'hostile_npc';
+
+export interface PlayerProgressionState {
+  level: number;
+  currentLevelXp: number;
+  totalXp: number;
+  xpToNextLevel: number;
+  pendingLevelUps?: number;
+  lastGrantedSource?: PlayerProgressionGrantSource | null;
+}
+
 export interface GameState {
   worldType: WorldType | null;
   customWorldProfile: CustomWorldProfile | null;
@@ -37,6 +52,7 @@ export interface GameState {
   runtimeSessionId?: string | null;
   runtimeActionVersion?: number;
   runtimeStats: GameRuntimeStats;
+  playerProgression?: PlayerProgressionState | null;
   currentScene: string;
   storyHistory: StoryMoment[];
   storyEngineMemory?: StoryEngineMemoryState;

src/types/scene.ts

@@ -107,6 +107,26 @@ export interface Encounter {
   imageSrc?: string;
   visual?: CustomWorldNpcVisual;
   narrativeProfile?: ActorNarrativeProfile | null;
+  levelProfile?: EntityLevelProfile;
+  experienceReward?: number;
+}
+
+export type ProgressionRole =
+  | 'guide'
+  | 'ambient'
+  | 'support'
+  | 'hostile_standard'
+  | 'hostile_elite'
+  | 'hostile_boss'
+  | 'rival';
+
+export interface EntityLevelProfile {
+  level: number;
+  referenceStrength: number;
+  chapterId?: string | null;
+  chapterIndex?: number | null;
+  progressionRole: ProgressionRole;
+  source: 'chapter_auto' | 'preset_override' | 'manual';
 }
 
 export interface SceneHostileNpc {
@@ -129,6 +149,8 @@ export interface SceneHostileNpc {
   combatTags?: string[];
   attributeProfile?: RoleAttributeProfile;
   behaviorVectors?: RoleActionDefinition[];
+  levelProfile?: EntityLevelProfile;
+  experienceReward?: number;
 }
 
 export interface SceneNpc {
@@ -158,6 +180,7 @@ export interface SceneNpc {
   imageSrc?: string;
   visual?: CustomWorldNpcVisual;
   narrativeProfile?: ActorNarrativeProfile | null;
+  levelProfile?: EntityLevelProfile;
 }
 
 export type SceneEncounterKind = 'npc' | 'treasure' | 'none';

src/types/story.ts

@@ -4,8 +4,8 @@ import {
   type QuestStatus,
   type TreasureInteractionAction,
 } from './core';
-import type {InventoryItem} from './items';
-import type {SceneDirective} from './scene';
+import type { InventoryItem } from './items';
+import type { SceneDirective } from './scene';
 
 export interface StoryOptionGoalAffordance {
   goalId: string;
@@ -31,6 +31,7 @@ export interface StoryOption {
 export interface QuestReward {
   affinityBonus: number;
   currency: number;
+  experience?: number;
   items: InventoryItem[];
   storyHint?: string;
   intel?: {
@@ -115,6 +116,11 @@ export interface StoryNpcChatState {
   npcName: string;
   turnCount: number;
   customInputPlaceholder?: string;
+  sceneActId?: string | null;
+  turnLimit?: number | null;
+  remainingTurns?: number | null;
+  limitReason?: 'negative_affinity' | null;
+  forceExitAfterTurn?: boolean;
   pendingQuestOffer?: {
     quest: QuestLogEntry;
   } | null;

src/types/storyEngine.ts

@@ -266,6 +266,15 @@ export interface ChapterState {
   chapterQuestId?: string | null;
 }
 
+export interface SceneActRuntimeState {
+  sceneId: string;
+  chapterId: string;
+  currentActId: string;
+  currentActIndex: number;
+  completedActIds: string[];
+  visitedActIds: string[];
+}
+
 export interface JourneyBeat {
   id: string;
   beatType:
@@ -522,6 +531,7 @@ export interface StoryEngineMemoryState {
   resolvedScarIds: string[];
   recentCarrierIds: string[];
   openedSceneChapterIds?: string[];
+  currentSceneActState?: SceneActRuntimeState | null;
   recentSignalIds?: string[];
   recentCompanionReactions?: CompanionReactionRecord[];
   currentChapter?: ChapterState | null;