Rework story engine flow and reorganize project docs

2026-04-06 23:19:00 +08:00
parent d678929064
commit ddcb5d5c8c
241 changed files with 19805 additions and 2478 deletions
--- a/src/components/game-canvas/GameCanvasEffectLayer.tsx
+++ b/src/components/game-canvas/GameCanvasEffectLayer.tsx
@@ -8,7 +8,7 @@ interface GameCanvasEffectLayerProps {
  activeCombatEffects: CombatVisualEffect[];
  getPlayerEffectLeft: (effectX: number, offsetPx?: number) => string;
  getHostileNpcEffectLeft: (effectX: number, hostileNpcId?: string, offsetPx?: number) => string;
-  sceneHostileNpcs: SceneHostileNpc[];
+  sceneCombatants: SceneHostileNpc[];
  playerCharacter: Character | null;
  groundBottom: string;
  stageLiftPx: number;
@@ -189,7 +189,7 @@ export function GameCanvasEffectLayer({
  activeCombatEffects,
  getPlayerEffectLeft,
  getHostileNpcEffectLeft,
-  sceneHostileNpcs,
+  sceneCombatants,
  playerCharacter,
  groundBottom,
  stageLiftPx,
@@ -210,7 +210,7 @@ export function GameCanvasEffectLayer({
        const startBottom = `calc(${getEntityEffectBottom({
          origin: effect.startOrigin,
          hostileNpcId: effect.startHostileNpcId ?? effect.startMonsterId,
-          sceneHostileNpcs,
+          sceneCombatants,
          playerCharacter,
          groundBottom,
          stageLiftPx,
@@ -220,7 +220,7 @@ export function GameCanvasEffectLayer({
        const endBottom = `calc(${getEntityEffectBottom({
          origin: effect.endOrigin ?? effect.startOrigin,
          hostileNpcId: effect.endHostileNpcId ?? effect.endMonsterId ?? effect.startHostileNpcId ?? effect.startMonsterId,
-          sceneHostileNpcs,
+          sceneCombatants,
          playerCharacter,
          groundBottom,
          stageLiftPx,
--- a/src/components/game-canvas/GameCanvasEntityLayer.tsx
+++ b/src/components/game-canvas/GameCanvasEntityLayer.tsx
@@ -26,6 +26,7 @@ import {
  getMonsterWorldLeft,
  getNpcCombatHpTop,
  getSceneEntityZIndex,
+  HOSTILE_NPC_SCENE_BOTTOM_OFFSET_PX,
  HpBar,
  mapHostileNpcAnimationToCharacterState,
  MONSTER_RENDER_OFFSETS,
@@ -66,7 +67,7 @@ interface GameCanvasEntityLayerProps {
    showEncounter: boolean;
    activeSpeaker?: 'player' | 'npc' | null;
  } | null;
-  sceneHostileNpcs: SceneHostileNpc[];
+  sceneCombatants: SceneHostileNpc[];
  monsters: MonsterSpriteConfig[];
  getHostileNpcOuterLeft: (hostileNpc: SceneHostileNpc) => string;
  groundBottom: string;
@@ -101,7 +102,7 @@ export function GameCanvasEntityLayer({
  effectivePlayerAnimationState,
  shouldShowPlayerDialogueIcon,
  dialogueIndicator = null,
-  sceneHostileNpcs,
+  sceneCombatants,
  monsters,
  getHostileNpcOuterLeft,
  groundBottom,
@@ -242,7 +243,7 @@ export function GameCanvasEntityLayer({
        </div>
      </motion.div>

-      {sceneHostileNpcs.map(hostileNpc => {
+      {sceneCombatants.map(hostileNpc => {
        const npcEncounter = hostileNpc.encounter;
        if (!npcEncounter) return null;
        const config = monsters.find(item => item.id === hostileNpc.id);
@@ -256,13 +257,20 @@ export function GameCanvasEntityLayer({
            ? hostileNpc.facing
            : getRenderableNpcFacing(npcEncounter, hostileNpc.facing, {medievalVisual: true});
        const npcCombatHpTop = getNpcCombatHpTop(npcEncounter?.characterId, npcEncounter?.monsterPresetId);
+        const hostileNpcBottomOffsetPx = npcMonsterConfig
+          ? HOSTILE_NPC_SCENE_BOTTOM_OFFSET_PX
+          : 0;
        const opponentBottom = npcCharacter
          ? getCharacterOpponentBottom(groundBottom, stageLiftPx, npcCharacter)
          : `calc(${groundBottom} + ${stageLiftPx}px)`;
-        const entityBottom = `calc(${opponentBottom} + ${(hostileNpc.yOffset ?? 0)}px)`;
+        const entityBottom = `calc(${opponentBottom} + ${(hostileNpc.yOffset ?? 0) + hostileNpcBottomOffsetPx}px)`;
        const entityBottomOffsetPx = npcCharacter
-          ? getCharacterBottomOffsetPx(stageLiftPx, npcCharacter, hostileNpc.yOffset ?? 0)
-          : stageLiftPx + (hostileNpc.yOffset ?? 0);
+          ? getCharacterBottomOffsetPx(
+              stageLiftPx,
+              npcCharacter,
+              (hostileNpc.yOffset ?? 0) + hostileNpcBottomOffsetPx,
+            )
+          : stageLiftPx + (hostileNpc.yOffset ?? 0) + hostileNpcBottomOffsetPx;

        return (
          <div
@@ -346,9 +354,12 @@ export function GameCanvasEntityLayer({
            encounter.kind === 'npc' && encounter.monsterPresetId
              ? monsters.find(item => item.id === encounter.monsterPresetId) ?? null
              : null;
+          const peacefulHostileBottomOffsetPx = peacefulMonsterConfig
+            ? HOSTILE_NPC_SCENE_BOTTOM_OFFSET_PX
+            : 0;
          const peacefulBottomOffsetPx = peacefulResolvedCharacter
            ? getCharacterBottomOffsetPx(stageLiftPx, peacefulResolvedCharacter)
-            : stageLiftPx;
+            : stageLiftPx + peacefulHostileBottomOffsetPx;
          const peacefulNpcSpriteFacing =
            encounter.kind === 'treasure' || peacefulResolvedCharacter
              ? towardPeacefulPlayer
@@ -370,7 +381,7 @@ export function GameCanvasEntityLayer({
                    stageLiftPx,
                    getCharacterById(encounter.characterId),
                  )
-                  : `calc(${groundBottom} + ${stageLiftPx}px)`,
+                  : `calc(${groundBottom} + ${stageLiftPx + peacefulHostileBottomOffsetPx}px)`,
                zIndex: getSceneEntityZIndex(peacefulBottomOffsetPx),
                transition: isCampCompanionEncounter
                  ? 'bottom 180ms ease'
--- a/src/components/game-canvas/GameCanvasRuntime.tsx
+++ b/src/components/game-canvas/GameCanvasRuntime.tsx
@@ -13,6 +13,7 @@ import {
  getCharacterBottomOffsetPx,
  getMonsterWorldLeft,
  getPlayerWorldLeft,
+  HOSTILE_NPC_SCENE_INSET_PX,
  SCENE_TRANSITION_LOWER_COMPANION_DELAY_S,
  SCENE_TRANSITION_SPEED_PX_PER_S,
  SCENE_TRANSITION_SPRITE_CLEARANCE_PX,
@@ -26,7 +27,6 @@ export function GameCanvasRuntime({
  currentScenePreset,
  worldType,
  sceneHostileNpcs,
-  sceneMonsters,
  playerX,
  playerOffsetY,
  playerFacing,
@@ -58,12 +58,8 @@ export function GameCanvasRuntime({
  const stageLiftPx = 68;
  const playerGroundOffset = playerCharacter?.groundOffsetY ?? 22;
  const cameraAnchorX = scrollWorld ? playerX : PLAYER_BASE_X_METERS;
-  const resolvedSceneHostileNpcs =
-    sceneMonsters && sceneMonsters.length > 0
-      ? sceneMonsters
-      : (sceneHostileNpcs ?? []);
-  const closestHostileNpcDistance = resolvedSceneHostileNpcs.length > 0
-    ? Math.min(...resolvedSceneHostileNpcs.map(hostileNpc => Math.abs(hostileNpc.xMeters - playerX)))
+  const closestHostileNpcDistance = sceneHostileNpcs.length > 0
+    ? Math.min(...sceneHostileNpcs.map(hostileNpc => Math.abs(hostileNpc.xMeters - playerX)))
    : Infinity;
  const escapeLead = scrollWorld ? Math.max(0, Math.min(1, (closestHostileNpcDistance - 1.2) / 3.4)) : 0;
  const sideAnchor = '15%';
@@ -78,10 +74,13 @@ export function GameCanvasRuntime({
    ? playerMeleeLeft
    : playerWorldLeft;
  const monsterAnchorMeters = 3.2;
-  const getHostileNpcOuterLeft = (hostileNpc: (typeof resolvedSceneHostileNpcs)[number]) =>
-    hostileNpc.animation === 'attack' && hostileNpc.combatMode !== 'ranged' && !scrollWorld
-      ? monsterMeleeLeft
-      : getMonsterWorldLeft(sideAnchor, hostileNpc.xMeters, cameraAnchorX, monsterAnchorMeters);
+  const getHostileNpcOuterLeft = (hostileNpc: (typeof sceneHostileNpcs)[number]) => {
+    const baseLeft =
+      hostileNpc.animation === 'attack' && hostileNpc.combatMode !== 'ranged' && !scrollWorld
+        ? monsterMeleeLeft
+        : getMonsterWorldLeft(sideAnchor, hostileNpc.xMeters, cameraAnchorX, monsterAnchorMeters);
+    return `calc(${baseLeft} - ${HOSTILE_NPC_SCENE_INSET_PX}px)`;
+  };
  const getPlayerEffectLeft = (effectX: number, offsetPx = 0) => {
    const base = playerActionMode === 'melee' && !scrollWorld
      ? playerMeleeLeft
@@ -89,7 +88,7 @@ export function GameCanvasRuntime({
    return `calc(${base} + 3.5rem + ${offsetPx}px)`;
  };
  const getHostileNpcEffectLeft = (effectX: number, hostileNpcId?: string, offsetPx = 0) => {
-    const effectHostileNpc = hostileNpcId ? resolvedSceneHostileNpcs.find(hostileNpc => hostileNpc.id === hostileNpcId) : null;
+    const effectHostileNpc = hostileNpcId ? sceneHostileNpcs.find(hostileNpc => hostileNpc.id === hostileNpcId) : null;
    const base = effectHostileNpc
      ? getHostileNpcOuterLeft(effectHostileNpc)
      : getMonsterWorldLeft(sideAnchor, effectX, cameraAnchorX, monsterAnchorMeters);
@@ -183,7 +182,7 @@ export function GameCanvasRuntime({
        effectivePlayerAnimationState={effectivePlayerAnimationState}
        shouldShowPlayerDialogueIcon={shouldShowPlayerDialogueIcon}
        dialogueIndicator={dialogueIndicator}
-        sceneHostileNpcs={resolvedSceneHostileNpcs}
+        sceneCombatants={sceneHostileNpcs}
        monsters={monsters}
        getHostileNpcOuterLeft={getHostileNpcOuterLeft}
        groundBottom={groundBottom}
@@ -198,7 +197,7 @@ export function GameCanvasRuntime({
        activeCombatEffects={activeCombatEffects}
        getPlayerEffectLeft={getPlayerEffectLeft}
        getHostileNpcEffectLeft={getHostileNpcEffectLeft}
-        sceneHostileNpcs={resolvedSceneHostileNpcs}
+        sceneCombatants={sceneHostileNpcs}
        playerCharacter={playerCharacter}
        groundBottom={groundBottom}
        stageLiftPx={stageLiftPx}
--- a/src/components/game-canvas/GameCanvasShared.tsx
+++ b/src/components/game-canvas/GameCanvasShared.tsx
@@ -27,8 +27,7 @@ export interface GameCanvasProps {
  encounter: Encounter | null;
  currentScenePreset: ScenePresetInfo | null;
  worldType: WorldType | null;
-  sceneHostileNpcs?: SceneHostileNpc[];
-  sceneMonsters?: SceneHostileNpc[];
+  sceneHostileNpcs: SceneHostileNpc[];
  playerX: number;
  playerOffsetY: number;
  playerFacing: 'left' | 'right';
@@ -64,6 +63,8 @@ export const DEFAULT_COMBAT_HP_TOP_PX = -18;
 export const CHARACTER_NPC_COMBAT_HP_TOP_PX = -2;
 export const GENERIC_NPC_COMBAT_HP_TOP_PX = 94;
 export const GENERIC_NPC_EFFECT_TARGET_OFFSET_PX = -16;
+export const HOSTILE_NPC_SCENE_INSET_PX = 28;
+export const HOSTILE_NPC_SCENE_BOTTOM_OFFSET_PX = -18;
 export const CHAT_BUBBLE_SPRITE_SRC = '/chat.png';
 export const OPENING_CAMP_OVERLAY_SRC = '/scene_bg/hut.png';
 export const CHAT_BUBBLE_FRAME_WIDTH = 27;
@@ -162,7 +163,7 @@ export function getCharacterBottomOffsetPx(
 export function getEntityEffectBottom({
  origin,
  hostileNpcId,
-  sceneHostileNpcs,
+  sceneCombatants,
  playerCharacter,
  groundBottom,
  stageLiftPx,
@@ -171,7 +172,7 @@ export function getEntityEffectBottom({
 }: {
  origin: 'player' | 'hostile_npc' | 'monster';
  hostileNpcId?: string;
-  sceneHostileNpcs: SceneHostileNpc[];
+  sceneCombatants: SceneHostileNpc[];
  playerCharacter: Character | null;
  groundBottom: string;
  stageLiftPx: number;
@@ -184,7 +185,7 @@ export function getEntityEffectBottom({
  }

  const targetHostileNpc = hostileNpcId
-    ? sceneHostileNpcs.find(hostileNpc => hostileNpc.id === hostileNpcId)
+    ? sceneCombatants.find(hostileNpc => hostileNpc.id === hostileNpcId)
    : null;

  if (!targetHostileNpc) {