+ );
+}
+
+/** Root component: mount runtime once, then viewport */
+function MinimalGame() {
+ const [runtime, setRuntime] = useState(null);
+
+ useEffect(() => {
+ const created = createGameRuntime({
+ scenes: [SCENE_A, SCENE_B],
+ items: [TROPHY_ITEM],
+ // Texto de la frase del hotspot (reglas de diálogo del core).
+ rules: [{ key: "notice.look", phrases: ["Un cartel de la plaza: 'SE BUSCA... un buen guía.'"] }],
+ });
+ // eslint-disable-next-line react-hooks/set-state-in-effect -- publishes the runtime so child hooks can access it before mounting the viewport
+ setRuntime(created);
+
+ return () => {
+ created.dispose();
+ setRuntime(null);
+ };
+ }, []);
+
+ if (!runtime) {
+ return null;
+ }
+
+ return (
+ }
+ />
+ );
+}
+
+export default MinimalGame;
diff --git a/apps/web-demo/app/lib/core/rules/inventoryRules.test.ts b/apps/web-demo/app/lib/core/rules/inventoryRules.test.ts
deleted file mode 100644
index 551fc06..0000000
--- a/apps/web-demo/app/lib/core/rules/inventoryRules.test.ts
+++ /dev/null
@@ -1,130 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
- addOneToInventory,
- removeOneFromSlot,
- resolveInventoryDropHitDecision,
- resolveInventoryDropMissDialogKey,
- resolveInventoryDropOnPlayerMessage,
- resolvePickupPlacedItemDecision,
-} from "./inventoryRules";
-
-describe("inventoryRules", () => {
- it("decrementa cantidad al remover una unidad", () => {
- const next = removeOneFromSlot(
- [
- {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- quantity: 2,
- },
- ],
- 0,
- );
-
- expect(next[0]?.quantity).toBe(1);
- });
-
- it("agrega una unidad a stack existente", () => {
- const result = addOneToInventory(
- [
- {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- quantity: 1,
- },
- ],
- {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- },
- );
-
- expect(result.added).toBe(true);
- expect(result.slots[0]?.quantity).toBe(2);
- });
-
- it("resuelve drop-hit place para gameboy en target valido", () => {
- const interaction = {
- id: "personal-room-gameboy-drop-target",
- kind: "drop-target",
- label: "Soporte del Gameboy",
- position: [3.27, -1.65, 19.71] as [number, number, number],
- halfSize: [0.95, 0.55, 0.95] as [number, number, number],
- hasCollision: true,
- acceptsItemIds: ["gameboy"],
- dialogKeys: {
- hit: "inventoryDropHit",
- miss: "inventoryDropMiss",
- },
- };
-
- const decision = resolveInventoryDropHitDecision({
- interaction,
- payload: {
- stack: {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- },
- fromSlotIndex: 0,
- },
- now: 123,
- });
-
- expect(decision.kind).toBe("place");
- if (decision.kind !== "place") return;
- expect(decision.placedItem.id).toBe("gameboy-personal-room-gameboy-drop-target-123");
- expect(decision.dialogKey).toBe("item.gameboy.drop.personal-room-gameboy-drop-target.hit");
- });
-
- it("usa fallback de miss cuando no hay interaction", () => {
- const key = resolveInventoryDropMissDialogKey({
- payload: {
- stack: {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- },
- fromSlotIndex: 0,
- },
- sceneInteractions: [],
- });
-
- expect(key).toBe("inventoryDropMiss");
- });
-
- it("describe item al soltarlo sobre el player", () => {
- const message = resolveInventoryDropOnPlayerMessage({
- payload: {
- stack: {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- },
- fromSlotIndex: 0,
- },
- });
-
- expect(message.kind).toBe("dialog-key");
- });
-
- it("bloquea pickup cuando el item no es levantable", () => {
- const decision = resolvePickupPlacedItemDecision({
- placedItem: {
- id: "placed-1",
- itemId: "gameboy",
- interactionId: "personal-room-gameboy-drop-target",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- worldPosition: [0, 0, 0],
- canPickup: false,
- },
- });
-
- expect(decision.kind).toBe("blocked");
- });
-});
diff --git a/apps/web-demo/app/lib/core/rules/inventoryRules.ts b/apps/web-demo/app/lib/core/rules/inventoryRules.ts
deleted file mode 100644
index 522ca2e..0000000
--- a/apps/web-demo/app/lib/core/rules/inventoryRules.ts
+++ /dev/null
@@ -1,270 +0,0 @@
-import { getItemDefinition, resolveItemRule } from "../../../../demo-content/items";
-import type { DialogKey } from "../../../../demo-content/dialogs/types";
-import type { SceneInteraction } from "../../../../demo-content/scenes/scenes";
-import type {
- InventorySlotsState,
- PlacedSceneItem,
-} from "@pointclick-engine/engine-core";
-
-export type { InventorySlotsState, PlacedSceneItem };
-
-type DraggedPayloadState = {
- stack: {
- id: string;
- name: string;
- spriteUrl: string;
- };
- fromSlotIndex: number;
-};
-
-type DropHitDecision =
- | {
- kind: "unknown-item";
- message: string;
- }
- | {
- kind: "rule-miss";
- dialogKey: DialogKey;
- }
- | {
- kind: "place";
- fromSlotIndex: number;
- placedItem: PlacedSceneItem;
- dialogKey: DialogKey;
- }
- | {
- kind: "consume";
- fromSlotIndex: number;
- dialogKey: DialogKey;
- }
- | {
- kind: "return";
- dialogKey: DialogKey;
- };
-
-type PickupDecision =
- | {
- kind: "ignore";
- }
- | {
- kind: "blocked";
- dialogKey: DialogKey;
- }
- | {
- kind: "allow";
- placedItemId: string;
- stack: {
- id: string;
- name: string;
- spriteUrl: string;
- };
- successDialogKey: DialogKey;
- };
-
-const UNKNOWN_ITEM_MESSAGE = "No conozco este item todavía.";
-const DEFAULT_DROP_MISS_DIALOG_KEY: DialogKey = "inventoryDropMiss";
-
-function getDefaultPickupDialogKey(itemId: string, type: "allowed" | "blocked"): DialogKey {
- return `item.${itemId}.pickup.${type}` as DialogKey;
-}
-
-export function removeOneFromSlot(
- slots: InventorySlotsState,
- slotIndex: number,
-): InventorySlotsState {
- const slot = slots[slotIndex];
- if (!slot) return slots;
-
- const next = [...slots];
- if (slot.quantity <= 1) {
- next[slotIndex] = null;
- } else {
- next[slotIndex] = { ...slot, quantity: slot.quantity - 1 };
- }
- return next;
-}
-
-export function addOneToInventory(
- slots: InventorySlotsState,
- stack: {
- id: string;
- name: string;
- spriteUrl: string;
- },
-): { slots: InventorySlotsState; added: boolean } {
- const existingIndex = slots.findIndex((current) => current?.id === stack.id);
- if (existingIndex >= 0) {
- const next = [...slots];
- const existing = next[existingIndex];
- if (!existing) return { slots, added: false };
- next[existingIndex] = { ...existing, quantity: existing.quantity + 1 };
- return { slots: next, added: true };
- }
-
- const emptyIndex = slots.findIndex((current) => current == null);
- if (emptyIndex < 0) {
- return { slots, added: false };
- }
-
- const next = [...slots];
- next[emptyIndex] = { ...stack, quantity: 1 };
- return { slots: next, added: true };
-}
-
-export function resolveInventoryDropHitDecision({
- interaction,
- payload,
- now,
-}: {
- interaction: SceneInteraction;
- payload: DraggedPayloadState;
- now: number;
-}): DropHitDecision {
- const itemDefinition = getItemDefinition(payload.stack.id);
- if (!itemDefinition) {
- return {
- kind: "unknown-item",
- message: UNKNOWN_ITEM_MESSAGE,
- };
- }
-
- const rule = resolveItemRule(itemDefinition.id, interaction.id);
- if (!rule) {
- return {
- kind: "rule-miss",
- dialogKey: interaction.dialogKeys.miss,
- };
- }
-
- if (rule.outcome === "place") {
- return {
- kind: "place",
- fromSlotIndex: payload.fromSlotIndex,
- placedItem: {
- id: `${itemDefinition.id}-${interaction.id}-${now}`,
- itemId: itemDefinition.id,
- interactionId: interaction.id,
- name: itemDefinition.name,
- spriteUrl: itemDefinition.spriteUrl,
- worldPosition: [
- interaction.position[0],
- interaction.position[1] + interaction.halfSize[1] + 0.175,
- interaction.position[2],
- ] as [number, number, number],
- canPickup: rule.placeCanPickup ?? false,
- hasCollision: rule.placeHasCollision ?? false,
- collisionHalfSize: rule.placeCollisionHalfSize as [number, number, number] | undefined,
- pickupSuccessDialogKey: rule.pickupSuccessDialogKey,
- pickupBlockedDialogKey: rule.pickupBlockedDialogKey,
- },
- dialogKey: rule.hitDialogKey ?? interaction.dialogKeys.hit,
- };
- }
-
- if (rule.outcome === "consume") {
- return {
- kind: "consume",
- fromSlotIndex: payload.fromSlotIndex,
- dialogKey: rule.hitDialogKey ?? interaction.dialogKeys.hit,
- };
- }
-
- return {
- kind: "return",
- dialogKey:
- rule.hitDialogKey ?? rule.missDialogKey ?? interaction.dialogKeys.miss,
- };
-}
-
-export function resolveInventoryDropMissDialogKey({
- payload,
- interaction,
- sceneInteractions,
-}: {
- payload: DraggedPayloadState;
- interaction?: SceneInteraction;
- sceneInteractions: SceneInteraction[];
-}): DialogKey {
- const itemRule = interaction
- ? resolveItemRule(payload.stack.id, interaction.id)
- : null;
-
- return (
- itemRule?.missDialogKey ??
- interaction?.dialogKeys.miss ??
- sceneInteractions.find(
- (currentInteraction) => currentInteraction.kind === "drop-target",
- )?.dialogKeys.miss ??
- DEFAULT_DROP_MISS_DIALOG_KEY
- );
-}
-
-export function resolveInventoryDropOnPlayerMessage({
- payload,
-}: {
- payload: DraggedPayloadState;
-}):
- | {
- kind: "text";
- text: string;
- }
- | {
- kind: "dialog-key";
- dialogKey: DialogKey;
- } {
- const itemDefinition = getItemDefinition(payload.stack.id);
- if (!itemDefinition) {
- return {
- kind: "text",
- text: UNKNOWN_ITEM_MESSAGE,
- };
- }
-
- if (itemDefinition.descriptionDialogKey) {
- return {
- kind: "dialog-key",
- dialogKey: itemDefinition.descriptionDialogKey,
- };
- }
-
- return {
- kind: "text",
- text: `Es ${itemDefinition.name}.`,
- };
-}
-
-export function resolvePickupPlacedItemDecision({
- placedItem,
-}: {
- placedItem: PlacedSceneItem;
-}): PickupDecision {
- const itemDefinition = getItemDefinition(placedItem.itemId);
- if (!itemDefinition) {
- return { kind: "ignore" };
- }
-
- if (!placedItem.canPickup) {
- return {
- kind: "blocked",
- dialogKey:
- placedItem.pickupBlockedDialogKey ?? getDefaultPickupDialogKey(placedItem.itemId, "blocked"),
- };
- }
-
- return {
- kind: "allow",
- placedItemId: placedItem.id,
- stack: {
- id: itemDefinition.id,
- name: itemDefinition.name,
- spriteUrl: itemDefinition.spriteUrl,
- },
- successDialogKey:
- placedItem.pickupSuccessDialogKey ?? getDefaultPickupDialogKey(placedItem.itemId, "allowed"),
- };
-}
-
-export const inventoryRuleMessages = {
- unknownItem: UNKNOWN_ITEM_MESSAGE,
- inventoryFull: "Inventario lleno.",
-};
diff --git a/apps/web-demo/app/lib/engine/publicApi.test.ts b/apps/web-demo/app/lib/engine/publicApi.test.ts
index 6bcd56e..5f35c8e 100644
--- a/apps/web-demo/app/lib/engine/publicApi.test.ts
+++ b/apps/web-demo/app/lib/engine/publicApi.test.ts
@@ -2,6 +2,9 @@ import { describe, expect, it, vi, afterEach, beforeEach } from "vitest";
import { createElement } from "react";
import { renderToString } from "react-dom/server";
+import { useGameViewportController } from "@pointclick-engine/engine-renderer-r3f";
+import type { RuntimeEvent } from "@pointclick-engine/engine-core";
+
import { DEFAULT_SCENE_ID, SCENES } from "../../../demo-content/scenes/scenes";
import { useInventoryStore } from "../../store/inventoryStore";
import { useDialogStore } from "../../store/dialogStore";
@@ -15,6 +18,8 @@ import {
registerRule,
registerScene,
useGameActions,
+ type GameActions,
+ type GameViewportProps,
type GameItemConfig,
type GameRuleConfig,
type GameSceneConfig,
@@ -118,35 +123,54 @@ describe("publicApi", () => {
Object.values(SCENES).forEach(registerScene);
const sceneIds = Object.keys(SCENES);
- let actionsFromHook: ReturnType | null = null;
+ const holder: { actions: GameActions | null } = { actions: null };
function Probe() {
- actionsFromHook = useGameActions();
+ holder.actions = useGameActions();
return null;
}
renderToString(createElement(Probe));
- expect(actionsFromHook).not.toBeNull();
- expect(typeof actionsFromHook?.setScene).toBe("function");
- expect(typeof actionsFromHook?.setPlayerPosition).toBe("function");
- expect(typeof actionsFromHook?.requestRespawn).toBe("function");
+ expect(holder.actions).not.toBeNull();
+ expect(typeof holder.actions?.setScene).toBe("function");
+ expect(typeof holder.actions?.setPlayerPosition).toBe("function");
+ expect(typeof holder.actions?.requestRespawn).toBe("function");
// Test that setScene actually works
- actionsFromHook?.setScene(sceneIds[0]);
+ holder.actions?.setScene(sceneIds[0]);
const afterSetScene = getGameState();
expect(afterSetScene.sceneId).toBe(sceneIds[0]);
});
- it("GameViewport reenvia debug y onRuntimeEvent al componente base", () => {
- const onRuntimeEvent = () => {};
- const element = GameViewport({
- debug: true,
- onRuntimeEvent,
- });
+ it("GameViewport reenvia debug y onRuntimeEvent a su destino", () => {
+ // GameViewport ya no es un envoltorio sin hooks sobre GameCanvasCore: vive en el
+ // renderer y delega en useGameViewportController (+ GameViewportView). Las dos props
+ // del contrato llegan al controlador, que es quien las consume: `onRuntimeEvent`
+ // recibe cada evento (ademas del bus) y `debug` activa el log de eventos.
+ expect(typeof GameViewport).toBe("function");
+ const runtime = createGameRuntime();
+ const busSpy = vi.fn();
+ runtime.on("player:moved", busSpy);
+ const debugSpy = vi.spyOn(console, "debug").mockImplementation(() => {});
+ const onRuntimeEvent = vi.fn();
+ const props = { debug: true, onRuntimeEvent } satisfies GameViewportProps;
+ const holder: { handle: ((event: RuntimeEvent) => void) | null } = { handle: null };
+
+ function Probe() {
+ holder.handle = useGameViewportController(props).handleRuntimeEvent;
+ return null;
+ }
+ renderToString(createElement(Probe));
+
+ const event: RuntimeEvent = { type: "onMove", position: [1, 0, 2], action: "idle" };
+ holder.handle?.(event);
- expect(element.props.debug).toBe(true);
- expect(element.props.onRuntimeEvent).toBe(onRuntimeEvent);
+ expect(onRuntimeEvent).toHaveBeenCalledWith(event);
+ expect(busSpy).toHaveBeenCalledOnce();
+ expect(debugSpy).toHaveBeenCalledWith("[runtime-event]", event);
+ debugSpy.mockRestore();
+ runtime.dispose();
});
});
@@ -238,6 +262,20 @@ describe("publicApi — bidirectional API (Phase 4)", () => {
// Phase 5: Wired commands
// ---------------------------------------------------------------------------
+function createWiredRuntime(config: Parameters[0] = {}) {
+ return createGameRuntime({
+ ...config,
+ inventoryAdapter: {
+ toggle: () => useInventoryStore.getState().toggle(),
+ isOpen: () => useInventoryStore.getState().isOpen,
+ },
+ dialogAdapter: {
+ show: (text, key) => useDialogStore.getState().show(text, key),
+ hide: () => useDialogStore.getState().dismiss(),
+ },
+ });
+}
+
describe("publicApi — wired commands (Phase 5)", () => {
beforeEach(() => {
// Reset stores before each test
@@ -250,7 +288,7 @@ describe("publicApi — wired commands (Phase 5)", () => {
});
it("inventory:toggle toggles inventoryStore.isOpen", () => {
- const runtime = createGameRuntime();
+ const runtime = createWiredRuntime();
expect(useInventoryStore.getState().isOpen).toBe(false);
runtime.executeCommand({ type: "inventory:toggle" });
@@ -261,7 +299,7 @@ describe("publicApi — wired commands (Phase 5)", () => {
});
it("dialog:trigger shows text in dialogStore and emits event", () => {
- const runtime = createGameRuntime({
+ const runtime = createWiredRuntime({
rules: [{ key: "test.dialog", phrases: ["Hello world"] }],
});
const spy = vi.fn();
@@ -282,13 +320,13 @@ describe("publicApi — wired commands (Phase 5)", () => {
});
it("dialog:trigger uses dialogKey as fallback when rule not registered", () => {
- const runtime = createGameRuntime();
+ const runtime = createWiredRuntime();
runtime.executeCommand({ type: "dialog:trigger", dialogKey: "unregistered.key" });
expect(useDialogStore.getState().text).toBe("unregistered.key");
});
it("dialog:dismiss hides dialogStore and emits event", () => {
- const runtime = createGameRuntime({
+ const runtime = createWiredRuntime({
rules: [{ key: "test.dismiss", phrases: ["Dismiss me"] }],
});
const spy = vi.fn();
@@ -305,4 +343,30 @@ describe("publicApi — wired commands (Phase 5)", () => {
dialogKey: "test.dismiss",
});
});
+
+ it("without adapters, inventory:toggle acts on the default core store and does not throw", () => {
+ const runtime = createGameRuntime();
+ expect(() => runtime.executeCommand({ type: "inventory:toggle" })).not.toThrow();
+ // Los stores de la demo son los del core: el toggle por defecto SI abre el inventario.
+ expect(useInventoryStore.getState().isOpen).toBe(true);
+ runtime.executeCommand({ type: "inventory:toggle" });
+ expect(useInventoryStore.getState().isOpen).toBe(false);
+ });
+
+ it("without adapters, dialog:trigger does not throw and still emits dialog:triggered", () => {
+ const runtime = createGameRuntime({
+ rules: [{ key: "test.noadapter", phrases: ["No adapter"] }],
+ });
+ const spy = vi.fn();
+ runtime.on("dialog:triggered", spy);
+
+ expect(() =>
+ runtime.executeCommand({ type: "dialog:trigger", dialogKey: "test.noadapter" }),
+ ).not.toThrow();
+ // Sin adapter se usa el store por defecto del core (el mismo objeto que el de la demo).
+ expect(useDialogStore.getState().visible).toBe(true);
+ expect(useDialogStore.getState().text).toBe("No adapter");
+ expect(useDialogStore.getState().key).toBe("test.noadapter");
+ expect(spy).toHaveBeenCalledOnce();
+ });
});
diff --git a/apps/web-demo/app/lib/engine/publicApi.ts b/apps/web-demo/app/lib/engine/publicApi.ts
index ba2e783..e5f872d 100644
--- a/apps/web-demo/app/lib/engine/publicApi.ts
+++ b/apps/web-demo/app/lib/engine/publicApi.ts
@@ -1,11 +1,24 @@
"use client";
+/**
+ * Public API mínima del motor de juego (barrel).
+ *
+ * El runtime agnóstico vive en `@pointclick-engine/engine-core`, los hooks y
+ * el canvas en `@pointclick-engine/engine-renderer-r3f`. Este módulo mantiene
+ * el contrato v1 estable re-exportando ambos.
+ */
+
+import { type GameSceneInteractionFull } from "@pointclick-engine/engine-core";
+
// Re-exports from renderer (stable public API)
-export { useR3FGameLoop, WebKeyboardInput } from "@pointclick-engine/engine-renderer-r3f";
+export {
+ useR3FGameLoop,
+ WebKeyboardInput,
+ useGameState,
+ useGameActions,
+} from "@pointclick-engine/engine-renderer-r3f";
-// ---------------------------------------------------------------------------
-// i18n public surface (Phase 13, v0.4.0+) — additions only, no breaking change
-// ---------------------------------------------------------------------------
+// i18n public surface (Phase 13) — additions only
export type {
Locale,
@@ -53,44 +66,12 @@ export type {
I18nProviderProps,
} from "@pointclick-engine/engine-renderer-r3f";
-/**
- * Public API mínima del motor de juego.
- *
- * Este módulo expone contratos estables e independientes de demo/content.
- * Usa estos tipos y funciones para integrar el engine desde fuera sin
- * acoplar a imports internos de app/demo/content.
- */
-
-import { useShallow } from "zustand/react/shallow";
-import { createElement } from "react";
-import type { ComponentType } from "react";
+// Runtime (vive en engine-core)
-import {
- useSceneStore,
- setSceneStoreEmitter,
- EventBus,
- CommandHandler,
- findPath,
- type GameVec3,
- type GameSceneGround,
- type GameSceneWall,
- type GameSceneInteractionFull,
- type GameEvent,
- type GameEventType,
- type GameEventHandler,
- type GameCommand,
- type SceneMusicConfig,
-} from "@pointclick-engine/engine-core";
-import { GameCanvasCore } from "@pointclick-engine/engine-renderer-r3f";
-
-// ---------------------------------------------------------------------------
-// Tipos públicos reutilizables (importados o re-exportados de engine-core)
-// ---------------------------------------------------------------------------
-
-// Re-export key types from engine-core for API stability
-export type { GameVec3, GameSceneGround, GameSceneWall } from "@pointclick-engine/engine-core";
-// Re-export bidirectional API types
export type {
+ GameVec3,
+ GameSceneGround,
+ GameSceneWall,
GameEvent,
GameEventType,
GameEventHandler,
@@ -100,527 +81,33 @@ export type {
// Alias for public API compatibility
export type GameSceneInteraction = GameSceneInteractionFull;
-/** Configuración de escena registrable via API pública. */
-export type GameSceneConfig = {
- id: string;
- label: string;
- background: string;
- playerSpawn: GameVec3;
- ground: GameSceneGround;
- walls: GameSceneWall[];
- interactions: GameSceneInteraction[];
- music?: SceneMusicConfig;
-};
-
-export type GameItemDropOutcome =
- | "consume"
- | "place"
- | "return"
- | "rule-miss"
- | "unknown-item"
- | "on-player"
- | "pickup-blocked"
- | "pickup-success";
-
-export type GameItemRule = {
- outcome: GameItemDropOutcome;
- hitDialogKey?: string;
- missDialogKey?: string;
- placeCanPickup?: boolean;
- placeHasCollision?: boolean;
- placeCollisionHalfSize?: GameVec3;
- pickupSuccessDialogKey?: string;
- pickupBlockedDialogKey?: string;
- dropSoundUrl?: string;
-};
-
-/** Configuración de ítem registrable via API pública. */
-export type GameItemConfig = {
- id: string;
- name: string;
- spriteUrl: string;
- descriptionDialogKey?: string;
- pickupSoundUrl?: string;
- dropSoundUrl?: string;
- interactionRules: Record;
- defaultRule: GameItemRule;
-};
-
-/** Regla de texto/diálogo registrable via API pública. */
-export type GameRuleConfig = {
- key: string;
- phrases: string[];
-};
-
-/** Props del punto de integración GameViewport (canvas + runtime). */
-export type GameViewportProps = {
- debug?: boolean;
- onRuntimeEvent?: GameRuntimeEventHandler;
-};
-
-// ---------------------------------------------------------------------------
-// Eventos de runtime (legacy — mantenidos por backwards compat)
-// ---------------------------------------------------------------------------
-
-export type GameRuntimeEvent =
- | {
- type: "onMove";
- position: GameVec3;
- action: "idle" | "north" | "south" | "west" | "east";
- }
- | { type: "onCollide"; reason: "boundary" | "stuck"; position: GameVec3 }
- | { type: "onDrop"; outcome: string; itemId: string; interactionId?: string }
- | { type: "onDialog"; text: string; dialogKey?: string; source: string };
-
-export type GameRuntimeEventHandler = (event: GameRuntimeEvent) => void;
-
-// ---------------------------------------------------------------------------
-// Handle de runtime devuelto por createGameRuntime (Phase 4)
-// ---------------------------------------------------------------------------
-
-export type GameRuntime = {
- // Registro (existentes)
- getScenes: () => Record;
- getItems: () => Record;
- getRules: () => Record;
- // Bidirectional API (Phase 4)
- /**
- * Envía un comando al motor. Sync, fire-and-forget.
- * Comandos sin executor registrado loguean warn y no hacen nada.
- * Ver ADR-0006 y docs/architecture/05-bidirectional-communication.md.
- */
- executeCommand: (cmd: GameCommand) => void;
- /**
- * Suscribe a un tipo de evento del motor.
- * @returns unsubscribe — llámalo para cancelar la suscripción (ej. en useEffect cleanup).
- */
- on: (type: T, handler: GameEventHandler) => () => void;
- /**
- * Emite un evento al bus del runtime.
- * Útil para que el renderer envíe eventos sin conocer el store.
- */
- emit: (event: GameEvent) => void;
- /**
- * Libera el bus y desactiva las emisiones del store.
- * Llamar al desmontar la app / en tests cleanup.
- */
- dispose: () => void;
-};
-
-type SceneStoreSnapshot = ReturnType;
-
-export type GameState = Pick<
- SceneStoreSnapshot,
- "sceneId" | "scene" | "playerPosition" | "respawnSignal"
->;
-
-export type GameActions = Pick<
- SceneStoreSnapshot,
- "setScene" | "setPlayerPosition" | "requestRespawn"
->;
-
-function toGameState(state: SceneStoreSnapshot): GameState {
- return {
- sceneId: state.sceneId,
- scene: state.scene,
- playerPosition: state.playerPosition,
- respawnSignal: state.respawnSignal,
- };
-}
-
-// ---------------------------------------------------------------------------
-// Configuración de createGameRuntime
-// ---------------------------------------------------------------------------
-
-/** Adapter para conectar el engine con la UI de inventario del host. */
-export interface InventoryUIAdapter {
- toggle(): void;
- isOpen(): boolean;
-}
-
-/** Adapter para conectar el engine con el sistema de diálogos del host. */
-export interface DialogUIAdapter {
- show(text: string, dialogKey?: string): void;
- hide(): void;
-}
-
-export type GameRuntimeConfig = {
- scenes?: GameSceneConfig[];
- items?: GameItemConfig[];
- rules?: GameRuleConfig[];
- /** Adapter de UI para inventory. Si no se pasa, inventory:toggle es no-op. */
- inventoryAdapter?: InventoryUIAdapter;
- /** Adapter de UI para diálogos. Si no se pasa, dialog:trigger es no-op. */
- dialogAdapter?: DialogUIAdapter;
-};
-
-// ---------------------------------------------------------------------------
-// Registros internos (singleton de módulo)
-// ---------------------------------------------------------------------------
-
-const _sceneRegistry = new Map();
-const _itemRegistry = new Map();
-const _ruleRegistry = new Map();
-
-/** Singleton del runtime activo. Accesible vía getGameRuntime(). */
-let _runtimeHandle: GameRuntime | null = null;
-
-/**
- * Registra una escena en el motor.
- * Idempotente: registrar la misma id sobreescribe la anterior.
- */
-export function registerScene(config: GameSceneConfig): void {
- _sceneRegistry.set(config.id, config);
-}
-
-/**
- * Registra un ítem en el motor.
- * Idempotente: registrar el mismo id sobreescribe el anterior.
- */
-export function registerItem(config: GameItemConfig): void {
- _itemRegistry.set(config.id, config);
-}
-
-/**
- * Registra una regla de diálogo en el motor.
- * Idempotente: registrar la misma key sobreescribe la anterior.
- */
-export function registerRule(config: GameRuleConfig): void {
- _ruleRegistry.set(config.key, config);
-}
-
-// ---------------------------------------------------------------------------
-// Factory principal
-// ---------------------------------------------------------------------------
-
-/**
- * Inicializa el runtime con las escenas, ítems y reglas proporcionadas.
- *
- * Registra cada config en el registry global, crea el EventBus y el
- * CommandHandler, y devuelve un handle con acceso completo a la API
- * bidireccional (`executeCommand`, `on`, `emit`, `dispose`).
- *
- * El handle se almacena como singleton accesible vía `getGameRuntime()`.
- *
- * @example
- * ```ts
- * const runtime = createGameRuntime({ scenes: [myScene], items: [myItem] });
- * runtime.on("scene:changed", (e) => console.log("now in:", e.sceneId));
- * runtime.executeCommand({ type: "scene:set", sceneId: myScene.id });
- * ```
- */
-export function createGameRuntime(config: GameRuntimeConfig = {}): GameRuntime {
- // Register content
- for (const scene of config.scenes ?? []) {
- registerScene(scene);
- }
- for (const item of config.items ?? []) {
- registerItem(item);
- }
- for (const rule of config.rules ?? []) {
- registerRule(rule);
- }
-
- // Create bus and command handler
- const bus = new EventBus();
- const commands = new CommandHandler();
-
- // Wire store → bus
- setSceneStoreEmitter((event) => bus.emit(event.type, event));
-
- // Register executors: scene commands
- commands.register("scene:set", (cmd) => {
- const sceneConfig = _sceneRegistry.get(cmd.sceneId);
- if (!sceneConfig) {
- console.warn(`[runtime] scene:set — scene not registered: ${cmd.sceneId}`);
- return;
- }
- useSceneStore.getState().setScene(sceneConfig.id, {
- id: sceneConfig.id,
- label: sceneConfig.label,
- background: sceneConfig.background,
- playerSpawn: sceneConfig.playerSpawn,
- ground: sceneConfig.ground,
- walls: sceneConfig.walls,
- interactions: sceneConfig.interactions,
- });
- });
-
- commands.register("scene:respawn", () => {
- useSceneStore.getState().requestRespawn();
- });
-
- commands.register("player:move", (cmd) => {
- useSceneStore.getState().setPlayerPosition(cmd.position);
- });
-
- commands.register("player:walkTo", (cmd) => {
- const state = useSceneStore.getState();
- const from: [number, number, number] = [
- state.playerPosition[0],
- state.playerPosition[1],
- state.playerPosition[2],
- ];
- const to: [number, number, number] = [
- cmd.position[0],
- cmd.position[1],
- cmd.position[2],
- ];
-
- // console.log(`[walkTo] from ${JSON.stringify(from)} to ${JSON.stringify(to)}`);
-
- // Calculate path using existing pathfinding
- const pathResult = findPath({
- start: { x: from[0], z: from[2] },
- goal: { x: to[0], z: to[2] },
- bounds: {
- minX: state.scene.ground.minX,
- maxX: state.scene.ground.maxX,
- minZ: state.scene.ground.minZ,
- maxZ: state.scene.ground.maxZ,
- },
- walls: state.scene.walls,
- interactions: state.scene.interactions,
- });
-
- // console.log(`[walkTo] pathResult length:`, pathResult?.length ?? 0);
-
- if (pathResult && pathResult.length > 0) {
- // Convert path points back to GameVec3 format
- // Always include start point + pathfinding results to ensure ≥2 points for interpolation
- const pathPoints: typeof cmd.position[] = [
- from, // Start position
- ...pathResult.map((point) => [
- point.x,
- state.scene.ground.y,
- point.z,
- ] as typeof cmd.position),
- ];
-
- // console.log(`[walkTo] setting walk state with ${pathPoints.length} points`);
-
- // Create walk state and activate animation
- state.setPlayerWalkingState({
- targetPosition: cmd.position,
- pathPoints,
- progress: 0,
- isActive: true,
- });
-
- // Emit event for listeners
- bus.emit("player:walkStarted", {
- type: "player:walkStarted",
- targetPosition: cmd.position,
- });
- } else {
- console.log(`[walkTo] no path found - aborting`);
- // Path not found
- bus.emit("player:walkAborted", {
- type: "player:walkAborted",
- reason: "unreachable",
- });
- }
- });
-
- // ---------------------------------------------------------------------------
- // Wired executors (Phase 5)
- // ---------------------------------------------------------------------------
-
- commands.register("inventory:toggle", () => {
- config.inventoryAdapter?.toggle();
- });
-
- // Track the active dialog key so dialog:dismiss can include it in the event
- let _activeDialogKey: string | undefined;
-
- commands.register("dialog:trigger", (cmd) => {
- const entry = _ruleRegistry.get(cmd.dialogKey);
- const phrases = entry?.phrases ?? [];
- const text =
- phrases.length > 0
- ? phrases[Math.floor(Math.random() * phrases.length)]!
- : cmd.dialogKey;
- _activeDialogKey = cmd.dialogKey;
- config.dialogAdapter?.show(text, cmd.dialogKey);
- bus.emit("dialog:triggered", {
- type: "dialog:triggered",
- text,
- dialogKey: cmd.dialogKey,
- source: "command",
- });
- });
-
- commands.register("dialog:dismiss", () => {
- const key = _activeDialogKey;
- _activeDialogKey = undefined;
- config.dialogAdapter?.hide();
- bus.emit("dialog:dismissed", {
- type: "dialog:dismissed",
- dialogKey: key,
- });
- });
-
- // ---------------------------------------------------------------------------
- // Transition executors (Phase 8)
- // ---------------------------------------------------------------------------
-
- commands.register("transition:activate", (cmd) => {
- const state = useSceneStore.getState();
- const transition = state.scene.transitions?.find(
- (t) => t.id === cmd.transitionId,
- );
- if (!transition) {
- console.warn(`[runtime] transition:activate — unknown transition: ${cmd.transitionId}`);
- return;
- }
- const fromSceneId = state.sceneId;
- bus.emit("transition:started", {
- type: "transition:started",
- transitionId: cmd.transitionId,
- });
- const sceneConfig = _sceneRegistry.get(transition.targetSceneId);
- if (!sceneConfig) {
- console.warn(`[runtime] transition:activate — target scene not registered: ${transition.targetSceneId}`);
- return;
- }
- useSceneStore.getState().setScene(sceneConfig.id, {
- id: sceneConfig.id,
- label: sceneConfig.label,
- background: sceneConfig.background,
- playerSpawn: sceneConfig.playerSpawn,
- ground: sceneConfig.ground,
- walls: sceneConfig.walls,
- interactions: sceneConfig.interactions,
- });
- bus.emit("transition:completed", {
- type: "transition:completed",
- fromSceneId,
- toSceneId: transition.targetSceneId,
- });
- });
-
- commands.register("transition:cancel", (cmd) => {
- useSceneStore.getState().setTransitionItemOccupying(cmd.transitionId, undefined);
- });
-
- // ---------------------------------------------------------------------------
- // Formally deferred executors (v0.2.0)
- // ---------------------------------------------------------------------------
-
- commands.register("player:stop", (cmd) =>
- console.warn(
- `[runtime] executor deferred to v0.2.0: ${cmd.type} — requires renderer-r3f DI prop for cancelTarget. See docs/phases/phase-5-publish/tasks/02-wire-pending-commands.md#aplazados`,
- ),
- );
-
- commands.register("inventory:pickup", (cmd) =>
- console.warn(
- `[runtime] executor deferred to v0.2.0: ${cmd.type} — requires UI context (which interaction was clicked). See docs/phases/phase-9-placed-items-agnóstic/README.md#phase-d`,
- ),
- );
-
- commands.register("inventory:drop", (cmd) =>
- console.warn(
- `[runtime] executor deferred to v0.2.0: ${cmd.type} — requires UI context (drag coordinates, target interaction). See docs/phases/phase-9-placed-items-agnóstic/README.md#phase-d`,
- ),
- );
-
- const runtime: GameRuntime = {
- getScenes: () => Object.fromEntries(_sceneRegistry),
- getItems: () => Object.fromEntries(_itemRegistry),
- getRules: () => Object.fromEntries(_ruleRegistry),
- executeCommand: (cmd) => commands.execute(cmd),
- on: (type: T, handler: GameEventHandler) =>
- bus.on(type, handler as (data: unknown) => void),
- emit: (event: GameEvent) => bus.emit(event.type, event),
- dispose: () => {
- bus.clear();
- commands.clear();
- setSceneStoreEmitter(null);
- if (_runtimeHandle === runtime) _runtimeHandle = null;
- },
- };
-
- _runtimeHandle = runtime;
- return runtime;
-}
-
-/**
- * Devuelve el handle del runtime activo (creado por `createGameRuntime`).
- * Retorna `null` si no se ha inicializado o tras llamar a `dispose()`.
- *
- * Útil para acceder al runtime desde componentes o callbacks que no
- * tienen acceso directo al handle (ej. GameTouchCanvas).
- */
-export function getGameRuntime(): GameRuntime | null {
- return _runtimeHandle;
-}
-
-/** Lee snapshot del estado público del runtime sin usar hooks React. */
-export function getGameState(): GameState {
- return toGameState(useSceneStore.getState());
-}
-
-/** Lee acciones públicas del runtime sin usar hooks React. */
-export function getGameActions(): GameActions {
- const state = useSceneStore.getState();
- return {
- setScene: (id: string) => {
- const sceneConfig = _sceneRegistry.get(id);
- if (!sceneConfig) {
- console.warn(`Scene not registered: ${id}`);
- return;
- }
- state.setScene(id, {
- id: sceneConfig.id,
- label: sceneConfig.label,
- background: sceneConfig.background,
- playerSpawn: sceneConfig.playerSpawn,
- ground: sceneConfig.ground,
- walls: sceneConfig.walls,
- interactions: sceneConfig.interactions,
- });
- },
- setPlayerPosition: state.setPlayerPosition,
- requestRespawn: state.requestRespawn,
- };
-}
-
-/** Hook para seleccionar estado de juego desde la API pública. */
-export function useGameState(selector: (state: GameState) => T): T {
- return useSceneStore((state) => selector(toGameState(state)));
-}
+export type {
+ GameSceneConfig,
+ GameItemDropOutcome,
+ GameItemRule,
+ GameItemConfig,
+ GameRuleConfig,
+ GameRuntimeEvent,
+ GameRuntimeEventHandler,
+ GameRuntime,
+ GameState,
+ GameActions,
+ InventoryUIAdapter,
+ DialogUIAdapter,
+ GameRuntimeConfig,
+} from "@pointclick-engine/engine-core";
-/** Hook para obtener acciones públicas con referencia estable. */
-export function useGameActions(): GameActions {
- return useSceneStore(
- useShallow((state) => ({
- setScene: (id: string) => {
- const sceneConfig = _sceneRegistry.get(id);
- if (!sceneConfig) {
- console.warn(`Scene not registered: ${id}`);
- return;
- }
- state.setScene(id, {
- id: sceneConfig.id,
- label: sceneConfig.label,
- background: sceneConfig.background,
- playerSpawn: sceneConfig.playerSpawn,
- ground: sceneConfig.ground,
- walls: sceneConfig.walls,
- interactions: sceneConfig.interactions,
- });
- },
- setPlayerPosition: state.setPlayerPosition,
- requestRespawn: state.requestRespawn,
- })),
- );
-}
+export {
+ registerScene,
+ registerItem,
+ registerRule,
+ createGameRuntime,
+ getGameRuntime,
+ getGameState,
+ getGameActions,
+} from "@pointclick-engine/engine-core";
-/** Integración pública de viewport/canvas para consumir el runtime. */
-export function GameViewport({ debug, onRuntimeEvent }: GameViewportProps) {
- return createElement(GameCanvasCore as ComponentType, {
- debug,
- onRuntimeEvent,
- });
-}
+// Viewport jugable (vive en el renderer). Mantiene el contrato v1: `GameViewport`
+// y `GameViewportProps` con `debug` y `onRuntimeEvent`.
+export { GameViewport } from "@pointclick-engine/engine-renderer-r3f";
+export type { GameViewportProps } from "@pointclick-engine/engine-renderer-r3f";
diff --git a/apps/web-demo/app/lib/engine/render/SpeechBubble.tsx b/apps/web-demo/app/lib/engine/render/SpeechBubble.tsx
deleted file mode 100644
index b63a71c..0000000
--- a/apps/web-demo/app/lib/engine/render/SpeechBubble.tsx
+++ /dev/null
@@ -1,242 +0,0 @@
-"use client";
-
-import { RoundedBox, Text } from "@react-three/drei";
-import { useEffect, useMemo, useRef, useState } from "react";
-
-import { browserTimerAdapter, type TimerHandle } from "../../platform-web";
-import { useSceneStore } from "@pointclick-engine/engine-core";
-
-type SpeechBubbleProps = {
- text: string;
- visible: boolean;
- trigger: number;
- charsPerSecond?: number;
- onDismiss?: () => void;
-};
-
-const SPRITE_HALF_WIDTH_WORLD = 0.62;
-const BUBBLE_GAP_WORLD = 0.22;
-const DEPTH_FAR_Z = -16;
-const DEPTH_NEAR_Z = 8;
-const SPRITE_MIN_SCALE = 1.4;
-const SPRITE_MAX_SCALE = 2.94;
-const SPRITE_HALF_WIDTH_FACTOR = 0.36;
-const BORDER_PADDING = 0.09;
-const SPRITE_CENTER_Y_OFFSET = -0.95;
-const BUBBLE_HEADROOM = -1;
-const TEXT_PADDING_X = 0.2;
-const TEXT_PADDING_Y = 0.16;
-const FONT_SIZE = 0.2;
-const LINE_HEIGHT = 1.18;
-const AVG_CHAR_WIDTH_WORLD = 0.096;
-const MIN_BUBBLE_WIDTH = 0.6;
-const MAX_BUBBLE_WIDTH = 5.2;
-const MIN_BUBBLE_HEIGHT = 0.45;
-const MAX_BUBBLE_HEIGHT = 3.8;
-const MS_PER_WORD_READ = 286;
-const MIN_READ_MS = 2080;
-const MAX_READ_MS = 10400;
-
-function clamp(value: number, min: number, max: number) {
- return Math.max(min, Math.min(max, value));
-}
-
-function lerp(start: number, end: number, t: number) {
- return start + (end - start) * t;
-}
-
-function wrapParagraphByWords(paragraph: string, maxCharsPerLine: number) {
- const words = paragraph.trim().split(/\s+/).filter(Boolean);
- if (words.length === 0) return [""];
-
- const lines: string[] = [];
- let currentLine = words[0];
-
- for (let index = 1; index < words.length; index += 1) {
- const candidate = `${currentLine} ${words[index]}`;
- if (candidate.length <= maxCharsPerLine) {
- currentLine = candidate;
- } else {
- lines.push(currentLine);
- currentLine = words[index];
- }
- }
-
- lines.push(currentLine);
- return lines;
-}
-
-export default function SpeechBubble({
- text,
- visible,
- trigger,
- charsPerSecond = 30,
- onDismiss,
-}: SpeechBubbleProps) {
- const playerPosition = useSceneStore((state) => state.playerPosition);
- const ground = useSceneStore((state) => state.scene.ground);
- const normalizedText = useMemo(() => text.trim(), [text]);
- const [displayedText, setDisplayedText] = useState("");
- const dismissTimerRef = useRef(null);
-
- // ── Layout estático: calculado UNA vez por diálogo (dep: normalizedText) ──
- // wrappedText: el texto con \n explícitos en los saltos de línea.
- // - El efecto tipea sobre wrappedText → cada palabra aparece ya en su
- // línea final desde el primer carácter. Nunca salta de línea.
- // bubbleWidth / textMaxWidth fijos desde el inicio → troika nunca
- // re-envuelve mientras se tipea, eliminando el baile de palabras.
- // NOTA: los espacios entre palabras que se convierten en \n tienen la
- // misma longitud (1 char) → los índices del tipeo coinciden exactamente.
- const { bubbleWidth, textMaxWidth, fullBubbleHeight, wrappedText } = useMemo(() => {
- const fullText = normalizedText.length > 0 ? normalizedText : " ";
- const totalChars = Math.max(1, fullText.length);
- const targetCPL = clamp(Math.round(Math.sqrt(totalChars) * 2.4), 18, 36);
- const paragraphs = fullText.split("\n");
- const wrappedFull = paragraphs.flatMap((p) =>
- p.trim().length === 0 ? [""] : wrapParagraphByWords(p, targetCPL),
- );
- const longestChars = Math.max(1, ...wrappedFull.map((l) => l.length));
- const rawTextWidth = clamp(
- longestChars * AVG_CHAR_WIDTH_WORLD,
- MIN_BUBBLE_WIDTH - TEXT_PADDING_X * 2,
- MAX_BUBBLE_WIDTH - TEXT_PADDING_X * 2,
- );
- const bw = clamp(rawTextWidth + TEXT_PADDING_X * 2, MIN_BUBBLE_WIDTH, MAX_BUBBLE_WIDTH);
- const fullLineCount = Math.max(1, wrappedFull.length);
- const fbh = clamp(
- fullLineCount * FONT_SIZE * LINE_HEIGHT + TEXT_PADDING_Y * 2,
- MIN_BUBBLE_HEIGHT,
- MAX_BUBBLE_HEIGHT,
- );
- return {
- bubbleWidth: bw,
- textMaxWidth: bw - TEXT_PADDING_X * 2,
- fullBubbleHeight: fbh,
- wrappedText: wrappedFull.join("\n"),
- };
- }, [normalizedText]);
-
- // ── Efecto de tipeo ────────────────────────────────────────────────────────
- useEffect(() => {
- if (!visible || wrappedText.length === 0) return;
-
- let index = 0;
- const msPerChar = Math.max(14, Math.floor(1000 / Math.max(1, charsPerSecond)));
-
- const timer = browserTimerAdapter.setInterval(() => {
- index += 1;
- setDisplayedText(wrappedText.slice(0, index));
-
- if (index >= wrappedText.length) {
- browserTimerAdapter.clearInterval(timer);
-
- if (onDismiss) {
- const wordCount = normalizedText.trim().split(/\s+/).filter(Boolean).length;
- const readMs = clamp(wordCount * MS_PER_WORD_READ, MIN_READ_MS, MAX_READ_MS);
- dismissTimerRef.current = browserTimerAdapter.setTimeout(onDismiss, readMs);
- }
- }
- }, msPerChar);
-
- return () => {
- browserTimerAdapter.clearInterval(timer);
- if (dismissTimerRef.current !== null) {
- browserTimerAdapter.clearTimeout(dismissTimerRef.current);
- dismissTimerRef.current = null;
- }
- };
- }, [charsPerSecond, wrappedText, normalizedText, onDismiss, trigger, visible]);
-
- const shouldShowLeft = useMemo(() => {
- const worldEdgePadding = 0.9;
- const spaceLeft = playerPosition[0] - ground.minX - worldEdgePadding;
- const spaceRight = ground.maxX - playerPosition[0] - worldEdgePadding;
- return spaceLeft > spaceRight;
- }, [ground.maxX, ground.minX, playerPosition]);
-
- const depthFactor = useMemo(() => {
- return clamp((playerPosition[2] - DEPTH_FAR_Z) / (DEPTH_NEAR_Z - DEPTH_FAR_Z), 0, 1);
- }, [playerPosition]);
-
- const spriteScale = useMemo(() => {
- return lerp(SPRITE_MIN_SCALE, SPRITE_MAX_SCALE, depthFactor);
- }, [depthFactor]);
-
- // ── Alto dinámico: displayedText ya tiene \n → solo contar líneas ─────────
- const bubbleHeight = useMemo(() => {
- const lineCount = Math.max(1, displayedText.split("\n").length);
- const textHeight = lineCount * FONT_SIZE * LINE_HEIGHT;
- return clamp(textHeight + TEXT_PADDING_Y * 2, MIN_BUBBLE_HEIGHT, MAX_BUBBLE_HEIGHT);
- }, [displayedText]);
-
- if (!visible || normalizedText.length === 0) {
- return null;
- }
-
- const spriteHalfWidthWorld = Math.max(SPRITE_HALF_WIDTH_WORLD, spriteScale * SPRITE_HALF_WIDTH_FACTOR);
- const sideOffset = spriteHalfWidthWorld + BUBBLE_GAP_WORLD;
- const offsetX = shouldShowLeft ? -sideOffset : sideOffset;
- // offsetY = borde SUPERIOR del bocadillo. Crece hacia abajo desde aquí.
- const offsetY = (2 * spriteScale) + SPRITE_CENTER_Y_OFFSET + BUBBLE_HEADROOM;
- const bubbleCenterX = shouldShowLeft
- ? offsetX - bubbleWidth / 2
- : offsetX + bubbleWidth / 2;
- const arrowBaseX = shouldShowLeft ? offsetX + 0.07 : offsetX - 0.07;
- const arrowRotationZ = shouldShowLeft ? -Math.PI / 2 : Math.PI / 2;
-
- return (
- // Grupo anclado al borde superior del bocadillo
-
- {/* Bocadillo: centro en -bubbleHeight/2 → parte superior fija en Y=0 */}
-
-
-
-
-
-
-
- {/* maxWidth = textMaxWidth → padding simétrico izquierda/derecha.
- Las líneas ya vienen pre-envueltas con \n explícitos, así que
- troika no necesita re-envolver; el valor actúa solo como límite
- de borde derecho para igualar el padding izquierdo. */}
-
- {displayedText}
-
-
-
- {/* Rabillo: 30% desde el borde superior del bocadillo completo —
- fijo durante el tipeo, entre el borde superior y el centro */}
-
-
-
-
-
-
-
-
-
- );
-}
diff --git a/apps/web-demo/app/lib/engine/render/scene/SceneCollisionSphere.tsx b/apps/web-demo/app/lib/engine/render/scene/SceneCollisionSphere.tsx
deleted file mode 100644
index e5abac6..0000000
--- a/apps/web-demo/app/lib/engine/render/scene/SceneCollisionSphere.tsx
+++ /dev/null
@@ -1,31 +0,0 @@
-"use client";
-
-import { useLoader } from "@react-three/fiber";
-import { BallCollider, RigidBody } from "@react-three/rapier";
-import { TextureLoader } from "three";
-
-import { useSceneStore } from "@pointclick-engine/engine-core";
-
-export function SceneCollisionSphere() {
- const globeTexture = useLoader(TextureLoader, "/globe.svg");
- const groundY = useSceneStore((s) => s.scene.ground.y);
- const posY = groundY + 0.1 + 0.5;
-
- return (
-
-
-
-
-
-
-
- );
-}
diff --git a/apps/web-demo/app/lib/engine/render/scene/SceneGround.tsx b/apps/web-demo/app/lib/engine/render/scene/SceneGround.tsx
deleted file mode 100644
index c0fd86f..0000000
--- a/apps/web-demo/app/lib/engine/render/scene/SceneGround.tsx
+++ /dev/null
@@ -1,126 +0,0 @@
-"use client";
-
-import { useMemo } from "react";
-import { CuboidCollider, RigidBody } from "@react-three/rapier";
-
-import { useSceneStore } from "@pointclick-engine/engine-core";
-
-const checkerVertexShader = /* glsl */`
- varying vec2 vUv;
- void main() {
- vUv = uv;
- gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
- }
-`;
-
-const checkerFragmentShader = /* glsl */`
- varying vec2 vUv;
- uniform float uCells;
- void main() {
- vec2 cell = floor(vUv * uCells);
- float checker = mod(cell.x + cell.y, 2.0);
- vec3 col = checker > 0.5 ? vec3(0.0, 1.0, 0.25) : vec3(0.0, 0.0, 0.0);
- float alpha = checker > 0.5 ? 0.28 : 0.04;
- gl_FragColor = vec4(col, alpha);
- }
-`;
-
-export function SceneGround({
- onClickWorld,
- onHoverWorld,
- debug,
- depthNearZ,
- depthFarZ,
-}: {
- onClickWorld: (x: number, z: number) => void;
- onHoverWorld?: (x: number, z: number) => void;
- debug: boolean;
- depthNearZ: number;
- depthFarZ: number;
-}) {
- const ground = useSceneStore((s) => s.scene.ground);
-
- const width = ground.maxX - ground.minX;
- const depth = ground.maxZ - ground.minZ;
- const centerX = (ground.minX + ground.maxX) / 2;
- const centerZ = (ground.minZ + ground.maxZ) / 2;
-
- const segX = Math.round(width / 2);
- const segZ = Math.round(depth / 2);
-
- const gy = ground.y + 0.02;
- const t = 0.05;
- const borderWallHalfHeight = 3;
- const borderWallHalfThickness = 0.35;
- const borderWallCenterY = ground.y + borderWallHalfHeight;
-
- const cells = Math.max(segX, segZ);
- const checkerUniforms = useMemo(() => ({ uCells: { value: cells } }), [cells]);
-
- return (
- <>
-
-
- {
- e.stopPropagation();
- onClickWorld(e.point.x, e.point.z);
- }}
- onPointerMove={(e) => {
- if (!onHoverWorld) return;
- onHoverWorld(e.point.x, e.point.z);
- }}
- >
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- {debug && (
- <>
- null}>
-
-
-
- null}>
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
- >
- )}
- >
- );
-}
diff --git a/apps/web-demo/app/lib/engine/render/scene/SceneWallPointPreview.tsx b/apps/web-demo/app/lib/engine/render/scene/SceneWallPointPreview.tsx
deleted file mode 100644
index 2f5af67..0000000
--- a/apps/web-demo/app/lib/engine/render/scene/SceneWallPointPreview.tsx
+++ /dev/null
@@ -1,49 +0,0 @@
-"use client";
-
-import { useMemo } from "react";
-import type { Vector2 } from "three";
-
-type WallPointPreview = {
- start: Vector2;
- end: Vector2;
-};
-
-export function SceneWallPointPreview({
- preview,
- groundY,
-}: {
- preview: WallPointPreview | null;
- groundY: number;
-}) {
- const pointPreviewLength = useMemo(() => {
- if (!preview) return 0;
- return Math.sqrt((preview.end.x - preview.start.x) ** 2 + (preview.end.y - preview.start.y) ** 2);
- }, [preview]);
-
- const pointPreviewMidX = preview ? (preview.start.x + preview.end.x) / 2 : 0;
- const pointPreviewMidZ = preview ? (preview.start.y + preview.end.y) / 2 : 0;
- const pointPreviewRotationY = preview
- ? -Math.atan2(preview.end.y - preview.start.y, preview.end.x - preview.start.x)
- : 0;
-
- if (!preview) return null;
-
- return (
- <>
-
-
-
-
-
-
-
-
- {pointPreviewLength >= 0.01 && (
-
-
-
-
- )}
- >
- );
-}
diff --git a/apps/web-demo/app/lib/engine/render/scene/SceneWalls.tsx b/apps/web-demo/app/lib/engine/render/scene/SceneWalls.tsx
deleted file mode 100644
index 7ac0f2b..0000000
--- a/apps/web-demo/app/lib/engine/render/scene/SceneWalls.tsx
+++ /dev/null
@@ -1,130 +0,0 @@
-"use client";
-
-import { CuboidCollider, RigidBody } from "@react-three/rapier";
-
-import { type GameSceneWall, useSceneStore } from "@pointclick-engine/engine-core";
-import { useSceneEditorStore } from "../../../../store/sceneEditorStore";
-import { computeWallSegments } from "@pointclick-engine/engine-renderer-r3f";
-import { SceneWallPlane } from "@pointclick-engine/engine-renderer-r3f";
-
-export type WallResizeHandle = "x+" | "x-" | "z+" | "z-";
-
-export function SceneWalls({
- debug,
- onStartWallMove,
- onStartWallResize,
-}: {
- debug: boolean;
- onStartWallMove: (index: number, pointX: number, pointZ: number) => void;
- onStartWallResize: (index: number, handle: WallResizeHandle) => void;
-}) {
- const walls = useSceneStore((s) => s.scene.walls);
- const selectedWallIndex = useSceneEditorStore((s) => s.selectedWallIndex);
- const selectWall = useSceneEditorStore((s) => s.selectWall);
-
- return (
- <>
- {walls.map((wall: GameSceneWall, i: number) => {
- const segments = computeWallSegments(wall.halfSize, wall.openings);
- const isSelected = selectedWallIndex === i;
-
- return (
-
- {/* One collider per solid segment → openings have no collision */}
- {segments.map((seg, si) => (
-
- ))}
-
- {debug && (
- <>
- {/* One wireframe mesh per segment — the gaps ARE the openings */}
- {segments.map((seg, si) => (
- {
- e.stopPropagation();
- selectWall(i);
- onStartWallMove(i, e.point.x, e.point.z);
- }}
- >
-
-
-
- ))}
-
- {/* Resize handles — always based on full wall halfSize */}
- {isSelected && (
- <>
- {
- e.stopPropagation();
- onStartWallResize(i, "x+");
- }}
- >
-
-
-
- {
- e.stopPropagation();
- onStartWallResize(i, "x-");
- }}
- >
-
-
-
- {
- e.stopPropagation();
- onStartWallResize(i, "z+");
- }}
- >
-
-
-
- {
- e.stopPropagation();
- onStartWallResize(i, "z-");
- }}
- >
-
-
-
- >
- )}
- >
- )}
-
- );
- })}
-
- {/* Wall texture planes — rendered outside RigidBody, camera-facing */}
- {walls.map((wall: GameSceneWall, i: number) =>
- wall.textureUrl ? (
-
- ) : null,
- )}
- >
- );
-}
diff --git a/apps/web-demo/app/lib/engine/render/sprite/DavidSprite.tsx b/apps/web-demo/app/lib/engine/render/sprite/DavidSprite.tsx
deleted file mode 100644
index a3ce1c9..0000000
--- a/apps/web-demo/app/lib/engine/render/sprite/DavidSprite.tsx
+++ /dev/null
@@ -1,230 +0,0 @@
-"use client";
-
-import { forwardRef, useEffect, useImperativeHandle, useMemo, useRef } from "react";
-import { useFrame, useLoader, useThree } from "@react-three/fiber";
-import {
- ClampToEdgeWrapping,
- FrontSide,
- Mesh,
- MeshBasicMaterial,
- NearestFilter,
- SRGBColorSpace,
- Texture,
- TextureLoader,
-} from "three";
-
-import type { SpriteAnimation } from "./clips";
-
-const SHOULD_LOG_SPRITE_STATE = process.env.NODE_ENV !== "production";
-let spriteInstanceCounter = 0;
-
-function logSpriteState(event: string, payload: Record) {
- if (!SHOULD_LOG_SPRITE_STATE) return;
- if (typeof window !== "undefined") {
- const nextEntry = { scope: "sprite", event, payload, ts: Date.now() };
- const currentTrace = ((window as unknown as { __gameTrace?: unknown[] }).__gameTrace ?? []);
- (window as unknown as { __gameTrace: unknown[] }).__gameTrace = [...currentTrace, nextEntry].slice(-300);
- }
- console.info(`[sprite-state] ${event}`, payload);
-}
-
-type DavidSpriteProps = {
- animation: SpriteAnimation;
- preloadAnimations?: readonly SpriteAnimation[];
- meshRef?: React.RefObject;
- scale?: [number, number, number];
- isPaused?: boolean;
-};
-
-export type DavidSpriteHandle = {
- nextFrame: () => void;
-};
-
-function cloneTexture(sourceTexture: Texture) {
- const clonedTexture = sourceTexture.clone();
- clonedTexture.colorSpace = SRGBColorSpace;
- clonedTexture.magFilter = NearestFilter;
- clonedTexture.minFilter = NearestFilter;
- clonedTexture.wrapS = ClampToEdgeWrapping;
- clonedTexture.wrapT = ClampToEdgeWrapping;
- clonedTexture.generateMipmaps = false;
- clonedTexture.needsUpdate = true;
- return clonedTexture;
-}
-
-const DavidSprite = forwardRef(
- ({ animation, preloadAnimations, meshRef, scale = [2.2, 2.2, 1], isPaused = false }, ref) => {
- const spriteInstanceIdRef = useRef(null);
- if (spriteInstanceIdRef.current == null) {
- spriteInstanceIdRef.current = ++spriteInstanceCounter;
- }
-
- const internalRef = useRef(null);
- const targetRef = meshRef ?? internalRef;
- const materialRef = useRef(null);
- const renderer = useThree((state) => state.gl);
- const preloadedFrames = useMemo(() => {
- if (!preloadAnimations?.length) {
- return null;
- }
-
- const uniqueFrames = new Set();
- preloadAnimations.forEach((clip) => {
- clip.frames.forEach((frame) => {
- uniqueFrames.add(frame);
- });
- });
-
- return Array.from(uniqueFrames);
- }, [preloadAnimations]);
-
- const framesToLoad = preloadedFrames ?? animation.frames;
-
- const sourceTextures = useLoader(TextureLoader, framesToLoad) as unknown as Texture[];
-
- const texturesByFrame = useMemo(() => {
- const byFrame = new Map();
- framesToLoad.forEach((frame, index) => {
- const sourceTexture = sourceTextures[index];
- if (!sourceTexture) return;
- byFrame.set(frame, cloneTexture(sourceTexture));
- });
- return byFrame;
- }, [framesToLoad, sourceTextures]);
-
- const textures = useMemo(
- () =>
- animation.frames
- .map((frame) => texturesByFrame.get(frame))
- .filter((texture): texture is Texture => Boolean(texture)),
- [animation.frames, texturesByFrame],
- );
-
- useEffect(() => {
- const initTexture = (renderer as unknown as { initTexture?: (texture: Texture) => void }).initTexture;
- if (!initTexture) return;
-
- texturesByFrame.forEach((texture) => {
- initTexture(texture);
- });
- }, [renderer, texturesByFrame]);
-
- const frameAspect = useMemo(() => {
- const image = textures[0]?.image as { width?: number; height?: number } | undefined;
- if (!image?.width || !image?.height) {
- return 1;
- }
-
- return image.width / image.height;
- }, [textures]);
- const frameCursorRef = useRef(0);
- const frameTimeRef = useRef(0);
-
- useEffect(() => {
- const instanceId = spriteInstanceIdRef.current;
- logSpriteState("mount", {
- instanceId,
- preloadClipCount: preloadAnimations?.length ?? 1,
- loadedFrameCount: framesToLoad.length,
- });
-
- return () => {
- logSpriteState("unmount", { instanceId });
- };
- }, [framesToLoad.length, preloadAnimations]);
-
- useEffect(() => {
- logSpriteState("animation-change", {
- instanceId: spriteInstanceIdRef.current,
- fps: animation.fps,
- frameCount: animation.frames.length,
- firstFrame: animation.frames[0],
- });
- }, [animation]);
-
- useEffect(() => {
- frameCursorRef.current = 0;
- frameTimeRef.current = 0;
-
- const firstTexture = textures[0];
- const material = materialRef.current;
-
- if (material && firstTexture) {
- material.map = firstTexture;
- material.needsUpdate = true;
- }
- }, [animation, textures]);
-
- useImperativeHandle(
- ref,
- () => ({
- nextFrame: () => {
- if (textures.length <= 1) {
- return;
- }
-
- const clipLength = textures.length;
- frameCursorRef.current = animation.loop ?? true
- ? (frameCursorRef.current + 1) % clipLength
- : Math.min(frameCursorRef.current + 1, clipLength - 1);
-
- const material = materialRef.current;
- const nextTexture = textures[frameCursorRef.current];
-
- if (material && nextTexture) {
- material.map = nextTexture;
- material.needsUpdate = true;
- }
- },
- }),
- [animation.loop, textures],
- );
-
- useFrame((_, delta) => {
- if (isPaused || textures.length <= 1) {
- return;
- }
-
- frameTimeRef.current += delta;
- const stepTime = 1 / animation.fps;
-
- if (frameTimeRef.current < stepTime) {
- return;
- }
-
- const steps = Math.floor(frameTimeRef.current / stepTime);
- frameTimeRef.current -= steps * stepTime;
-
- frameCursorRef.current = animation.loop ?? true
- ? (frameCursorRef.current + steps) % textures.length
- : Math.min(frameCursorRef.current + steps, textures.length - 1);
-
- const material = materialRef.current;
- const nextTexture = textures[frameCursorRef.current];
-
- if (material && nextTexture) {
- material.map = nextTexture;
- material.needsUpdate = true;
- }
- });
-
- const [sx, sy, sz] = scale;
- const meshScale = useMemo<[number, number, number]>(
- () => [animation.flipX ? -Math.abs(sx) : Math.abs(sx), sy, sz],
- [animation.flipX, sx, sy, sz],
- );
- const planeWidth = 2 * frameAspect;
- const planeHeight = 2;
-
- return (
-
-
-
-
- );
- },
-);
-
-DavidSprite.displayName = "DavidSprite";
-
-export default DavidSprite;
diff --git a/apps/web-demo/app/lib/engine/render/sprite/clips.ts b/apps/web-demo/app/lib/engine/render/sprite/clips.ts
deleted file mode 100644
index b9d63ab..0000000
--- a/apps/web-demo/app/lib/engine/render/sprite/clips.ts
+++ /dev/null
@@ -1,72 +0,0 @@
-export type SpriteAnimation = {
- frames: readonly string[];
- fps: number;
- loop?: boolean;
- flipX?: boolean;
-};
-
-export type GameCharacterName = "Dave";
-
-export type GameDirection = "idle" | "north" | "south" | "west" | "east";
-
-type CharacterSprites = Record;
-
-type CharacterGridPosition = {
- name: GameCharacterName;
- column: 0 | 1 | 2;
- row: 0 | 1 | 2;
-};
-
-const DAVE_SPRITE_ROOT = "/assets/sprites/david";
-
-const createFrameUrls = (prefix: string, count: number, startIndex = 1) =>
- Array.from(
- { length: count },
- (_, index) =>
- `${DAVE_SPRITE_ROOT}/${prefix}_${String(startIndex + index).padStart(4, "0")}.png`,
- );
-
-const DAVE_CHARACTER_SPRITES: CharacterSprites = {
- idle: {
- frames: [`${DAVE_SPRITE_ROOT}/david_idle.png`],
- fps: 1,
- loop: true,
- },
- north: {
- frames: createFrameUrls("david-walk-north", 9).slice().reverse(),
- fps: 16,
- loop: true,
- },
- south: {
- frames: createFrameUrls("david-walk-south", 8, 3),
- fps: 16,
- loop: true,
- },
- west: {
- frames: createFrameUrls("david-walk-west", 9).slice().reverse(),
- fps: 16,
- loop: true,
- flipX: true,
- },
- east: {
- frames: createFrameUrls("david-walk-west", 9).slice().reverse(),
- fps: 16,
- loop: true,
- },
-};
-
-export const DAVE_IDLE_SPEAKING: SpriteAnimation = {
- frames: createFrameUrls("david_speaking", 8),
- fps: 8,
- loop: true,
-};
-
-export const GAME_CHARACTERS = [
- { name: "Dave", column: 0, row: 0 },
-] as const satisfies ReadonlyArray;
-
-export const GAME_CHARACTER_SPRITES = Object.fromEntries(
- GAME_CHARACTERS.map((character) => [character.name, DAVE_CHARACTER_SPRITES]),
-) as Record;
-
-export const DAVE_SPRITES = DAVE_CHARACTER_SPRITES;
diff --git a/apps/web-demo/app/lib/engine/render/sprite/speakingAnimation.ts b/apps/web-demo/app/lib/engine/render/sprite/speakingAnimation.ts
deleted file mode 100644
index 2752f47..0000000
--- a/apps/web-demo/app/lib/engine/render/sprite/speakingAnimation.ts
+++ /dev/null
@@ -1,46 +0,0 @@
-import { DAVE_IDLE_SPEAKING, type SpriteAnimation } from "./clips";
-
-const BASE_FRAMES = DAVE_IDLE_SPEAKING.frames;
-const FRAME_COUNT = BASE_FRAMES.length;
-
-/**
- * Builds a varied speaking animation from the base idle-speaking frames.
- *
- * Strategy: generates chunks of 2–3 consecutive frames with 1–2 repetitions
- * each, then jumps to an overlapping or skipped position. The result is a
- * pre-computed frame sequence (~15–20 frames) that loops, giving natural
- * mouth movement without a mechanical cycle.
- *
- * @param seed speechTrigger value — stabilises the pattern for one
- * speech event; different dialogues get different patterns.
- * @param charsPerSecond text reveal speed → drives fps so mouth matches pace.
- */
-export function buildSpeakingAnimation(
- seed: number,
- charsPerSecond: number,
-): SpriteAnimation {
- const result: string[] = [];
- let pos = seed % FRAME_COUNT;
-
- // 6 chunks → roughly 15–20 frames before the loop point
- for (let chunk = 0; chunk < 6; chunk++) {
- const chunkSize = 2 + ((seed * 7 + chunk * 3) % 2); // 2 or 3
- const repeats = 1 + ((seed * 5 + chunk * 11) % 2); // 1 or 2
-
- for (let r = 0; r < repeats; r++) {
- for (let i = 0; i < chunkSize; i++) {
- result.push(BASE_FRAMES[(pos + i) % FRAME_COUNT]);
- }
- }
-
- // Advance by chunkSize + a small irregular offset (1 or 2)
- const jump = chunkSize + 1 + ((seed * 3 + chunk * 7) % 2);
- pos = (pos + jump) % FRAME_COUNT;
- }
-
- // Sync fps to text reveal speed: ~1 mouth move per 4 characters,
- // clamped so it always looks natural regardless of text speed.
- const fps = Math.max(4, Math.min(10, Math.round(charsPerSecond * 0.25)));
-
- return { frames: result, fps, loop: true };
-}
diff --git a/apps/web-demo/app/lib/engine/runtime/demoViewportOptions.ts b/apps/web-demo/app/lib/engine/runtime/demoViewportOptions.ts
new file mode 100644
index 0000000..cf8a485
--- /dev/null
+++ b/apps/web-demo/app/lib/engine/runtime/demoViewportOptions.ts
@@ -0,0 +1,103 @@
+import { npcToHotspot, useDialogStore } from "@pointclick-engine/engine-core";
+import type {
+ DialogUIAdapter,
+ GameRuntimeConfig,
+ GameScene,
+ GameSceneTransition,
+ PlacedSceneItem,
+} from "@pointclick-engine/engine-core";
+import type {
+ GameViewportControllerOptions,
+ SceneProgressStorage,
+} from "@pointclick-engine/engine-renderer-r3f";
+
+import { SCENES, DEFAULT_SCENE_ID } from "../../../../demo-content/scenes/scenes";
+import { ITEMS } from "../../../../demo-content/items";
+import { getRandomPhrase } from "../../../../demo-content/dialogs/getRandomPhrase";
+import { demoDictionaries } from "../../../../demo-content/dialogs";
+import { demoDialogues } from "../../../../demo-content/dialogues/guide";
+import { localStorageAdapter } from "../../platform-web";
+import { webAudioAdapter } from "../../platform-web-audio";
+import { audioSettingsStore } from "../../../store/audio";
+import {
+ loadCurrentSceneId,
+ saveCurrentSceneId,
+ startGamePersistence,
+} from "../../gamePersistence";
+import { DEMO_AUDIO_DEFAULTS } from "./useDemoAudio";
+
+const SCENE_STORAGE: SceneProgressStorage = {
+ loadSceneId: loadCurrentSceneId,
+ saveSceneId: saveCurrentSceneId,
+};
+
+// Transiciones de la demo por id (para el sonido declarativo `triggerSoundUrl`).
+const DEMO_TRANSITIONS: Record = Object.fromEntries(
+ Object.values(SCENES).flatMap((sc) => (sc.transitions ?? []).map((t) => [t.id, t] as const)),
+);
+
+/** En la demo, los items sin `sceneId` (partidas antiguas) cuentan como de personalRoom. */
+const filterDemoPlacedItems = (item: PlacedSceneItem, sceneId: string): boolean =>
+ item.sceneId === sceneId || (item.sceneId === undefined && sceneId === "personalRoom");
+
+/**
+ * La demo mantiene en el store su escena completa (SCENES) y no la proyeccion del registro del
+ * core (`toRuntimeScene`), asi que proyecta ella los NPC a hotspots: `hotspot:interact` los
+ * busca en `scene.hotspots` de la escena activa.
+ */
+function resolveDemoScene(id: string): GameScene | null {
+ const scene = SCENES[id];
+ if (!scene) return null;
+ if (!scene.npcs?.length) return scene;
+ return { ...scene, hotspots: [...(scene.hotspots ?? []), ...scene.npcs.map(npcToHotspot)] };
+}
+
+/** Opciones propias de la demo para `useGameViewportController` (datos y callbacks de su juego). */
+export const DEMO_VIEWPORT_OPTIONS: GameViewportControllerOptions = {
+ initialSceneId: DEFAULT_SCENE_ID,
+ storage: SCENE_STORAGE,
+ // La demo mantiene en el store su escena completa (SCENES), no la proyeccion del registro del core.
+ resolveScene: resolveDemoScene,
+ // Los diccionarios de la demo se registran en su getRandomPhrase.
+ getPhrase: (key) => getRandomPhrase(key),
+ filterPlacedItems: filterDemoPlacedItems,
+ // Guardado automatico de la partida (ya hidratada al importar gamePersistence).
+ startPersistence: startGamePersistence,
+ audio: {
+ port: webAudioAdapter,
+ defaults: DEMO_AUDIO_DEFAULTS,
+ scenes: SCENES,
+ items: ITEMS,
+ transitions: DEMO_TRANSITIONS,
+ settingsStore: audioSettingsStore,
+ },
+};
+
+/**
+ * `dialog:trigger` (y por tanto `say`, `onEnter`, `blocked`...) resuelve el texto en las reglas
+ * del runtime, no en los diccionarios i18n de la demo. Este adaptador muestra el bocadillo con
+ * la frase del diccionario del idioma activo para la clave.
+ */
+const DEMO_DIALOG_ADAPTER: DialogUIAdapter = {
+ show: (text, dialogKey, speaker) =>
+ useDialogStore.getState().show(dialogKey ? getRandomPhrase(dialogKey) : text, dialogKey, speaker),
+ hide: () => useDialogStore.getState().dismiss(),
+};
+
+/** Claves de dialogo de la demo (en cualquier idioma), para que `validateContent` las compruebe. */
+const DEMO_DIALOG_KEYS: ReadonlySet = new Set(
+ Object.values(demoDictionaries).flatMap((dictionary) => Object.keys(dictionary)),
+);
+
+/**
+ * Configuracion de `createGameRuntime` de la demo (la comparten `/`, `/debug` y
+ * `/example-bridge`): contenido, almacenamiento de la partida y puerto de dialogo.
+ */
+export const DEMO_RUNTIME_CONFIG: GameRuntimeConfig = {
+ scenes: Object.values(SCENES),
+ items: Object.values(ITEMS),
+ dialogues: demoDialogues,
+ storage: localStorageAdapter,
+ dialogAdapter: DEMO_DIALOG_ADAPTER,
+ dialogKeys: DEMO_DIALOG_KEYS,
+};
diff --git a/apps/web-demo/app/lib/engine/runtime/useDemoAudio.ts b/apps/web-demo/app/lib/engine/runtime/useDemoAudio.ts
new file mode 100644
index 0000000..415832f
--- /dev/null
+++ b/apps/web-demo/app/lib/engine/runtime/useDemoAudio.ts
@@ -0,0 +1,77 @@
+import { useCallback, useEffect, useRef } from "react";
+
+import {
+ useSceneStore,
+ type AudioDefaultsConfig,
+ type PlayerWalkingState,
+} from "@pointclick-engine/engine-core";
+import { webAudioAdapter } from "../../platform-web-audio";
+import { audioSettingsStore } from "../../../store/audio";
+import { useInventoryStore } from "../../../store/inventoryStore";
+
+/**
+ * Sonidos por defecto de la demo (datos, no lógica). Los sonidos específicos
+ * viven en los datos de cada ítem (`pickupSoundUrl`/`dropSoundUrl`) y de cada
+ * transición (`triggerSoundUrl`).
+ */
+export const DEMO_AUDIO_DEFAULTS: AudioDefaultsConfig = {
+ clickSoundUrl: "/assets/audio/sfx/click.ogg",
+ pickupSoundUrl: "/assets/audio/sfx/pickup-default.ogg",
+ dropSoundUrl: "/assets/audio/sfx/drop-default.ogg",
+ transitionSoundUrl: "/assets/audio/sfx/transition-default.ogg",
+};
+
+/**
+ * Sonidos de UI de la demo: sincroniza los ajustes de audio con el adaptador web y
+ * suena el click de la mochila y el de empezar a caminar. Devuelve el sonido de las
+ * letras del bocadillo.
+ */
+export function useDemoUiSounds() {
+ // Sync audio settings (already hydrated from localStorage at module load)
+ // to the webAudioAdapter on mount AND on every subsequent change. Without
+ // the initial apply the adapter starts at its defaults and ignores any
+ // persisted mute until the user toggles a setting.
+ useEffect(() => {
+ const apply = (state: ReturnType) => {
+ webAudioAdapter.setMuted("master", state.masterMuted);
+ webAudioAdapter.setMuted("music", state.musicMuted);
+ webAudioAdapter.setMuted("sfx", state.sfxMuted);
+ webAudioAdapter.setVolume("master", state.masterVolume);
+ webAudioAdapter.setVolume("music", state.musicVolume);
+ webAudioAdapter.setVolume("sfx", state.sfxVolume);
+ };
+ apply(audioSettingsStore.getState());
+ return audioSettingsStore.subscribe(apply);
+ }, []);
+
+ // Click sound for inventory toggle
+ const isInventoryOpen = useInventoryStore((s) => s.isOpen);
+ useEffect(() => {
+ webAudioAdapter.playSound({
+ id: "click",
+ url: "/assets/audio/sfx/click.ogg",
+ category: "ui",
+ });
+ }, [isInventoryOpen]);
+
+ // Click sound on canvas for pathfinding
+ const playerWalkingState = useSceneStore((s) => s.playerWalkingState);
+ const prevWalkingRef = useRef(null);
+ useEffect(() => {
+ // Play click sound when walking starts (transition from null to walking state)
+ if (playerWalkingState && !prevWalkingRef.current) {
+ webAudioAdapter.playSound({
+ id: "click-canvas",
+ url: "/assets/audio/sfx/click.ogg",
+ category: "ui",
+ });
+ }
+ prevWalkingRef.current = playerWalkingState;
+ }, [playerWalkingState]);
+
+ return useCallback(() => {
+ const n = Math.floor(Math.random() * 4) + 1;
+ const url = `/assets/audio/sfx/speak (${n}).mp3`;
+ webAudioAdapter.playSound({ id: url, url, category: "sfx" }, { volume: 0.35 });
+ }, []);
+}
diff --git a/apps/web-demo/app/lib/engine/runtime/useDemoSceneDebug.ts b/apps/web-demo/app/lib/engine/runtime/useDemoSceneDebug.ts
new file mode 100644
index 0000000..6455beb
--- /dev/null
+++ b/apps/web-demo/app/lib/engine/runtime/useDemoSceneDebug.ts
@@ -0,0 +1,59 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { SCENES } from "../../../../demo-content/scenes/scenes";
+import { useSceneStore } from "@pointclick-engine/engine-core";
+import { getGameRuntime } from "../publicApi";
+
+type StoreSetScene = ReturnType["setScene"];
+
+/**
+ * Selector de escena del panel de debug: opciones y `setScene` con entrada animada.
+ * El estado de escena, la siembra y la persistencia viven en `useGameViewportController`
+ * (renderer); este hook solo recibe su `storeSetScene`.
+ */
+export function useDemoSceneDebug(storeSetScene: StoreSetScene) {
+ const sceneOptions = useMemo(
+ () => Object.values(SCENES).map((s) => ({ label: s.label, value: s.id })),
+ [],
+ );
+
+ const setScene = useMemo(
+ () => (id: string) => {
+ const scene = SCENES[id];
+ if (!scene) {
+ console.warn(`Scene not found: ${id}`);
+ return;
+ }
+ // When changing scene from debug menu, look for a transition to that scene
+ // and use its spawn/target positions for animated entry
+ const currentScene = useSceneStore.getState().scene;
+ const transitionToTarget = currentScene?.transitions?.find((t) => t.targetSceneId === id);
+
+ if (transitionToTarget && "spawnPosition" in transitionToTarget && transitionToTarget.spawnPosition) {
+ // Use transition's spawn position
+ const spawnPos = transitionToTarget.spawnPosition;
+ const targetPos = "targetPosition" in transitionToTarget ? transitionToTarget.targetPosition : undefined;
+
+ storeSetScene(id, scene, spawnPos);
+
+ // Execute walk command if target position exists
+ if (targetPos) {
+ setTimeout(() => {
+ getGameRuntime()?.executeCommand({
+ type: "player:walkTo",
+ position: targetPos,
+ });
+ }, 0);
+ }
+ } else {
+ // No transition found, just change scene normally
+ storeSetScene(id, scene);
+ }
+ },
+ [storeSetScene],
+ );
+
+ return { sceneOptions, setScene };
+}
diff --git a/apps/web-demo/app/lib/engine/runtime/useDoorSystem.ts b/apps/web-demo/app/lib/engine/runtime/useDoorSystem.ts
index 4d5de18..9c90d48 100644
--- a/apps/web-demo/app/lib/engine/runtime/useDoorSystem.ts
+++ b/apps/web-demo/app/lib/engine/runtime/useDoorSystem.ts
@@ -28,11 +28,11 @@ const DOOR_APPROACH_GAP = 1.2;
* inside the demo layer, free to evolve into a first-class engine
* primitive later without breaking the existing rule wiring.
*
- * Returns a handler you can plug into `useInventoryRuntimeController`'s
- * `onRuntimeEvent` prop. Composable: chain it with other handlers if you
+ * Returns a handler you can pass as the viewport controller's
+ * `onRuntimeEvent` option. Composable: chain it with other handlers if you
* already have one.
*/
-export function useDoorSystem({
+export function useDoorEventBridge({
scene,
passthrough,
}: {
@@ -63,21 +63,25 @@ export function useDoorSystem({
[scene, setOpen, passthrough],
);
- /**
- * Click-goal preprocessor for the runtime's click-to-move pipeline.
- *
- * Behavior: for each closed door in the active scene, check whether the
- * click point is past the door's wall from the player's perspective.
- * If so, replace the goal with an "approach point" — a position on the
- * player's side of the wall, aligned with the door, offset by the
- * wall depth + a small gap. This stops the player in front of the
- * locked door instead of routing them around the entire wall.
- *
- * Limitation: assumes axis-aligned walls (rotationY ≈ 0). For rotated
- * walls we currently bail out and return null (use the original goal),
- * so the path may still route around. Generalizing this is a future task.
- */
- const getEffectiveClickGoal = useCallback(
+ return handleRuntimeEvent;
+}
+
+/**
+ * Click-goal preprocessor for the runtime's click-to-move pipeline.
+ *
+ * Behavior: for each closed door in the active scene, check whether the
+ * click point is past the door's wall from the player's perspective.
+ * If so, replace the goal with an "approach point" — a position on the
+ * player's side of the wall, aligned with the door, offset by the
+ * wall depth + a small gap. This stops the player in front of the
+ * locked door instead of routing them around the entire wall.
+ *
+ * Limitation: assumes axis-aligned walls (rotationY ≈ 0). For rotated
+ * walls we currently bail out and return null (use the original goal),
+ * so the path may still route around. Generalizing this is a future task.
+ */
+export function useDoorClickGoal(scene: Scene | undefined) {
+ return useCallback(
(clickX: number, clickZ: number, playerX: number, playerZ: number) => {
const doors = scene?.doors;
const walls = scene?.walls;
@@ -116,6 +120,17 @@ export function useDoorSystem({
},
[scene],
);
+}
+/** Puente de eventos + preprocesador de click en un solo hook (uso conjunto). */
+export function useDoorSystem({
+ scene,
+ passthrough,
+}: {
+ scene: Scene | undefined;
+ passthrough?: (event: RuntimeEvent) => void;
+}) {
+ const handleRuntimeEvent = useDoorEventBridge({ scene, passthrough });
+ const getEffectiveClickGoal = useDoorClickGoal(scene);
return { handleRuntimeEvent, getEffectiveClickGoal };
}
diff --git a/apps/web-demo/app/lib/engine/runtime/useInventoryRuntimeController.ts b/apps/web-demo/app/lib/engine/runtime/useInventoryRuntimeController.ts
deleted file mode 100644
index d1131e4..0000000
--- a/apps/web-demo/app/lib/engine/runtime/useInventoryRuntimeController.ts
+++ /dev/null
@@ -1,564 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useRef, useState } from "react";
-
-import { getRandomPhrase } from "../../../../demo-content/dialogs/getRandomPhrase";
-import { getGameRuntime } from "../publicApi";
-import { browserEnvironmentAdapter } from "../../platform-web";
-import type { SceneInteraction } from "../../../../demo-content/scenes/scenes";
-import type { PlacedSceneItem } from "@pointclick-engine/engine-core";
-import { useProximityHintController } from "./useProximityHintController";
-import {
- emitRuntimeEvent,
- type RuntimeEventHandler,
-} from "@pointclick-engine/engine-core";
-import { useDialogStore } from "../../../store/dialogStore";
-import { useInventoryStore } from "../../../store/inventoryStore";
-import { usePlacedItemsStore } from "../../../store/placedItemsStore";
-import {
- addOneToInventory,
- inventoryRuleMessages,
- removeOneFromSlot,
- resolveInventoryDropHitDecision,
- resolveInventoryDropMissDialogKey,
- resolveInventoryDropOnPlayerMessage,
- resolvePickupPlacedItemDecision,
-} from "../../core/rules/inventoryRules";
-
-type InventoryStack = {
- id: string;
- name: string;
- spriteUrl: string;
- quantity: number;
-};
-
-type InventorySlots = Array;
-
-type DraggedInventoryPayload = {
- stack: InventoryStack;
- fromSlotIndex: number;
-};
-
-type RuntimeDraggedStack = DraggedInventoryPayload & {
- pointerX: number;
- pointerY: number;
-};
-
-function createInitialInventorySlots(): InventorySlots {
- return Array.from({ length: 9 }, (_, index) => {
- if (index === 0) {
- return {
- id: "gameboy",
- name: "Gameboy",
- spriteUrl: "/assets/gameboy/gameboy.png",
- quantity: 1,
- };
- }
- if (index === 1) {
- // Gold key seeded so the player can immediately test the dungeon door
- // pipeline. Once items can be picked up from scene placements, this
- // seed should be removed and the key dropped into a scene instead.
- return {
- id: "gold-key",
- name: "Llave dorada",
- spriteUrl: "/assets/key/gold-key.png",
- quantity: 1,
- };
- }
- return null;
- });
-}
-
-function createInitialPlacedItems(sceneId: string): PlacedSceneItem[] {
- return [
- {
- id: "trophy-ground",
- itemId: "trophy",
- interactionId: "trophy-ground-pickup",
- name: "Trophy",
- spriteUrl: "/assets/trophy/trophy.png",
- worldPosition: [5.5, -1.3, 22.0],
- canPickup: true,
- hasCollision: true,
- collisionHalfSize: [0.5, 0.8, 0.5],
- sceneId, // Track which scene this item belongs to
- // No dialog keys for ground pickup - will use defaults from resolvePickupPlacedItemDecision
- },
- ];
-}
-
-export function useInventoryRuntimeController({
- sceneId,
- sceneInteractions,
- playerPosition,
- onRuntimeEvent,
-}: {
- sceneId: string;
- sceneInteractions: SceneInteraction[];
- playerPosition: [number, number, number];
- onRuntimeEvent?: RuntimeEventHandler;
-}) {
- // Dialog state now lives in dialogStore (wirable via dialog:trigger / dialog:dismiss commands)
- const showDialog = useDialogStore((s) => s.show);
- const dismissDialog = useDialogStore((s) => s.dismiss);
-
- // Inventory visibility now lives in inventoryStore (wirable via inventory:toggle command)
- const isInventoryOpen = useInventoryStore((s) => s.isOpen);
-
- const [inventorySlots, setInventorySlots] = useState(() => {
- // Try to load from localStorage
- if (typeof window !== "undefined") {
- const saved = localStorage.getItem("inventory-slots");
- if (saved) {
- try {
- return JSON.parse(saved);
- } catch {
- // Fall back to initial if parse fails
- }
- }
- }
- return createInitialInventorySlots();
- });
- const [draggedStack, setDraggedStack] = useState(
- null,
- );
- const [placedItems, setPlacedItems] = useState([]);
- const pickupLockRef = useRef>(new Set());
- const inventorySlotsRef = useRef(inventorySlots);
- const setPlacedItemsInStore = usePlacedItemsStore((s) => s.setItems);
-
- // Keep ref in sync with current state (avoids stale closure in callbacks)
- useEffect(() => {
- inventorySlotsRef.current = inventorySlots;
- });
-
- // Persist inventory slots to localStorage whenever they change
- useEffect(() => {
- localStorage.setItem("inventory-slots", JSON.stringify(inventorySlots));
- }, [inventorySlots]);
-
- useEffect(() => {
- if (pickupLockRef.current.size === 0) {
- return;
- }
-
- for (const lockedItemId of Array.from(pickupLockRef.current)) {
- const stillExists = placedItems.some((item) => item.id === lockedItemId);
- if (!stillExists) {
- pickupLockRef.current.delete(lockedItemId);
- }
- }
- }, [placedItems]);
-
- // Manage placed items: maintain all items in state (persisted to store)
- useEffect(() => {
- const { items: storedItems, initialItemsCreated } = usePlacedItemsStore.getState();
-
- setPlacedItems((prev) => {
- // Start with all stored items (already persisted in localStorage)
- const allItems = storedItems.length > 0 ? storedItems : prev;
-
- // For personalRoom, create initial spawn items only once per session
- // Only create if the item doesn't exist in ANY scene (not just this one)
- if (sceneId === "personalRoom" && !initialItemsCreated) {
- const trophyTakenOrMovedElsewhere = allItems.some((i) => i.itemId === "trophy");
- // Only recreate the trophy if it has never left this room
- // If it exists anywhere, assume it was taken/moved by the player
- if (!trophyTakenOrMovedElsewhere) {
- return [...allItems, ...createInitialPlacedItems(sceneId)];
- }
- }
-
- return allItems;
- });
-
- // Mark initial items as created AFTER setState
- if (sceneId === "personalRoom" && !initialItemsCreated) {
- usePlacedItemsStore.getState().markInitialItemsCreated();
- }
- }, [sceneId]);
-
- // Sync all placed items to localStorage via store
- useEffect(() => {
- setPlacedItemsInStore(placedItems);
- }, [placedItems, setPlacedItemsInStore]);
-
- const handleBoundaryHit = useCallback(
- (phrase: string) => {
- showDialog(phrase, "boundaryHit");
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDialog",
- source: "boundary",
- text: phrase,
- dialogKey: "boundaryHit",
- });
- },
- [onRuntimeEvent, showDialog],
- );
-
- const showSpeechBubble = useCallback(
- (
- nextText: string,
- meta?: { source?: "inventory" | "debug"; dialogKey?: string },
- ) => {
- showDialog(nextText, meta?.dialogKey);
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDialog",
- source: meta?.source ?? "inventory",
- text: nextText,
- dialogKey: meta?.dialogKey,
- });
- },
- [onRuntimeEvent, showDialog],
- );
-
- const hideSpeechBubble = useCallback(() => {
- dismissDialog();
- }, [dismissDialog]);
-
- const handleInventoryDropHit = useCallback(
- (interaction: SceneInteraction, payload: DraggedInventoryPayload) => {
- const decision = resolveInventoryDropHitDecision({
- interaction,
- payload,
- now: Date.now(),
- });
-
- if (decision.kind === "unknown-item") {
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "unknown-item",
- itemId: payload.stack.id,
- interactionId: interaction.id,
- });
- showSpeechBubble(decision.message);
- setDraggedStack(null);
- return;
- }
-
- if (decision.kind === "rule-miss") {
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "rule-miss",
- itemId: payload.stack.id,
- interactionId: interaction.id,
- });
- showSpeechBubble(getRandomPhrase(decision.dialogKey), {
- dialogKey: decision.dialogKey,
- });
- setDraggedStack(null);
- return;
- }
-
- if (decision.kind === "place") {
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "place",
- itemId: payload.stack.id,
- interactionId: interaction.id,
- });
- setInventorySlots((currentSlots) =>
- removeOneFromSlot(currentSlots, decision.fromSlotIndex),
- );
- setPlacedItems((currentPlaced) => [
- ...currentPlaced,
- { ...decision.placedItem, sceneId }, // Add sceneId to track which scene this item belongs to
- ]);
- showSpeechBubble(getRandomPhrase(decision.dialogKey), {
- dialogKey: decision.dialogKey,
- });
- setDraggedStack(null);
- return;
- }
-
- if (decision.kind === "consume") {
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "consume",
- itemId: payload.stack.id,
- interactionId: interaction.id,
- });
- setInventorySlots((currentSlots) =>
- removeOneFromSlot(currentSlots, decision.fromSlotIndex),
- );
- showSpeechBubble(getRandomPhrase(decision.dialogKey), {
- dialogKey: decision.dialogKey,
- });
- setDraggedStack(null);
- return;
- }
-
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "return",
- itemId: payload.stack.id,
- interactionId: interaction.id,
- });
- showSpeechBubble(getRandomPhrase(decision.dialogKey), {
- dialogKey: decision.dialogKey,
- });
- setDraggedStack(null);
- },
- [onRuntimeEvent, showSpeechBubble],
- );
-
- const handleInventoryDropMiss = useCallback(
- (payload: DraggedInventoryPayload, interaction?: SceneInteraction) => {
- const fallbackMiss = resolveInventoryDropMissDialogKey({
- payload,
- interaction,
- sceneInteractions,
- });
-
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "return",
- itemId: payload.stack.id,
- interactionId: interaction?.id,
- });
- showSpeechBubble(getRandomPhrase(fallbackMiss), {
- dialogKey: fallbackMiss,
- });
- setDraggedStack(null);
- },
- [onRuntimeEvent, sceneInteractions, showSpeechBubble],
- );
-
- const handleInventoryDropOnPlayer = useCallback(
- (payload: DraggedInventoryPayload) => {
- const message = resolveInventoryDropOnPlayerMessage({ payload });
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "on-player",
- itemId: payload.stack.id,
- });
- if (message.kind === "dialog-key") {
- showSpeechBubble(getRandomPhrase(message.dialogKey), {
- dialogKey: message.dialogKey,
- });
- } else {
- showSpeechBubble(message.text);
- }
-
- setDraggedStack(null);
- },
- [onRuntimeEvent, showSpeechBubble],
- );
-
- const handlePickupPlacedItem = useCallback(
- (placedItem: PlacedSceneItem) => {
- if (isInventoryOpen) {
- return;
- }
-
- if (pickupLockRef.current.has(placedItem.id)) {
- return;
- }
-
- pickupLockRef.current.add(placedItem.id);
-
- const decision = resolvePickupPlacedItemDecision({ placedItem });
- if (decision.kind === "ignore") {
- pickupLockRef.current.delete(placedItem.id);
- return;
- }
-
- if (decision.kind === "blocked") {
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "pickup-blocked",
- itemId: placedItem.itemId,
- interactionId: placedItem.interactionId,
- });
- showSpeechBubble(getRandomPhrase(decision.dialogKey), {
- dialogKey: decision.dialogKey,
- });
- pickupLockRef.current.delete(placedItem.id);
- return;
- }
-
- // Try to add to inventory first, but don't apply state changes yet
- const inventoryResult = addOneToInventory(
- inventorySlotsRef.current,
- decision.stack,
- );
-
- if (!inventoryResult.added) {
- showSpeechBubble(inventoryRuleMessages.inventoryFull);
- pickupLockRef.current.delete(placedItem.id);
- return;
- }
-
- // If we get here, inventory has space. Apply both changes atomically:
- // 1. Update inventory
- setInventorySlots(inventoryResult.slots);
-
- // 2. Remove from placed items
- setPlacedItems((currentPlaced) =>
- currentPlaced.filter(
- (currentItem) => currentItem.id !== decision.placedItemId,
- ),
- );
-
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "pickup-success",
- itemId: placedItem.itemId,
- interactionId: placedItem.interactionId,
- });
- showSpeechBubble(getRandomPhrase(decision.successDialogKey));
- },
- [isInventoryOpen, onRuntimeEvent, showSpeechBubble],
- );
-
- const updatePlacedItemPosition = useCallback(
- (id: string, axis: 0 | 1 | 2, value: number) => {
- setPlacedItems((currentPlaced) =>
- currentPlaced.map((item) => {
- if (item.id !== id) return item;
- const worldPosition = [...item.worldPosition] as [
- number,
- number,
- number,
- ];
- worldPosition[axis] = value;
- return { ...item, worldPosition };
- }),
- );
- },
- [],
- );
-
- const movePlacedItemToPlayer = useCallback(
- (id: string) => {
- setPlacedItems((currentPlaced) =>
- currentPlaced.map((item) => {
- if (item.id !== id) return item;
- return {
- ...item,
- worldPosition: [
- playerPosition[0],
- item.worldPosition[1],
- playerPosition[2],
- ],
- };
- }),
- );
- },
- [playerPosition],
- );
-
- const removePlacedItemById = useCallback((id: string) => {
- setPlacedItems((currentPlaced) =>
- currentPlaced.filter((item) => item.id !== id),
- );
- }, []);
-
- const handleStartInventoryDrag = useCallback(
- (slotIndex: number, clientX: number, clientY: number) => {
- const stack = inventorySlots[slotIndex];
- if (!stack) return;
-
- useInventoryStore.getState().close();
- setDraggedStack({
- stack,
- fromSlotIndex: slotIndex,
- pointerX: clientX,
- pointerY: clientY,
- });
- },
- [inventorySlots],
- );
-
- const handleInteractionInspect = useCallback(
- (interaction: SceneInteraction) => {
- if (!interaction.hintDialogKeys) return;
-
- // Si hay un ítem colocado que puede recogerse, no disparamos el hint:
- // el click será gestionado por el sistema de pickup, no por el de pistas.
- const hasPickableItem = placedItems.some(
- (item) => item.interactionId === interaction.id && item.canPickup,
- );
- if (hasPickableItem) return;
-
- const isOccupied = placedItems.some(
- (item) => item.interactionId === interaction.id,
- );
- const dialogKey = isOccupied
- ? interaction.hintDialogKeys.occupied
- : interaction.hintDialogKeys.empty;
-
- showSpeechBubble(getRandomPhrase(dialogKey), { dialogKey });
- },
- [placedItems, showSpeechBubble],
- );
-
- useProximityHintController({
- playerPosition,
- interactions: sceneInteractions,
- placedItems,
- showSpeechBubble,
- });
-
- useEffect(() => {
- if (sceneId !== "personalRoom") return;
-
- // Double-rAF: el speech inicial dispara DESPUÉS de que R3F haya corrido
- // al menos un useFrame. setTimeout(0) se ejecutaba antes del primer
- // requestAnimationFrame, dejando el sprite en SPRITE_MIN_SCALE sin que
- // useFrame hubiera corregido aún la escala por profundidad.
- let outerHandle: number | null = null;
- let innerHandle: number | null = null;
-
- outerHandle = browserEnvironmentAdapter.requestAnimationFrame(() => {
- outerHandle = null;
- innerHandle = browserEnvironmentAdapter.requestAnimationFrame(() => {
- innerHandle = null;
- showSpeechBubble(getRandomPhrase("personalRoomWelcome"), {
- dialogKey: "personalRoomWelcome",
- });
- });
- });
-
- return () => {
- if (outerHandle !== null) browserEnvironmentAdapter.cancelAnimationFrame(outerHandle);
- if (innerHandle !== null) browserEnvironmentAdapter.cancelAnimationFrame(innerHandle);
- };
- }, [sceneId, showSpeechBubble]);
-
- const handleItemInteract = useCallback(
- (item: PlacedSceneItem) => {
- // Emit item interaction event — useTransitionSystem listens for this
- // to check if there's a matching transition
- emitRuntimeEvent(onRuntimeEvent, {
- type: "onDrop",
- outcome: "item-interact",
- itemId: item.itemId,
- interactionId: item.interactionId,
- });
- },
- [onRuntimeEvent],
- );
-
- return {
- // Note: speechText, speechVisible, speechTrigger are now in dialogStore
- // Note: isInventoryOpen is now in inventoryStore
- isInventoryOpen,
- inventorySlots,
- draggedStack,
- placedItems,
- handleBoundaryHit,
- showSpeechBubble,
- hideSpeechBubble,
- handleInteractionInspect,
- handleInventoryDropHit,
- handleInventoryDropMiss,
- handleInventoryDropOnPlayer,
- handlePickupPlacedItem,
- updatePlacedItemPosition,
- movePlacedItemToPlayer,
- removePlacedItemById,
- handleStartInventoryDrag,
- handleItemInteract,
- };
-}
diff --git a/apps/web-demo/app/lib/engine/runtime/useSceneRuntimeController.ts b/apps/web-demo/app/lib/engine/runtime/useSceneRuntimeController.ts
deleted file mode 100644
index 43c923e..0000000
--- a/apps/web-demo/app/lib/engine/runtime/useSceneRuntimeController.ts
+++ /dev/null
@@ -1,106 +0,0 @@
-"use client";
-
-import { useEffect, useMemo } from "react";
-
-import { SCENES, DEFAULT_SCENE_ID } from "../../../../demo-content/scenes/scenes";
-import { useSceneStore, type GameScene } from "@pointclick-engine/engine-core";
-import { getGameRuntime } from "../publicApi";
-
-export function useSceneRuntimeController() {
- const sceneId = useSceneStore((s) => s.sceneId);
- const sceneBackground = useSceneStore((s) => s.scene.background);
- const storeSetScene = useSceneStore((s) => s.setScene);
- const sceneInteractions = useSceneStore((s) => s.scene.interactions);
- const requestRespawn = useSceneStore((s) => s.requestRespawn);
- const playerPosition = useSceneStore((s) => s.playerPosition);
- const scenePlayerSpawn = useSceneStore((s) => s.scene.playerSpawn);
- const updateInteraction = useSceneStore((s) => s.updateInteraction);
- const resetInteractionsFromSceneConfig = useSceneStore(
- (s) => s.resetInteractionsFromSceneConfig,
- );
-
- const sceneOptions = useMemo(
- () => Object.values(SCENES).map((s) => ({ label: s.label, value: s.id })),
- [],
- );
-
- const setScene = useMemo(
- () => (id: string) => {
- const scene = SCENES[id];
- if (!scene) {
- console.warn(`Scene not found: ${id}`);
- return;
- }
- // When changing scene from debug menu, look for a transition to that scene
- // and use its spawn/target positions for animated entry
- const currentScene = useSceneStore.getState().scene;
- const transitionToTarget = currentScene?.transitions?.find((t) => t.targetSceneId === id);
-
- if (transitionToTarget && "spawnPosition" in transitionToTarget && transitionToTarget.spawnPosition) {
- // Use transition's spawn position
- const spawnPos = transitionToTarget.spawnPosition;
- const targetPos = "targetPosition" in transitionToTarget ? transitionToTarget.targetPosition : undefined;
-
- storeSetScene(id, scene as GameScene, spawnPos);
-
- // Execute walk command if target position exists
- if (targetPos) {
- setTimeout(() => {
- getGameRuntime()?.executeCommand({
- type: "player:walkTo",
- position: targetPos,
- });
- }, 0);
- }
- } else {
- // No transition found, just change scene normally
- storeSetScene(id, scene as GameScene);
- }
- },
- [storeSetScene],
- );
-
- // Load default scene on mount if the store is empty (engine-core store
- // is agnostic and starts blank — the demo is responsible for seeding it).
- // Try to load last visited scene from localStorage, fallback to default.
- useEffect(() => {
- if (!useSceneStore.getState().sceneId) {
- // Try to load from localStorage
- const savedSceneId =
- typeof window !== "undefined" ? localStorage.getItem("current-scene-id") : null;
- const initialSceneId = savedSceneId || DEFAULT_SCENE_ID;
- const initialScene = SCENES[initialSceneId];
-
- if (initialScene) {
- storeSetScene(initialSceneId, initialScene as GameScene);
- } else {
- // Fallback to default if saved scene doesn't exist
- const defaultScene = SCENES[DEFAULT_SCENE_ID];
- if (defaultScene) {
- storeSetScene(DEFAULT_SCENE_ID, defaultScene as GameScene);
- }
- }
- }
- // eslint-disable-next-line react-hooks/exhaustive-deps
- }, []);
-
- // Persist current scene to localStorage whenever it changes
- useEffect(() => {
- if (sceneId) {
- localStorage.setItem("current-scene-id", sceneId);
- }
- }, [sceneId]);
-
- return {
- sceneId,
- sceneBackground,
- setScene,
- sceneInteractions,
- requestRespawn,
- playerPosition,
- scenePlayerSpawn,
- updateInteraction,
- resetInteractionsFromSceneConfig,
- sceneOptions,
- };
-}
diff --git a/apps/web-demo/app/lib/engine/runtime/useTransitionSystem.ts b/apps/web-demo/app/lib/engine/runtime/useTransitionSystem.ts
deleted file mode 100644
index e8371b6..0000000
--- a/apps/web-demo/app/lib/engine/runtime/useTransitionSystem.ts
+++ /dev/null
@@ -1,196 +0,0 @@
-"use client";
-
-import { useCallback, useEffect, useRef } from "react";
-import { useSceneStore } from "@pointclick-engine/engine-core";
-import { resolveTransitionFromItemDrop, resolveTransitionFromItemInteraction } from "@pointclick-engine/engine-core";
-import { getGameRuntime } from "../publicApi";
-import { useDialogStore } from "../../../store/dialogStore";
-import { usePlacedItemsStore } from "../../../store/placedItemsStore";
-import { getRandomPhrase } from "../../../../demo-content/dialogs/getRandomPhrase";
-import { preloadSceneBackground } from "../../../components/scene/SceneBackgroundPlane";
-import type { RuntimeEvent, GameScene } from "@pointclick-engine/engine-core";
-
-/**
- * Wires scene transitions into the demo.
- *
- * Handles:
- * - Collision-based transitions (via `handleTransitionTriggered` callback)
- * - Item-drop-based transitions (by watching `item:dropped` events)
- *
- * Scene changes are applied directly via sceneStore for demo compatibility
- * (scenes are defined in SCENES, not registered via createGameRuntime).
- */
-export interface UseTransitionSystemOpts {
- onBeforeChange?: () => void;
- /** Resuelve el objeto de escena completo por ID. Usado para validación y precarga de fondo. */
- resolveScene?: (sceneId: string) => GameScene | null;
-}
-
-export function useTransitionSystem(opts?: UseTransitionSystemOpts) {
- const storeSetScene = useSceneStore((s) => s.setScene);
- const placedItems = usePlacedItemsStore((s) => s.items);
- const isTransitioningRef = useRef(false);
- const showDialog = useDialogStore((s) => s.show);
- const dialogVisible = useDialogStore((s) => s.visible);
- const pendingTransitionRef = useRef<{ id: string; targetSceneId: string } | null>(null);
- const optsRef = useRef(opts);
- useEffect(() => { optsRef.current = opts; });
-
- const changeScene = useCallback(
- (targetSceneId: string, transitionId: string) => {
- if (isTransitioningRef.current) return;
- isTransitioningRef.current = true;
-
- // Emit transition:started via runtime bus (if runtime is active)
- getGameRuntime()?.emit({
- type: "transition:started",
- transitionId,
- });
-
- // Notify caller synchronously so it can show the curtain overlay before
- // any state update causes a re-render with the new (backgroundless) scene.
- optsRef.current?.onBeforeChange?.();
-
- const fromSceneId = useSceneStore.getState().sceneId;
- const fromScene = useSceneStore.getState().scene;
-
- // Find the transition that was used to trigger this scene change
- const usedTransition = fromScene.transitions?.find((t) => t.id === transitionId);
-
- // Change scene first with optional custom spawn position
- const spawnPos = usedTransition && "spawnPosition" in usedTransition ? usedTransition.spawnPosition : undefined;
- const resolvedScene = optsRef.current?.resolveScene?.(targetSceneId) ?? null;
- storeSetScene(targetSceneId, resolvedScene as Parameters[1], spawnPos);
-
- // Then emit walk command in the new scene with correct pathfinding context
- if (usedTransition && "targetPosition" in usedTransition && usedTransition.targetPosition) {
- const targetPos = usedTransition.targetPosition;
- // console.log(`[useTransitionSystem] Emitting walkTo to ${JSON.stringify(targetPos)}`);
- // Emit walk command via runtime
- getGameRuntime()?.executeCommand({
- type: "player:walkTo",
- position: targetPos,
- });
- } else {
- // console.log(`[useTransitionSystem] No targetPosition found on transition`, usedTransition);
- }
-
- getGameRuntime()?.emit({
- type: "transition:completed",
- fromSceneId,
- toSceneId: targetSceneId,
- });
-
- // Reset guard after a brief delay so re-entering the same zone works
- setTimeout(() => {
- isTransitioningRef.current = false;
- }, 800);
- },
- [storeSetScene],
- );
-
- /** Called by SceneTransitions renderer when player enters a collision zone. */
- const handleTransitionTriggered = useCallback(
- (transitionId: string, targetSceneId: string) => {
- const currentSceneId = useSceneStore.getState().sceneId;
- const currentScene = useSceneStore.getState().scene;
- const transition = currentScene.transitions?.find((t) => t.id === transitionId);
-
- if (!transition) {
- console.warn(`[transition] transition not found: ${transitionId}`);
- return;
- }
-
- // Special case: leaving personalRoom requires having taken the trophy
- // The trophy must not be placed in personalRoom (can be in inventory or another room)
- if (currentSceneId === "personalRoom" && targetSceneId === "dungeon") {
- const trophyStillInRoom = placedItems.some(
- (item) => item.itemId === "trophy" && item.sceneId === "personalRoom",
- );
-
- console.log("[transition-debug] personalRoom exit check:", {
- allPlacedItems: placedItems.map((i) => ({ id: i.id, itemId: i.itemId, sceneId: i.sceneId })),
- trophyStillInRoom,
- });
-
- if (trophyStillInRoom) {
- showDialog(
- "Sería mejor recoger todo lo que pueda del cuarto antes de irme...",
- "interaction.trophy-pedestal.empty",
- );
- return;
- }
- }
-
- // Preload the target scene background so it's in browser cache when we switch.
- const targetBg = optsRef.current?.resolveScene?.(targetSceneId)?.background;
- if (targetBg) preloadSceneBackground(targetBg);
-
- getGameRuntime()?.emit({
- type: "transition:triggered",
- transitionId,
- targetSceneId,
- });
- changeScene(targetSceneId, transitionId);
- },
- [changeScene, showDialog, placedItems],
- );
-
- /**
- * Handles item-drop and item-interact events from the inventory system.
- * Returns a passthrough handler that checks if the drop/interact matches a transition.
- * Defers the scene change until the dialog is dismissed.
- */
- const wrapRuntimeEventForTransitions = useCallback(
- (passthrough: (event: RuntimeEvent) => void) =>
- (event: RuntimeEvent) => {
- const scene = useSceneStore.getState().scene;
-
- if (event.type === "onDrop" && (event.outcome === "consume" || event.outcome === "place") && event.interactionId) {
- const gameEvent = {
- type: "item:dropped" as const,
- itemId: event.itemId,
- outcome: event.outcome as "consume" | "place",
- interactionId: event.interactionId,
- };
- const matching = resolveTransitionFromItemDrop(scene, gameEvent);
- if (matching) {
- getGameRuntime()?.emit({
- type: "transition:triggered",
- transitionId: matching.id,
- targetSceneId: matching.targetSceneId,
- });
- // Store transition to trigger after dialog closes
- pendingTransitionRef.current = { id: matching.id, targetSceneId: matching.targetSceneId };
- }
- }
-
- if (event.type === "onDrop" && event.outcome === "item-interact" && event.interactionId) {
- const matching = resolveTransitionFromItemInteraction(scene, event.itemId, event.interactionId);
- if (matching) {
- getGameRuntime()?.emit({
- type: "transition:triggered",
- transitionId: matching.id,
- targetSceneId: (matching as any).targetSceneId,
- });
- // Store transition to trigger after dialog closes
- pendingTransitionRef.current = { id: matching.id, targetSceneId: (matching as any).targetSceneId };
- }
- }
-
- passthrough(event);
- },
- [],
- );
-
- // Execute pending transition after dialog is dismissed
- useEffect(() => {
- if (!dialogVisible && pendingTransitionRef.current) {
- const t = pendingTransitionRef.current;
- pendingTransitionRef.current = null;
- changeScene(t.targetSceneId, t.id);
- }
- }, [dialogVisible, changeScene]);
-
- return { handleTransitionTriggered, wrapRuntimeEventForTransitions };
-}
diff --git a/apps/web-demo/app/lib/gamePersistence.ts b/apps/web-demo/app/lib/gamePersistence.ts
new file mode 100644
index 0000000..55aa74f
--- /dev/null
+++ b/apps/web-demo/app/lib/gamePersistence.ts
@@ -0,0 +1,282 @@
+/**
+ * gamePersistence – Punto único de acceso al guardado del progreso de la demo.
+ *
+ * Toda la partida vive en UNA instantánea (`GameSnapshot`, clave `pointclick-save`)
+ * que escribe el comando `game:save` del core. Lo propio de la demo, las puertas, va en
+ * `snapshot.extra`:
+ *
+ * extra = { doors: { "": true | false, ... } }
+ *
+ * Las partidas con el formato de 0.5.0 (cuatro claves sueltas: `inventory-slots`,
+ * `current-scene-id`, `placed-items-state`, `door-states`) se migran al arrancar con
+ * `migrateLegacySave` y las claves antiguas se borran.
+ *
+ * Todos los accesos pasan por `localStorageAdapter` (fallback seguro en SSR).
+ */
+
+import {
+ clearSave,
+ getGameRuntime,
+ loadGame,
+ migrateLegacySave,
+ resetGameState,
+ saveGame,
+ SAVE_STORAGE_KEY,
+ useInventoryStateStore,
+ usePlacedItemsStateStore,
+ useSceneStore,
+ useWorldStateStore,
+ type GameSnapshot,
+ type InventorySlotsState,
+} from "@pointclick-engine/engine-core";
+
+import { DEFAULT_SCENE_ID } from "../../demo-content/scenes/scenes";
+import { useDoorStore } from "../store/doorStore";
+import { localStorageAdapter } from "./platform-web";
+
+// ============================================================================
+// Claves antiguas (formato 0.5.0): solo se leen para migrar y se borran
+// ============================================================================
+
+export const LEGACY_GAME_STORAGE_KEYS = {
+ inventorySlots: "inventory-slots",
+ currentSceneId: "current-scene-id",
+ doorStates: "door-states",
+ placedItems: "placed-items-state",
+} as const;
+
+const LEGACY_KEYS: string[] = Object.values(LEGACY_GAME_STORAGE_KEYS);
+
+/** Escena que sembraba el antiguo flag `initialItemsCreated` de las partidas guardadas. */
+export const LEGACY_SEEDED_SCENE_ID = "personalRoom";
+
+/** Inventario de una partida nueva: gameboy y llave dorada (para probar la puerta de la mazmorra). */
+export function createInitialInventorySlots(): InventorySlotsState {
+ return Array.from({ length: 9 }, (_, index) => {
+ if (index === 0) {
+ return {
+ id: "gameboy",
+ name: "Gameboy",
+ spriteUrl: "/assets/gameboy/gameboy.png",
+ quantity: 1,
+ };
+ }
+ if (index === 1) {
+ return {
+ id: "gold-key",
+ name: "Llave dorada",
+ spriteUrl: "/assets/key/gold-key.png",
+ quantity: 1,
+ };
+ }
+ return null;
+ });
+}
+
+// ============================================================================
+// Puertas: el estado vive en `extra`, no en su propia clave
+// ============================================================================
+
+const DOORS_EXTRA_KEY = "doors";
+
+type DoorStates = Record;
+
+function isDoorStates(value: unknown): value is DoorStates {
+ return (
+ typeof value === "object" &&
+ value !== null &&
+ !Array.isArray(value) &&
+ Object.values(value).every((v) => typeof v === "boolean")
+ );
+}
+
+function readDoors(snapshot: GameSnapshot | null): DoorStates {
+ const doors = snapshot?.extra?.[DOORS_EXTRA_KEY];
+ return isDoorStates(doors) ? { ...doors } : {};
+}
+
+// ============================================================================
+// Lectura: instantánea nueva o migración de las claves antiguas
+// ============================================================================
+
+function removeLegacyKeys(): void {
+ for (const key of LEGACY_KEYS) localStorageAdapter.removeItem(key);
+}
+
+/** Migra las claves de 0.5.0 a la instantánea nueva, la escribe y borra las antiguas. */
+function migrateLegacy(): GameSnapshot | null {
+ const hadInventory = localStorageAdapter.getItem(LEGACY_GAME_STORAGE_KEYS.inventorySlots) !== null;
+ const snapshot = migrateLegacySave(localStorageAdapter, {
+ legacySeededSceneId: LEGACY_SEEDED_SCENE_ID,
+ defaultSceneId: DEFAULT_SCENE_ID,
+ extraKeys: [LEGACY_GAME_STORAGE_KEYS.doorStates],
+ });
+ if (!snapshot) return null;
+
+ // Sin inventario guardado, la partida antigua arrancaba con el inventario inicial.
+ if (!hadInventory) snapshot.inventory = createInitialInventorySlots();
+
+ // `door-states` era un envoltorio zustand `{ state: { doorOpenStates }, version }`.
+ const legacyDoors = snapshot.extra?.[LEGACY_GAME_STORAGE_KEYS.doorStates] as
+ | { state?: { doorOpenStates?: unknown } }
+ | undefined;
+ delete snapshot.extra?.[LEGACY_GAME_STORAGE_KEYS.doorStates];
+ const doors = legacyDoors?.state?.doorOpenStates;
+ snapshot.extra = isDoorStates(doors) ? { [DOORS_EXTRA_KEY]: doors } : {};
+
+ localStorageAdapter.setItem(SAVE_STORAGE_KEY, JSON.stringify(snapshot));
+ removeLegacyKeys();
+ return snapshot;
+}
+
+function readSavedGame(): GameSnapshot | null {
+ return loadGame(localStorageAdapter) ?? migrateLegacy();
+}
+
+// ============================================================================
+// Hidratación de los stores
+// ============================================================================
+
+let hydrated = false;
+let loadedSnapshot: GameSnapshot | null = null;
+
+/**
+ * Vuelca la partida guardada en los stores (inventario, ítems colocados, flags, puertas).
+ * Idempotente. Se ejecuta al importar este módulo en cliente (antes del primer render que
+ * lea los stores) y NO guarda nada: el guardado solo se activa en `startGamePersistence`.
+ *
+ * La escena NO se aplica aquí: la siembra `useSceneRuntime` con `loadCurrentSceneId` (con la
+ * escena completa de la demo y el aviso `scene:changed` al audio). Tampoco se restaura la
+ * posición del jugador: como siempre, al cargar aparece en el spawn de la escena.
+ */
+export function hydrateGameState(): void {
+ if (hydrated || typeof window === "undefined") return;
+ hydrated = true;
+ loadedSnapshot = readSavedGame();
+ const snapshot = loadedSnapshot;
+
+ useInventoryStateStore.getState().setSlots(snapshot?.inventory ?? createInitialInventorySlots());
+ if (snapshot) {
+ const placed = usePlacedItemsStateStore.getState();
+ placed.setItems(snapshot.placedItems);
+ placed.setSeededSceneIds(snapshot.seededSceneIds);
+ useWorldStateStore.getState().setAll({
+ flags: snapshot.flags,
+ visitedSceneIds: snapshot.visitedSceneIds,
+ });
+ }
+ useDoorStore.setState({ doorOpenStates: readDoors(snapshot) });
+}
+
+hydrateGameState();
+
+// ============================================================================
+// Guardado automático
+// ============================================================================
+
+let persistenceUsers = 0;
+let unsubscribers: Array<() => void> = [];
+let suspended = false;
+let saveScheduled = false;
+
+function saveNow(): void {
+ if (suspended) return;
+ // Sin escena todavía no hay partida que guardar.
+ if (!useSceneStore.getState().sceneId) return;
+ const extra = { [DOORS_EXTRA_KEY]: { ...useDoorStore.getState().doorOpenStates } };
+ const runtime = getGameRuntime();
+ if (runtime) runtime.executeCommand({ type: "game:save", extra });
+ else saveGame(localStorageAdapter, { extra });
+}
+
+/** Agrupa los cambios del mismo instante en un solo guardado. */
+function scheduleSave(): void {
+ if (saveScheduled || suspended) return;
+ saveScheduled = true;
+ queueMicrotask(() => {
+ saveScheduled = false;
+ saveNow();
+ });
+}
+
+function stopSubscriptions(): void {
+ unsubscribers.forEach((off) => off());
+ unsubscribers = [];
+}
+
+/**
+ * Activa el guardado automático (escribe el estado actual, ya hidratado, y después cada
+ * cambio de inventario, ítems colocados, flags/escenas visitadas, escena o puertas).
+ * Con contador de usos para StrictMode. Devuelve la función de baja.
+ */
+export function startGamePersistence(): () => void {
+ hydrateGameState();
+ if (persistenceUsers === 0 && !suspended) {
+ scheduleSave();
+ unsubscribers = [
+ useInventoryStateStore.subscribe((state, prev) => {
+ if (state.slots !== prev.slots) scheduleSave();
+ }),
+ usePlacedItemsStateStore.subscribe((state, prev) => {
+ if (state.items !== prev.items || state.seededSceneIds !== prev.seededSceneIds) {
+ scheduleSave();
+ }
+ }),
+ useWorldStateStore.subscribe((state, prev) => {
+ if (state.flags !== prev.flags || state.visitedSceneIds !== prev.visitedSceneIds) {
+ scheduleSave();
+ }
+ }),
+ useSceneStore.subscribe((state, prev) => {
+ if (state.sceneId !== prev.sceneId) scheduleSave();
+ }),
+ useDoorStore.subscribe((state, prev) => {
+ if (state.doorOpenStates !== prev.doorOpenStates) scheduleSave();
+ }),
+ ];
+ }
+ persistenceUsers += 1;
+ let released = false;
+ return () => {
+ if (released) return;
+ released = true;
+ persistenceUsers -= 1;
+ if (persistenceUsers === 0) stopSubscriptions();
+ };
+}
+
+// ============================================================================
+// Escena actual (puerto del renderer)
+// ============================================================================
+
+/** Escena de la partida guardada (para que el renderer la siembre al montar). */
+export function loadCurrentSceneId(): string | null {
+ return loadedSnapshot?.sceneId ?? null;
+}
+
+/** La escena se guarda con la instantánea (suscripción al `sceneStore`): nada que hacer aquí. */
+export function saveCurrentSceneId(): void {}
+
+// ============================================================================
+// Limpieza de progreso
+// ============================================================================
+
+/**
+ * Borra solo el progreso de la partida actual: `game:reset` (vacía los stores y borra
+ * la instantánea con `clearSave`) y las claves antiguas por si quedaran. Antes se corta
+ * el guardado automático para que el vaciado de los stores no reescriba la partida.
+ *
+ * Preserva idioma (`i18n-locale`), ajustes de audio (`audio-settings`) y cualquier clave
+ * ajena. Nunca usa `localStorage.clear()`.
+ */
+export function clearGameProgress(): void {
+ suspended = true;
+ stopSubscriptions();
+ const runtime = getGameRuntime();
+ if (runtime) runtime.executeCommand({ type: "game:reset" });
+ else resetGameState();
+ // Idempotente: cubre un runtime creado sin `storage`.
+ clearSave(localStorageAdapter);
+ useDoorStore.setState({ doorOpenStates: {} });
+ removeLegacyKeys();
+}
diff --git a/apps/web-demo/app/lib/platform-web-audio.test.ts b/apps/web-demo/app/lib/platform-web-audio.test.ts
index 2086bdf..09a592c 100644
--- a/apps/web-demo/app/lib/platform-web-audio.test.ts
+++ b/apps/web-demo/app/lib/platform-web-audio.test.ts
@@ -42,10 +42,7 @@ function FakeAudio(this: FakeAudioInstance, url: string) {
function unlockAdapter() {
// The adapter queues plays until a user gesture. Simulate it.
- const handlers = (globalThis as any).__windowHandlers as Map<
- string,
- Array
- >;
+ const handlers = (globalThis as unknown as { __windowHandlers: Map> }).__windowHandlers;
const pointerHandlers = handlers.get("pointerdown") ?? [];
for (const h of pointerHandlers) {
if (typeof h === "function") h(new Event("pointerdown"));
@@ -55,7 +52,7 @@ function unlockAdapter() {
beforeEach(() => {
audioInstances.length = 0;
const handlers = new Map>();
- (globalThis as any).__windowHandlers = handlers;
+ (globalThis as unknown as { __windowHandlers?: Map> }).__windowHandlers = handlers;
vi.stubGlobal("window", {
addEventListener: (name: string, h: EventListenerOrEventListenerObject) => {
const list = handlers.get(name) ?? [];
diff --git a/apps/web-demo/app/lib/platform-web-audio.ts b/apps/web-demo/app/lib/platform-web-audio.ts
index cbaf78f..96e1187 100644
--- a/apps/web-demo/app/lib/platform-web-audio.ts
+++ b/apps/web-demo/app/lib/platform-web-audio.ts
@@ -254,7 +254,7 @@ export class WebAudioAdapter implements AudioPort {
resolve();
};
audio.addEventListener("canplaythrough", onReady, { once: true });
- const timeout = setTimeout(() => {
+ setTimeout(() => {
audio.removeEventListener("canplaythrough", onReady);
resolve();
}, 5000);
diff --git a/apps/web-demo/app/page.tsx b/apps/web-demo/app/page.tsx
index 636618e..49b8ab6 100644
--- a/apps/web-demo/app/page.tsx
+++ b/apps/web-demo/app/page.tsx
@@ -1,15 +1,13 @@
"use client";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useState } from "react";
import {
createGameRuntime,
- type GameSceneConfig,
+ type GameRuntime,
} from "./lib/engine/publicApi";
import { CRTEffectWrapper } from "./lib/components/CRTEffectWrapper";
-import { SCENES } from "../demo-content/scenes/scenes";
+import { DEMO_RUNTIME_CONFIG } from "./lib/engine/runtime/demoViewportOptions";
import GameTouchCanvas from "./components/GameTouchCanvas";
-import { useInventoryStore } from "./store/inventoryStore";
-import { useDialogStore } from "./store/dialogStore";
import { IntroScene } from "./components/intro/IntroScene";
import { useLocaleDetection } from "@pointclick-engine/engine-renderer-r3f";
import { createWebI18nAdapter } from "./lib/platform-web";
@@ -33,25 +31,27 @@ const I18N_CONFIG = {
};
function Game() {
+ // El runtime se crea en un efecto (con su dispose en el cleanup) y el canvas
+ // solo se monta cuando ya existe: los efectos de los hijos corren antes que
+ // los del padre, y useSceneRuntimeController fija la escena inicial en uno de
+ // ellos. Montando el canvas despues, el `scene:changed` inicial llega al bus
+ // (musica inicial) y no hace falta esperar al runtime con polling.
+ // StrictMode (create -> dispose -> create) es seguro: cada ciclo del efecto
+ // crea su propio runtime y el estado final apunta al ultimo, que sigue vivo.
+ const [runtime, setRuntime] = useState(null);
+
useEffect(() => {
- const runtime = createGameRuntime({
- scenes: Object.values(SCENES) as GameSceneConfig[],
- inventoryAdapter: {
- toggle: () => useInventoryStore.getState().toggle(),
- isOpen: () => useInventoryStore.getState().isOpen,
- },
- dialogAdapter: {
- show: (text, key) => useDialogStore.getState().show(text, key),
- hide: () => useDialogStore.getState().dismiss(),
- },
- });
+ const created = createGameRuntime(DEMO_RUNTIME_CONFIG);
+ // eslint-disable-next-line react-hooks/set-state-in-effect -- publishes the external runtime handle so children mount only once it exists (children effects run before the parent's)
+ setRuntime(created);
return () => {
- runtime.dispose();
+ created.dispose();
+ setRuntime(null);
};
}, []);
- return ;
+ return runtime ? : null;
}
export default function Home() {
diff --git a/apps/web-demo/app/store/dialogStore.ts b/apps/web-demo/app/store/dialogStore.ts
index c6b738c..216b429 100644
--- a/apps/web-demo/app/store/dialogStore.ts
+++ b/apps/web-demo/app/store/dialogStore.ts
@@ -1,33 +1,5 @@
-import { create } from "zustand";
-
/**
- * dialogStore — estado del diálogo/speech bubble activo.
- *
- * Accesible desde ejecutores de comandos (`publicApi.ts`) y componentes UI.
- * Reemplaza el estado local de speech en `useInventoryRuntimeController` para
- * que `dialog:trigger` y `dialog:dismiss` funcionen sin acceso al scope React.
+ * dialogStore — el store vive en engine-core (`useDialogStore`).
+ * Re-export para que los consumidores de la demo no cambien.
*/
-type DialogStoreState = {
- text: string;
- key: string | undefined;
- visible: boolean;
- /** Incrementado en cada `show()` para forzar re-animación del speech bubble. */
- triggerCount: number;
- show: (text: string, key?: string) => void;
- dismiss: () => void;
-};
-
-export const useDialogStore = create((set) => ({
- text: "",
- key: undefined,
- visible: false,
- triggerCount: 0,
- show: (text, key) =>
- set((s) => ({
- text,
- key,
- visible: true,
- triggerCount: s.triggerCount + 1,
- })),
- dismiss: () => set({ visible: false }),
-}));
+export { useDialogStore } from "@pointclick-engine/engine-core";
diff --git a/apps/web-demo/app/store/doorStore.ts b/apps/web-demo/app/store/doorStore.ts
index 5fb19a6..bb79c26 100644
--- a/apps/web-demo/app/store/doorStore.ts
+++ b/apps/web-demo/app/store/doorStore.ts
@@ -1,5 +1,4 @@
import { create } from "zustand";
-import { persist } from "zustand/middleware";
/**
* doorStore — estado abierto/cerrado de las puertas de la escena.
@@ -13,7 +12,8 @@ import { persist } from "zustand/middleware";
* "closed" — the same default used by `SceneDoors` if a scene declares the
* door without a starting state.
*
- * Door state is persisted to localStorage so doors remain open after page reload.
+ * Door state is saved inside the game snapshot (`extra.doors`) by
+ * `gamePersistence.ts`, so doors remain open after page reload.
*/
type DoorStoreState = {
doorOpenStates: Record;
@@ -27,26 +27,19 @@ type DoorStoreState = {
reset: (initial: Record) => void;
};
-export const useDoorStore = create()(
- persist(
- (set, get) => ({
- doorOpenStates: {},
- isOpen: (id) => Boolean(get().doorOpenStates[id]),
- setOpen: (id, isOpen) =>
- set((s) => ({
- doorOpenStates: { ...s.doorOpenStates, [id]: isOpen },
- })),
- toggle: (id) =>
- set((s) => ({
- doorOpenStates: {
- ...s.doorOpenStates,
- [id]: !s.doorOpenStates[id],
- },
- })),
- reset: (initial) => set({ doorOpenStates: { ...initial } }),
- }),
- {
- name: "door-states",
- },
- ),
-);
+export const useDoorStore = create()((set, get) => ({
+ doorOpenStates: {},
+ isOpen: (id) => Boolean(get().doorOpenStates[id]),
+ setOpen: (id, isOpen) =>
+ set((s) => ({
+ doorOpenStates: { ...s.doorOpenStates, [id]: isOpen },
+ })),
+ toggle: (id) =>
+ set((s) => ({
+ doorOpenStates: {
+ ...s.doorOpenStates,
+ [id]: !s.doorOpenStates[id],
+ },
+ })),
+ reset: (initial) => set({ doorOpenStates: { ...initial } }),
+}));
diff --git a/apps/web-demo/app/store/inventoryStore.ts b/apps/web-demo/app/store/inventoryStore.ts
index 10e6801..c3d23c9 100644
--- a/apps/web-demo/app/store/inventoryStore.ts
+++ b/apps/web-demo/app/store/inventoryStore.ts
@@ -1,22 +1,5 @@
-import { create } from "zustand";
-
/**
- * inventoryStore — estado de visibilidad del inventario.
- *
- * Accesible desde ejecutores de comandos (`publicApi.ts`) y componentes UI.
- * Separado de `useInventoryRuntimeController` para que `inventory:toggle`
- * funcione sin acceso al scope React del componente.
+ * inventoryStore — el store vive en engine-core (`useInventoryUiStore`).
+ * Alias con el nombre historico de la demo para no tocar a los consumidores.
*/
-type InventoryStoreState = {
- isOpen: boolean;
- toggle: () => void;
- open: () => void;
- close: () => void;
-};
-
-export const useInventoryStore = create((set) => ({
- isOpen: false,
- toggle: () => set((s) => ({ isOpen: !s.isOpen })),
- open: () => set({ isOpen: true }),
- close: () => set({ isOpen: false }),
-}));
+export { useInventoryUiStore as useInventoryStore } from "@pointclick-engine/engine-core";
diff --git a/apps/web-demo/app/store/placedItemsStore.ts b/apps/web-demo/app/store/placedItemsStore.ts
deleted file mode 100644
index 401710d..0000000
--- a/apps/web-demo/app/store/placedItemsStore.ts
+++ /dev/null
@@ -1,26 +0,0 @@
-import { create } from "zustand";
-import { persist } from "zustand/middleware";
-import type { PlacedSceneItem } from "@pointclick-engine/engine-core";
-
-type PlacedItemsStoreState = {
- items: PlacedSceneItem[];
- setItems: (items: PlacedSceneItem[]) => void;
- initialItemsCreated: boolean;
- markInitialItemsCreated: () => void;
-};
-
-const STORAGE_KEY = "placed-items-state";
-
-export const usePlacedItemsStore = create()(
- persist(
- (set) => ({
- items: [],
- setItems: (items: PlacedSceneItem[]) => set({ items }),
- initialItemsCreated: false,
- markInitialItemsCreated: () => set({ initialItemsCreated: true }),
- }),
- {
- name: STORAGE_KEY,
- },
- ),
-);
diff --git a/apps/web-demo/assets-src/README.md b/apps/web-demo/assets-src/README.md
new file mode 100644
index 0000000..09c3f21
--- /dev/null
+++ b/apps/web-demo/assets-src/README.md
@@ -0,0 +1,24 @@
+# Fuentes de arte (no se sirven)
+
+Material de terceros descargado tal cual, para elegir de aquí los assets de la demo con historia (Fase 18). Esta carpeta **no** está bajo `public/`: no se sirve ni se despliega. Lo que se use en el juego se copia a `public/assets/` y se anota en el `LICENSES.md` de arte correspondiente.
+
+## Packs
+
+| Carpeta | Pack | Autor | Licencia | Origen | Descargado |
+|---|---|---|---|---|---|
+| `items/7soul-rpg-icons/` | 496 pixel art icons for medieval/fantasy RPG — 496 PNG de 34×34 | Henrique Lazarini (7Soul1) | CC0 | https://opengameart.org/node/39455 | 2026-10-10 |
+| `items/idylwild-inventory/` | Idylwild's Inventory — 51 PNG de 32×32 y el `.ase` fuente | Idylwild | CC0 | https://opengameart.org/content/idylwilds-inventory | 2026-10-10 |
+| `backgrounds/sci-fi-level/` | Sci Fi Level — fondo y primer plano de 5121×841 (PNG) y las capas sueltas en dos tamaños (`.tar.gz`) | Jeremy Gooch (jeremygooch.blogspot.com) | CC-BY 3.0 (también CC-BY-SA 3.0, GPL 2.0 y GPL 3.0) | https://opengameart.org/content/sci-fi-level | 2026-10-11 |
+| `characters/helix-male/` | 8 Directional 2D Point and Click Male Character — una hoja de sprites (`helix_full_sheet.png`) con reposo y paseo en 8 direcciones, pensada para 64×64 | DeMoNiCaTeD | CC-BY-SA 4.0 (también GPL 3.0) | https://opengameart.org/content/8-directional-2d-point-and-click-male-character | 2026-10-11 |
+
+Los dos packs de ítems están en dominio público (CC0): se pueden usar, modificar y redistribuir sin condiciones. La atribución no es obligatoria, pero se mantiene esta tabla.
+
+**Sci Fi Level exige atribución** (CC-BY 3.0): donde se use hay que acreditar "Jeremy Gooch (jeremygooch.blogspot.com)", en los créditos del juego y en el `LICENSES.md` de arte.
+
+**El personaje Helix es CC-BY-SA 4.0**: exige acreditar al autor (DeMoNiCaTeD), enlazar la licencia e indicar los cambios, y cualquier versión modificada (frames recortados, tintes, reescalados) debe publicarse con la misma licencia.
+
+## Convenciones
+
+- Los archivos se guardan sin modificar, con su nombre original.
+- Los iconos se escalan ×2 sin suavizado al copiarlos a `public/assets/`, para igualar los 64×64 de los ítems actuales.
+- Antes de añadir otro pack, comprobar su licencia y anotarla aquí. El repositorio es público: solo material que permita redistribución.
diff --git a/apps/web-demo/assets-src/backgrounds/sci-fi-level/sci-fi-level[background_layer].png b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sci-fi-level[background_layer].png
new file mode 100644
index 0000000..b40d9a0
Binary files /dev/null and b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sci-fi-level[background_layer].png differ
diff --git a/apps/web-demo/assets-src/backgrounds/sci-fi-level/sci-fi-level[foreground_layer].png b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sci-fi-level[foreground_layer].png
new file mode 100644
index 0000000..2e51e29
Binary files /dev/null and b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sci-fi-level[foreground_layer].png differ
diff --git a/apps/web-demo/assets-src/backgrounds/sci-fi-level/sciFi_layers[large].tar.gz b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sciFi_layers[large].tar.gz
new file mode 100644
index 0000000..5ba48bc
Binary files /dev/null and b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sciFi_layers[large].tar.gz differ
diff --git a/apps/web-demo/assets-src/backgrounds/sci-fi-level/sciFi_layers[small].tar.gz b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sciFi_layers[small].tar.gz
new file mode 100644
index 0000000..9e5fed9
Binary files /dev/null and b/apps/web-demo/assets-src/backgrounds/sci-fi-level/sciFi_layers[small].tar.gz differ
diff --git a/apps/web-demo/assets-src/characters/helix-male/helix_full_sheet.png b/apps/web-demo/assets-src/characters/helix-male/helix_full_sheet.png
new file mode 100644
index 0000000..b6bd011
Binary files /dev/null and b/apps/web-demo/assets-src/characters/helix-male/helix_full_sheet.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armor04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armor04.png
new file mode 100644
index 0000000..a31e04f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armor04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armor05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armor05.png
new file mode 100644
index 0000000..cc7d88b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armor05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour01.png
new file mode 100644
index 0000000..747f7e4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour02.png
new file mode 100644
index 0000000..b680d01
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour03.png
new file mode 100644
index 0000000..a30ab9e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Armour03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Clothing01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Clothing01.png
new file mode 100644
index 0000000..86d24da
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Clothing01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Clothing02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Clothing02.png
new file mode 100644
index 0000000..4cd9027
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Clothing02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes01.png
new file mode 100644
index 0000000..1fcf2f1
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes02.png
new file mode 100644
index 0000000..c25544b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes03.png
new file mode 100644
index 0000000..afd5b3d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes04.png
new file mode 100644
index 0000000..fee4be8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes05.png
new file mode 100644
index 0000000..abc2bbc
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes06.png
new file mode 100644
index 0000000..de882c9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes07.png
new file mode 100644
index 0000000..79dd46d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/A_Shoes07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal01.png
new file mode 100644
index 0000000..c94f84e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal02.png
new file mode 100644
index 0000000..9058757
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal03.png
new file mode 100644
index 0000000..590219e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal04.png
new file mode 100644
index 0000000..824147b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Medal04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace01.png
new file mode 100644
index 0000000..50872bc
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace02.png
new file mode 100644
index 0000000..7891a34
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace03.png
new file mode 100644
index 0000000..f7c10fe
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace04.png
new file mode 100644
index 0000000..e929dfa
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace05.png
new file mode 100644
index 0000000..2ef38b7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace06.png
new file mode 100644
index 0000000..23c90ae
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace07.png
new file mode 100644
index 0000000..5f52a76
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace08.png
new file mode 100644
index 0000000..824da05
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Necklace08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Ring01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Ring01.png
new file mode 100644
index 0000000..dfee3ee
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Ring01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Ring02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Ring02.png
new file mode 100644
index 0000000..9d6161c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/Ac_Ring02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm01.png
new file mode 100644
index 0000000..3144561
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm03.png
new file mode 100644
index 0000000..b045d4b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm04.png
new file mode 100644
index 0000000..0b232eb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Elm04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Hat01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Hat01.png
new file mode 100644
index 0000000..620880e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Hat01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Hat02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Hat02.png
new file mode 100644
index 0000000..08335ee
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/C_Hat02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Bones02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Bones02.png
new file mode 100644
index 0000000..b49ed1a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Bones02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Bones03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Bones03.png
new file mode 100644
index 0000000..c3adb4b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Bones03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Gold01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Gold01.png
new file mode 100644
index 0000000..0129e82
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Gold01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Gold02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Gold02.png
new file mode 100644
index 0000000..115ee12
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Gold02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal01.png
new file mode 100644
index 0000000..394b70d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal02.png
new file mode 100644
index 0000000..1f4900a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal03.png
new file mode 100644
index 0000000..f746ac4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal04.png
new file mode 100644
index 0000000..0f0bc49
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal05.png
new file mode 100644
index 0000000..850d5ed
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal06.png
new file mode 100644
index 0000000..1b6cc99
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal07.png
new file mode 100644
index 0000000..e916d6d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal08.png
new file mode 100644
index 0000000..7850875
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal09.png
new file mode 100644
index 0000000..32e51de
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Metal09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood01.png
new file mode 100644
index 0000000..32cd977
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood02.png
new file mode 100644
index 0000000..9b03dc4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood03.png
new file mode 100644
index 0000000..03e76d3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood04.png
new file mode 100644
index 0000000..b98c337
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/E_Wood04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Agate.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Agate.png
new file mode 100644
index 0000000..a701852
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Agate.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Amethist.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Amethist.png
new file mode 100644
index 0000000..684937f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Amethist.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Antidote.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Antidote.png
new file mode 100644
index 0000000..4dea993
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Antidote.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BatWing.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BatWing.png
new file mode 100644
index 0000000..ef3cbf8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BatWing.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BirdsBeak.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BirdsBeak.png
new file mode 100644
index 0000000..26bf7ef
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BirdsBeak.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bone.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bone.png
new file mode 100644
index 0000000..972d44a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bone.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Book.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Book.png
new file mode 100644
index 0000000..8e5b687
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Book.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle01.png
new file mode 100644
index 0000000..401be59
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle02.png
new file mode 100644
index 0000000..8390d80
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle03.png
new file mode 100644
index 0000000..0093b07
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle04.png
new file mode 100644
index 0000000..6b87204
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Bottle04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BronzeBar.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BronzeBar.png
new file mode 100644
index 0000000..a226465
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BronzeBar.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BronzeCoin.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BronzeCoin.png
new file mode 100644
index 0000000..a35da87
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_BronzeCoin.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Banana.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Banana.png
new file mode 100644
index 0000000..4a492a9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Banana.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Bread.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Bread.png
new file mode 100644
index 0000000..71bfa9e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Bread.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Carrot.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Carrot.png
new file mode 100644
index 0000000..be2c0bf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Carrot.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Cheese.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Cheese.png
new file mode 100644
index 0000000..384e1c4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Cheese.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Cherry.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Cherry.png
new file mode 100644
index 0000000..a9f151e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Cherry.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Fish.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Fish.png
new file mode 100644
index 0000000..517fbef
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Fish.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Grapes.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Grapes.png
new file mode 100644
index 0000000..bfb7e68
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Grapes.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_GreenGrapes.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_GreenGrapes.png
new file mode 100644
index 0000000..da957de
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_GreenGrapes.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_GreenPepper.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_GreenPepper.png
new file mode 100644
index 0000000..c675b5b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_GreenPepper.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Lemon.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Lemon.png
new file mode 100644
index 0000000..0474910
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Lemon.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Meat.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Meat.png
new file mode 100644
index 0000000..42df984
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Meat.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Mulberry.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Mulberry.png
new file mode 100644
index 0000000..ceceacb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Mulberry.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Mushroom.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Mushroom.png
new file mode 100644
index 0000000..b9b9f51
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Mushroom.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Nut.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Nut.png
new file mode 100644
index 0000000..44f10c8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Nut.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Orange.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Orange.png
new file mode 100644
index 0000000..e6c298b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Orange.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pear.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pear.png
new file mode 100644
index 0000000..688e588
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pear.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pie.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pie.png
new file mode 100644
index 0000000..5fed405
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pie.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pineapple.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pineapple.png
new file mode 100644
index 0000000..9ef6dad
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Pineapple.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Radish.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Radish.png
new file mode 100644
index 0000000..957f0d7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Radish.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RawFish.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RawFish.png
new file mode 100644
index 0000000..086e6dd
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RawFish.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RawMeat.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RawMeat.png
new file mode 100644
index 0000000..22c279f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RawMeat.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RedPepper.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RedPepper.png
new file mode 100644
index 0000000..64703c7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_RedPepper.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Strawberry.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Strawberry.png
new file mode 100644
index 0000000..bc22727
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Strawberry.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Watermellon.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Watermellon.png
new file mode 100644
index 0000000..92760bf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_Watermellon.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_YellowPepper.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_YellowPepper.png
new file mode 100644
index 0000000..460000e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_C_YellowPepper.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon01.png
new file mode 100644
index 0000000..cc0624c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon02.png
new file mode 100644
index 0000000..1ea7c56
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon03.png
new file mode 100644
index 0000000..30b7965
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon04.png
new file mode 100644
index 0000000..655d77b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon05.png
new file mode 100644
index 0000000..36ecb00
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Cannon05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Chest01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Chest01.png
new file mode 100644
index 0000000..71cf24e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Chest01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Chest02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Chest02.png
new file mode 100644
index 0000000..58e470f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Chest02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Clock.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Clock.png
new file mode 100644
index 0000000..29db742
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Clock.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Clover.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Clover.png
new file mode 100644
index 0000000..e4c977b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Clover.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Coal.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Coal.png
new file mode 100644
index 0000000..110f497
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Coal.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal01.png
new file mode 100644
index 0000000..d398c4f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal02.png
new file mode 100644
index 0000000..8a0ef08
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal03.png
new file mode 100644
index 0000000..9f53e3d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Crystal03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Diamond.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Diamond.png
new file mode 100644
index 0000000..22c2d02
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Diamond.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Eye.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Eye.png
new file mode 100644
index 0000000..3147f90
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Eye.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Fabric.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Fabric.png
new file mode 100644
index 0000000..210d2cf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Fabric.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Fang.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Fang.png
new file mode 100644
index 0000000..25f8daf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Fang.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Feather01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Feather01.png
new file mode 100644
index 0000000..26ea804
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Feather01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Feather02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Feather02.png
new file mode 100644
index 0000000..03ef83b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Feather02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FishTail.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FishTail.png
new file mode 100644
index 0000000..ffde951
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FishTail.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FoxTail.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FoxTail.png
new file mode 100644
index 0000000..6f6e848
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FoxTail.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FrogLeg.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FrogLeg.png
new file mode 100644
index 0000000..0f3ef81
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_FrogLeg.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_GoldBar.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_GoldBar.png
new file mode 100644
index 0000000..649df55
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_GoldBar.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_GoldCoin.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_GoldCoin.png
new file mode 100644
index 0000000..d94762a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_GoldCoin.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Ink.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Ink.png
new file mode 100644
index 0000000..a909d04
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Ink.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_IronBall.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_IronBall.png
new file mode 100644
index 0000000..1bb3bf8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_IronBall.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Jade.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Jade.png
new file mode 100644
index 0000000..0c951f5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Jade.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key01.png
new file mode 100644
index 0000000..8a84d23
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key02.png
new file mode 100644
index 0000000..9d63f0b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key03.png
new file mode 100644
index 0000000..a72d37b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key04.png
new file mode 100644
index 0000000..59548ed
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key05.png
new file mode 100644
index 0000000..3a18db6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key06.png
new file mode 100644
index 0000000..54d5a7a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key07.png
new file mode 100644
index 0000000..8895c0f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Key07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Leaf.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Leaf.png
new file mode 100644
index 0000000..3b67c05
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Leaf.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Map.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Map.png
new file mode 100644
index 0000000..89f3605
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Map.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Mirror.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Mirror.png
new file mode 100644
index 0000000..a7b9ed2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Mirror.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Opal.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Opal.png
new file mode 100644
index 0000000..9295f2c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Opal.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_RabbitPaw.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_RabbitPaw.png
new file mode 100644
index 0000000..adc3c3f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_RabbitPaw.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock01.png
new file mode 100644
index 0000000..6064034
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock02.png
new file mode 100644
index 0000000..9cfc57b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock03.png
new file mode 100644
index 0000000..6124aba
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock04.png
new file mode 100644
index 0000000..5439ff8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock05.png
new file mode 100644
index 0000000..903a270
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Rock05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Ruby.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Ruby.png
new file mode 100644
index 0000000..188862e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Ruby.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Sapphire.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Sapphire.png
new file mode 100644
index 0000000..a0a6d63
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Sapphire.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_ScorpionClaw.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_ScorpionClaw.png
new file mode 100644
index 0000000..8a85d42
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_ScorpionClaw.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Scroll.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Scroll.png
new file mode 100644
index 0000000..23cd50e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Scroll.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Scroll02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Scroll02.png
new file mode 100644
index 0000000..f2411b3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Scroll02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SilverBar.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SilverBar.png
new file mode 100644
index 0000000..4a1b60b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SilverBar.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SilverCoin.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SilverCoin.png
new file mode 100644
index 0000000..875c925
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SilverCoin.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SnailShell.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SnailShell.png
new file mode 100644
index 0000000..0cb7bc2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SnailShell.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SolidShell.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SolidShell.png
new file mode 100644
index 0000000..e196416
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_SolidShell.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Telescope.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Telescope.png
new file mode 100644
index 0000000..bafa4cb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Telescope.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Tentacle.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Tentacle.png
new file mode 100644
index 0000000..97cb2e4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Tentacle.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Torch01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Torch01.png
new file mode 100644
index 0000000..a5c37be
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Torch01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Torch02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Torch02.png
new file mode 100644
index 0000000..0e2c906
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Torch02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Water.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Water.png
new file mode 100644
index 0000000..e347cd9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_Water.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/I_WolfFur.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_WolfFur.png
new file mode 100644
index 0000000..31244bb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/I_WolfFur.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue01.png
new file mode 100644
index 0000000..399cf44
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue02.png
new file mode 100644
index 0000000..d4ea865
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue03.png
new file mode 100644
index 0000000..81470f6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue04.png
new file mode 100644
index 0000000..0b9faef
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue05.png
new file mode 100644
index 0000000..b1abdca
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue06.png
new file mode 100644
index 0000000..76f2b66
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue07.png
new file mode 100644
index 0000000..eda9089
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue08.png
new file mode 100644
index 0000000..9d4a58b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Blue08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green01.png
new file mode 100644
index 0000000..6dcd755
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green02.png
new file mode 100644
index 0000000..1221400
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green03.png
new file mode 100644
index 0000000..c657a0b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green04.png
new file mode 100644
index 0000000..fb5a330
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green05.png
new file mode 100644
index 0000000..446f8c8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green06.png
new file mode 100644
index 0000000..d3cf6cd
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Green06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine01.png
new file mode 100644
index 0000000..e7ed77c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine02.png
new file mode 100644
index 0000000..f730b88
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine03.png
new file mode 100644
index 0000000..97481ba
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine04.png
new file mode 100644
index 0000000..81c9257
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine05.png
new file mode 100644
index 0000000..785adf7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine06.png
new file mode 100644
index 0000000..3746c9b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine07.png
new file mode 100644
index 0000000..ade454f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine08.png
new file mode 100644
index 0000000..cef28a0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine09.png
new file mode 100644
index 0000000..9d7fa1c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Medicine09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange01.png
new file mode 100644
index 0000000..ee7da21
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange02.png
new file mode 100644
index 0000000..294ce63
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange03.png
new file mode 100644
index 0000000..170173d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange04.png
new file mode 100644
index 0000000..89b3a52
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange05.png
new file mode 100644
index 0000000..316d696
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange06.png
new file mode 100644
index 0000000..5dd417e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Orange06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink01.png
new file mode 100644
index 0000000..f90e006
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink02.png
new file mode 100644
index 0000000..f5a2d7a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink03.png
new file mode 100644
index 0000000..7c0371d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink04.png
new file mode 100644
index 0000000..45434b0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink05.png
new file mode 100644
index 0000000..61b4a77
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink06.png
new file mode 100644
index 0000000..913bd83
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink07.png
new file mode 100644
index 0000000..36e116c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink08.png
new file mode 100644
index 0000000..2998b25
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Pink08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red01.png
new file mode 100644
index 0000000..d9d5c96
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red02.png
new file mode 100644
index 0000000..56ff726
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red03.png
new file mode 100644
index 0000000..bbb80a6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red04.png
new file mode 100644
index 0000000..66a6065
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red05.png
new file mode 100644
index 0000000..7ad082d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red06.png
new file mode 100644
index 0000000..eea7e70
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red07.png
new file mode 100644
index 0000000..c0c1dd5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Red07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White01.png
new file mode 100644
index 0000000..68f24d2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White02.png
new file mode 100644
index 0000000..6bcdea5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White03.png
new file mode 100644
index 0000000..25535dd
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White04.png
new file mode 100644
index 0000000..645ca48
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White05.png
new file mode 100644
index 0000000..fc6a1f6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_White05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow01.png
new file mode 100644
index 0000000..248267b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow02.png
new file mode 100644
index 0000000..8b686f5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow03.png
new file mode 100644
index 0000000..5d26d82
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow04.png
new file mode 100644
index 0000000..7221938
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow05.png
new file mode 100644
index 0000000..71eae8f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow06.png
new file mode 100644
index 0000000..3cd1523
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow07.png
new file mode 100644
index 0000000..3086400
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow08.png
new file mode 100644
index 0000000..ae8afb4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/P_Yellow08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe01.png
new file mode 100644
index 0000000..1716410
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe02.png
new file mode 100644
index 0000000..f900f9f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe03.png
new file mode 100644
index 0000000..9bf6229
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe04.png
new file mode 100644
index 0000000..4722ba9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe05.png
new file mode 100644
index 0000000..a6a956d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe06.png
new file mode 100644
index 0000000..1bdb356
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe07.png
new file mode 100644
index 0000000..2f28ba0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Axe07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow01.png
new file mode 100644
index 0000000..eb3655b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow02.png
new file mode 100644
index 0000000..8feae95
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow03.png
new file mode 100644
index 0000000..d598d65
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow04.png
new file mode 100644
index 0000000..44e8986
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow05.png
new file mode 100644
index 0000000..74ca3bb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow06.png
new file mode 100644
index 0000000..b212035
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow07.png
new file mode 100644
index 0000000..50236ef
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow08.png
new file mode 100644
index 0000000..0d47949
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow09.png
new file mode 100644
index 0000000..c35b24f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow10.png
new file mode 100644
index 0000000..4561fdb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow11.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow11.png
new file mode 100644
index 0000000..bfbb27f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow11.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow12.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow12.png
new file mode 100644
index 0000000..f84f180
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow12.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow13.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow13.png
new file mode 100644
index 0000000..1bb188b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow13.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow14.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow14.png
new file mode 100644
index 0000000..d6c243c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Bow14.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff01.png
new file mode 100644
index 0000000..ab1756f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff02.png
new file mode 100644
index 0000000..46e9ab2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff03.png
new file mode 100644
index 0000000..0f9ecca
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff04.png
new file mode 100644
index 0000000..9d0d3e9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff05.png
new file mode 100644
index 0000000..ff8fc59
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff06.png
new file mode 100644
index 0000000..c562bce
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff07.png
new file mode 100644
index 0000000..c562bce
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff08.png
new file mode 100644
index 0000000..2fd69f6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff09.png
new file mode 100644
index 0000000..dcbb11f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff10.png
new file mode 100644
index 0000000..c5df567
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff11.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff11.png
new file mode 100644
index 0000000..7a5a146
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff11.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff12.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff12.png
new file mode 100644
index 0000000..45cee17
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff12.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff13.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff13.png
new file mode 100644
index 0000000..804454f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff13.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff14.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff14.png
new file mode 100644
index 0000000..2e66075
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Buff14.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger02.png
new file mode 100644
index 0000000..017dd86
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger03.png
new file mode 100644
index 0000000..ffad54e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger04.png
new file mode 100644
index 0000000..70ca4c3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger05.png
new file mode 100644
index 0000000..419ffd9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger06.png
new file mode 100644
index 0000000..71465ad
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Dagger06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth01.png
new file mode 100644
index 0000000..189a306
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth02.png
new file mode 100644
index 0000000..60ed9a0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth03.png
new file mode 100644
index 0000000..8e54818
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth04.png
new file mode 100644
index 0000000..fc360a1
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth05.png
new file mode 100644
index 0000000..105ba25
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth06.png
new file mode 100644
index 0000000..a635951
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth07.png
new file mode 100644
index 0000000..a3c74f2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Earth07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire01.png
new file mode 100644
index 0000000..620b2f8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire02.png
new file mode 100644
index 0000000..5eacb67
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire03.png
new file mode 100644
index 0000000..b581229
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire04.png
new file mode 100644
index 0000000..8c78e6b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire05.png
new file mode 100644
index 0000000..a4197a9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire06.png
new file mode 100644
index 0000000..c7b0305
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire07.png
new file mode 100644
index 0000000..076a930
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire08.png
new file mode 100644
index 0000000..01246e6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Fire08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy01.png
new file mode 100644
index 0000000..7d79e22
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy02.png
new file mode 100644
index 0000000..2f17ec9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy03.png
new file mode 100644
index 0000000..16f7bc6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy04.png
new file mode 100644
index 0000000..cb7b145
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy05.png
new file mode 100644
index 0000000..5be76b6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy06.png
new file mode 100644
index 0000000..65c2ee6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy07.png
new file mode 100644
index 0000000..f6562e3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy08.png
new file mode 100644
index 0000000..913f2ea
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy09.png
new file mode 100644
index 0000000..83419fa
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy10.png
new file mode 100644
index 0000000..3dca24d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Holy10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice01.png
new file mode 100644
index 0000000..fa0c5b3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice02.png
new file mode 100644
index 0000000..8ad9b4d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice03.png
new file mode 100644
index 0000000..7cf3bdb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice04.png
new file mode 100644
index 0000000..d39d8d4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice05.png
new file mode 100644
index 0000000..5310923
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice06.png
new file mode 100644
index 0000000..b90e60c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice07.png
new file mode 100644
index 0000000..b54fa20
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice08.png
new file mode 100644
index 0000000..1ef34a8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice09.png
new file mode 100644
index 0000000..96a1290
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Ice09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light01.png
new file mode 100644
index 0000000..1d1f592
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light02.png
new file mode 100644
index 0000000..773add5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light03.png
new file mode 100644
index 0000000..0fa7aca
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light04.png
new file mode 100644
index 0000000..56dc636
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Light04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic01.png
new file mode 100644
index 0000000..15c639c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic02.png
new file mode 100644
index 0000000..0d623bf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic03.png
new file mode 100644
index 0000000..5654a04
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic04.png
new file mode 100644
index 0000000..da45b40
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic05.png
new file mode 100644
index 0000000..5eff177
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic06.png
new file mode 100644
index 0000000..9a110af
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic07.png
new file mode 100644
index 0000000..a3dbd76
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic08.png
new file mode 100644
index 0000000..e46959d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic09.png
new file mode 100644
index 0000000..7c3a6b3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic10.png
new file mode 100644
index 0000000..261ce4e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic11.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic11.png
new file mode 100644
index 0000000..2797a93
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Magic11.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Physic01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Physic01.png
new file mode 100644
index 0000000..c3b46a9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Physic01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Physic02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Physic02.png
new file mode 100644
index 0000000..8192f32
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Physic02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison01.png
new file mode 100644
index 0000000..ff90875
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison02.png
new file mode 100644
index 0000000..a1fac2c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison03.png
new file mode 100644
index 0000000..476b12f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison04.png
new file mode 100644
index 0000000..4ac01b5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison05.png
new file mode 100644
index 0000000..8702d46
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison06.png
new file mode 100644
index 0000000..8e08739
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison07.png
new file mode 100644
index 0000000..b76f316
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison08.png
new file mode 100644
index 0000000..ed93125
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison09.png
new file mode 100644
index 0000000..901060e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Poison09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow01.png
new file mode 100644
index 0000000..b9683d7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow02.png
new file mode 100644
index 0000000..5d88f4b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow03.png
new file mode 100644
index 0000000..98dce99
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow04.png
new file mode 100644
index 0000000..30677eb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow05.png
new file mode 100644
index 0000000..ade6be8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow06.png
new file mode 100644
index 0000000..7c6b9be
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow07.png
new file mode 100644
index 0000000..4ac1643
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow08.png
new file mode 100644
index 0000000..16316e2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow09.png
new file mode 100644
index 0000000..766d26e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow10.png
new file mode 100644
index 0000000..2561c6c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow11.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow11.png
new file mode 100644
index 0000000..c06ac9b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow11.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow12.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow12.png
new file mode 100644
index 0000000..45e88f6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow12.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow13.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow13.png
new file mode 100644
index 0000000..919c804
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow13.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow14.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow14.png
new file mode 100644
index 0000000..bc0fb52
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow14.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow15.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow15.png
new file mode 100644
index 0000000..4c0b6b8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow15.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow16.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow16.png
new file mode 100644
index 0000000..aba69c3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Shadow16.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword01.png
new file mode 100644
index 0000000..b622967
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword02.png
new file mode 100644
index 0000000..3b18e0b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword03.png
new file mode 100644
index 0000000..b6a8ac6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword04.png
new file mode 100644
index 0000000..7c7eb3a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword05.png
new file mode 100644
index 0000000..c9442d9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword06.png
new file mode 100644
index 0000000..42ad806
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword07.png
new file mode 100644
index 0000000..9715a63
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword08.png
new file mode 100644
index 0000000..63f2b3b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword09.png
new file mode 100644
index 0000000..4bdcac9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword10.png
new file mode 100644
index 0000000..84eecc2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword15.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword15.png
new file mode 100644
index 0000000..633e1f1
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword15.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword16.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword16.png
new file mode 100644
index 0000000..afbd888
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword16.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword17.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword17.png
new file mode 100644
index 0000000..4446660
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword17.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword18.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword18.png
new file mode 100644
index 0000000..51db6e6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword18.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword19.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword19.png
new file mode 100644
index 0000000..7ab10fa
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword19.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword20.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword20.png
new file mode 100644
index 0000000..24da837
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword20.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword21.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword21.png
new file mode 100644
index 0000000..a7c5f85
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Sword21.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder01.png
new file mode 100644
index 0000000..fc5d4a0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder02.png
new file mode 100644
index 0000000..9e6f8b1
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder03.png
new file mode 100644
index 0000000..8de3602
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder04.png
new file mode 100644
index 0000000..aabfdc5
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder05.png
new file mode 100644
index 0000000..c6f188b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder06.png
new file mode 100644
index 0000000..6f78391
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder07.png
new file mode 100644
index 0000000..d5f060a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Thunder07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water01.png
new file mode 100644
index 0000000..b22552b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water02.png
new file mode 100644
index 0000000..bfb3be3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water03.png
new file mode 100644
index 0000000..5e75fd0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water04.png
new file mode 100644
index 0000000..3c17bc6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water05.png
new file mode 100644
index 0000000..bde5b06
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water06.png
new file mode 100644
index 0000000..af68390
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water07.png
new file mode 100644
index 0000000..a4480fa
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Water07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind01.png
new file mode 100644
index 0000000..90c8da9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind02.png
new file mode 100644
index 0000000..58562fc
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind03.png
new file mode 100644
index 0000000..dfd94b3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind04.png
new file mode 100644
index 0000000..6d92970
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind05.png
new file mode 100644
index 0000000..1ec6795
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind06.png
new file mode 100644
index 0000000..428c5f9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind07.png
new file mode 100644
index 0000000..14c98eb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/S_Wind07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe001.png
new file mode 100644
index 0000000..74736f9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe002.png
new file mode 100644
index 0000000..9175970
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe003.png
new file mode 100644
index 0000000..a608c34
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe004.png
new file mode 100644
index 0000000..c27096d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe005.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe005.png
new file mode 100644
index 0000000..1aff856
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe005.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe006.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe006.png
new file mode 100644
index 0000000..d9f7bdf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe006.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe007.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe007.png
new file mode 100644
index 0000000..2e5258f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe007.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe008.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe008.png
new file mode 100644
index 0000000..d43b522
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe008.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe009.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe009.png
new file mode 100644
index 0000000..dbf377e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe009.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe010.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe010.png
new file mode 100644
index 0000000..e06c5ee
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe010.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe011.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe011.png
new file mode 100644
index 0000000..51d162d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe011.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe012.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe012.png
new file mode 100644
index 0000000..59827c2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe012.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe013.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe013.png
new file mode 100644
index 0000000..a510713
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe013.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe014.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe014.png
new file mode 100644
index 0000000..80d5ff7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Axe014.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book01.png
new file mode 100644
index 0000000..d8c3c56
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book02.png
new file mode 100644
index 0000000..bfb1fc8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book03.png
new file mode 100644
index 0000000..51ca4f3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book04.png
new file mode 100644
index 0000000..0c2f552
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book05.png
new file mode 100644
index 0000000..517ba90
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book06.png
new file mode 100644
index 0000000..5bd2771
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book07.png
new file mode 100644
index 0000000..e6f06d2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Book07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow01.png
new file mode 100644
index 0000000..e2297da
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow02.png
new file mode 100644
index 0000000..eb09d1b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow03.png
new file mode 100644
index 0000000..7c33cf6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow04.png
new file mode 100644
index 0000000..de3d425
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow05.png
new file mode 100644
index 0000000..46fc8b0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow06.png
new file mode 100644
index 0000000..d8bc8f4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow07.png
new file mode 100644
index 0000000..f69f86d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow08.png
new file mode 100644
index 0000000..9297e18
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow09.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow09.png
new file mode 100644
index 0000000..2ae45c6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow09.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow10.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow10.png
new file mode 100644
index 0000000..cbe2721
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow10.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow11.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow11.png
new file mode 100644
index 0000000..ff23a22
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow11.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow12.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow12.png
new file mode 100644
index 0000000..cbd27fd
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow12.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow13.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow13.png
new file mode 100644
index 0000000..2b1c252
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow13.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow14.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow14.png
new file mode 100644
index 0000000..26f9245
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow14.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow15.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow15.png
new file mode 100644
index 0000000..f94b509
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow15.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow16.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow16.png
new file mode 100644
index 0000000..2c30f28
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow16.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow17.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow17.png
new file mode 100644
index 0000000..b481fb3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Bow17.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger001.png
new file mode 100644
index 0000000..f6e2dab
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger002.png
new file mode 100644
index 0000000..7e4c8dd
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger003.png
new file mode 100644
index 0000000..d21f790
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger004.png
new file mode 100644
index 0000000..4454d0d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger005.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger005.png
new file mode 100644
index 0000000..a2b8c7c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger005.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger006.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger006.png
new file mode 100644
index 0000000..d3f753f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger006.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger007.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger007.png
new file mode 100644
index 0000000..0d04e59
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger007.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger008.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger008.png
new file mode 100644
index 0000000..3274ef0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger008.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger009.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger009.png
new file mode 100644
index 0000000..62e38cc
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger009.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger010.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger010.png
new file mode 100644
index 0000000..577ba4f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger010.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger011.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger011.png
new file mode 100644
index 0000000..b92832e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger011.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger012.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger012.png
new file mode 100644
index 0000000..94b03ff
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger012.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger013.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger013.png
new file mode 100644
index 0000000..3c97ef3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger013.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger014.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger014.png
new file mode 100644
index 0000000..0ee7dd8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger014.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger015.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger015.png
new file mode 100644
index 0000000..c3fb038
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger015.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger016.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger016.png
new file mode 100644
index 0000000..bc5dd24
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger016.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger017.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger017.png
new file mode 100644
index 0000000..7894e62
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger017.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger018.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger018.png
new file mode 100644
index 0000000..765e02b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger018.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger019.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger019.png
new file mode 100644
index 0000000..aecb1bc
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger019.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger020.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger020.png
new file mode 100644
index 0000000..59d6a66
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger020.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger021.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger021.png
new file mode 100644
index 0000000..453af68
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Dagger021.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist001.png
new file mode 100644
index 0000000..d673544
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist002.png
new file mode 100644
index 0000000..bd5166b
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist003.png
new file mode 100644
index 0000000..3cc044e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist004.png
new file mode 100644
index 0000000..df25dc3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist005.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist005.png
new file mode 100644
index 0000000..ad779b2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Fist005.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Axe.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Axe.png
new file mode 100644
index 0000000..c236ed9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Axe.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Bow.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Bow.png
new file mode 100644
index 0000000..cc9bc6c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Bow.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Dagger.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Dagger.png
new file mode 100644
index 0000000..8871684
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Dagger.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Mace.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Mace.png
new file mode 100644
index 0000000..5e7d63e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Mace.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Spear.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Spear.png
new file mode 100644
index 0000000..3c20113
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Spear.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Sword.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Sword.png
new file mode 100644
index 0000000..cde8cb9
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gold_Sword.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun001.png
new file mode 100644
index 0000000..76ede7d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun002.png
new file mode 100644
index 0000000..282701d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun003.png
new file mode 100644
index 0000000..11d750a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Gun003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace001.png
new file mode 100644
index 0000000..577051e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace002.png
new file mode 100644
index 0000000..54a80e0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace003.png
new file mode 100644
index 0000000..8b961b1
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace004.png
new file mode 100644
index 0000000..81c9658
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace005.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace005.png
new file mode 100644
index 0000000..1061ea7
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace005.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace006.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace006.png
new file mode 100644
index 0000000..47bb935
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace006.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace007.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace007.png
new file mode 100644
index 0000000..e220de8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace007.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace008.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace008.png
new file mode 100644
index 0000000..01ccac4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace008.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace009.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace009.png
new file mode 100644
index 0000000..ab66259
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace009.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace010.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace010.png
new file mode 100644
index 0000000..dd34c78
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace010.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace011.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace011.png
new file mode 100644
index 0000000..81eb6fb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace011.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace012.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace012.png
new file mode 100644
index 0000000..76f5dea
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace012.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace013.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace013.png
new file mode 100644
index 0000000..184e3c3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace013.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace014.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace014.png
new file mode 100644
index 0000000..401c554
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace014.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace15.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace15.png
new file mode 100644
index 0000000..1b478fa
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace15.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace16.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace16.png
new file mode 100644
index 0000000..8c08f8d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Mace16.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear001.png
new file mode 100644
index 0000000..e707e97
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear002.png
new file mode 100644
index 0000000..785045e
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear003.png
new file mode 100644
index 0000000..3bba345
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear004.png
new file mode 100644
index 0000000..a755b9a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear005.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear005.png
new file mode 100644
index 0000000..dfe9464
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear005.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear006.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear006.png
new file mode 100644
index 0000000..64bbb66
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear006.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear007.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear007.png
new file mode 100644
index 0000000..a2fee6d
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear007.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear008.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear008.png
new file mode 100644
index 0000000..5baf456
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear008.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear009.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear009.png
new file mode 100644
index 0000000..5c364ea
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear009.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear010.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear010.png
new file mode 100644
index 0000000..289ed41
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear010.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear011.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear011.png
new file mode 100644
index 0000000..c45b3b0
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear011.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear012.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear012.png
new file mode 100644
index 0000000..64eec76
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear012.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear013.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear013.png
new file mode 100644
index 0000000..5a457d8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear013.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear014.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear014.png
new file mode 100644
index 0000000..588fac6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Spear014.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff01.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff01.png
new file mode 100644
index 0000000..37b6d88
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff01.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff02.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff02.png
new file mode 100644
index 0000000..24c6dbf
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff02.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff03.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff03.png
new file mode 100644
index 0000000..de68131
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff03.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff04.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff04.png
new file mode 100644
index 0000000..c6f9d15
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff04.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff05.png
new file mode 100644
index 0000000..7e073ad
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff05.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff06.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff06.png
new file mode 100644
index 0000000..061e5cb
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff06.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff07.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff07.png
new file mode 100644
index 0000000..8a9e7d8
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff07.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff08.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff08.png
new file mode 100644
index 0000000..6e31d2f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Staff08.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword001.png
new file mode 100644
index 0000000..9d0bd7c
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword002.png
new file mode 100644
index 0000000..757e087
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword003.png
new file mode 100644
index 0000000..1eba7ad
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword004.png
new file mode 100644
index 0000000..7939ed2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword005.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword005.png
new file mode 100644
index 0000000..5c81410
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword005.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword006.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword006.png
new file mode 100644
index 0000000..09c059a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword006.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword007.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword007.png
new file mode 100644
index 0000000..b4bb849
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword007.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword008.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword008.png
new file mode 100644
index 0000000..8dfb408
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword008.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword009.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword009.png
new file mode 100644
index 0000000..ab11cb4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword009.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword010.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword010.png
new file mode 100644
index 0000000..8fe6b6f
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword010.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword011.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword011.png
new file mode 100644
index 0000000..05af7f4
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword011.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword012.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword012.png
new file mode 100644
index 0000000..317a8c2
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword012.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword013.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword013.png
new file mode 100644
index 0000000..582d66a
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword013.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword014.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword014.png
new file mode 100644
index 0000000..f649fac
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword014.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword015.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword015.png
new file mode 100644
index 0000000..0225ee3
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword015.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword016.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword016.png
new file mode 100644
index 0000000..e304e66
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword016.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword017.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword017.png
new file mode 100644
index 0000000..63d30dc
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword017.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword018.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword018.png
new file mode 100644
index 0000000..2725cd1
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword018.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword019.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword019.png
new file mode 100644
index 0000000..dc33c37
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword019.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword020.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword020.png
new file mode 100644
index 0000000..4e93215
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword020.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword021.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword021.png
new file mode 100644
index 0000000..81f7e10
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword021.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword022.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword022.png
new file mode 100644
index 0000000..98afed6
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Sword022.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw001.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw001.png
new file mode 100644
index 0000000..b342b07
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw001.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw002.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw002.png
new file mode 100644
index 0000000..edceccd
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw002.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw003.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw003.png
new file mode 100644
index 0000000..987e344
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw003.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw004.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw004.png
new file mode 100644
index 0000000..6a419de
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw004.png differ
diff --git a/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw05.png b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw05.png
new file mode 100644
index 0000000..4c37fac
Binary files /dev/null and b/apps/web-demo/assets-src/items/7soul-rpg-icons/W_Throw05.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/acorn.png b/apps/web-demo/assets-src/items/idylwild-inventory/acorn.png
new file mode 100644
index 0000000..10f1c49
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/acorn.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/apple.png b/apps/web-demo/assets-src/items/idylwild-inventory/apple.png
new file mode 100644
index 0000000..d6c7b77
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/apple.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/arrow.png b/apps/web-demo/assets-src/items/idylwild-inventory/arrow.png
new file mode 100644
index 0000000..8486bce
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/arrow.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/basket.png b/apps/web-demo/assets-src/items/idylwild-inventory/basket.png
new file mode 100644
index 0000000..43c1260
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/basket.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/board.png b/apps/web-demo/assets-src/items/idylwild-inventory/board.png
new file mode 100644
index 0000000..2c1d1a9
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/board.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/bone.png b/apps/web-demo/assets-src/items/idylwild-inventory/bone.png
new file mode 100644
index 0000000..6497aba
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/bone.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/bonemeal.png b/apps/web-demo/assets-src/items/idylwild-inventory/bonemeal.png
new file mode 100644
index 0000000..0540b7d
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/bonemeal.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/book.png b/apps/web-demo/assets-src/items/idylwild-inventory/book.png
new file mode 100644
index 0000000..289109c
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/book.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/bread.png b/apps/web-demo/assets-src/items/idylwild-inventory/bread.png
new file mode 100644
index 0000000..8f03c02
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/bread.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/bucket.png b/apps/web-demo/assets-src/items/idylwild-inventory/bucket.png
new file mode 100644
index 0000000..d12e755
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/bucket.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/chain.png b/apps/web-demo/assets-src/items/idylwild-inventory/chain.png
new file mode 100644
index 0000000..ddd90d7
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/chain.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/cloth.png b/apps/web-demo/assets-src/items/idylwild-inventory/cloth.png
new file mode 100644
index 0000000..7e7c0b0
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/cloth.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/copper_ingot.png b/apps/web-demo/assets-src/items/idylwild-inventory/copper_ingot.png
new file mode 100644
index 0000000..c3c571a
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/copper_ingot.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/copper_ore.png b/apps/web-demo/assets-src/items/idylwild-inventory/copper_ore.png
new file mode 100644
index 0000000..9719ef6
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/copper_ore.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/copper_rod.png b/apps/web-demo/assets-src/items/idylwild-inventory/copper_rod.png
new file mode 100644
index 0000000..7a54cf0
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/copper_rod.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/egg.png b/apps/web-demo/assets-src/items/idylwild-inventory/egg.png
new file mode 100644
index 0000000..ab35b05
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/egg.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/gold_ingot.png b/apps/web-demo/assets-src/items/idylwild-inventory/gold_ingot.png
new file mode 100644
index 0000000..e9bbb8d
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/gold_ingot.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/gold_key.png b/apps/web-demo/assets-src/items/idylwild-inventory/gold_key.png
new file mode 100644
index 0000000..589743c
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/gold_key.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/gold_ore.png b/apps/web-demo/assets-src/items/idylwild-inventory/gold_ore.png
new file mode 100644
index 0000000..540cec5
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/gold_ore.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/grass.png b/apps/web-demo/assets-src/items/idylwild-inventory/grass.png
new file mode 100644
index 0000000..5239a73
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/grass.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/herb.png b/apps/web-demo/assets-src/items/idylwild-inventory/herb.png
new file mode 100644
index 0000000..6394ba0
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/herb.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/inkpot.png b/apps/web-demo/assets-src/items/idylwild-inventory/inkpot.png
new file mode 100644
index 0000000..fd34233
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/inkpot.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/inventory.png b/apps/web-demo/assets-src/items/idylwild-inventory/inventory.png
new file mode 100644
index 0000000..bf31d98
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/inventory.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/inventory_ase.ase b/apps/web-demo/assets-src/items/idylwild-inventory/inventory_ase.ase
new file mode 100644
index 0000000..b6f0905
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/inventory_ase.ase differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/iron_ingot.png b/apps/web-demo/assets-src/items/idylwild-inventory/iron_ingot.png
new file mode 100644
index 0000000..ea8eeda
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/iron_ingot.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/iron_ore.png b/apps/web-demo/assets-src/items/idylwild-inventory/iron_ore.png
new file mode 100644
index 0000000..2e9875a
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/iron_ore.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/iron_pickaxe.png b/apps/web-demo/assets-src/items/idylwild-inventory/iron_pickaxe.png
new file mode 100644
index 0000000..1959d5d
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/iron_pickaxe.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/leather.png b/apps/web-demo/assets-src/items/idylwild-inventory/leather.png
new file mode 100644
index 0000000..9c5d814
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/leather.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/log.png b/apps/web-demo/assets-src/items/idylwild-inventory/log.png
new file mode 100644
index 0000000..41aa21e
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/log.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/mug.png b/apps/web-demo/assets-src/items/idylwild-inventory/mug.png
new file mode 100644
index 0000000..339e7d6
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/mug.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/mushroom.png b/apps/web-demo/assets-src/items/idylwild-inventory/mushroom.png
new file mode 100644
index 0000000..beb30d1
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/mushroom.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/parchment.png b/apps/web-demo/assets-src/items/idylwild-inventory/parchment.png
new file mode 100644
index 0000000..e00de27
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/parchment.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/plate.png b/apps/web-demo/assets-src/items/idylwild-inventory/plate.png
new file mode 100644
index 0000000..5965906
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/plate.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/platinum_ingot.png b/apps/web-demo/assets-src/items/idylwild-inventory/platinum_ingot.png
new file mode 100644
index 0000000..975c49b
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/platinum_ingot.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/platinum_ore.png b/apps/web-demo/assets-src/items/idylwild-inventory/platinum_ore.png
new file mode 100644
index 0000000..f2022cd
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/platinum_ore.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/quill.png b/apps/web-demo/assets-src/items/idylwild-inventory/quill.png
new file mode 100644
index 0000000..e4e2e60
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/quill.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/rawhide.png b/apps/web-demo/assets-src/items/idylwild-inventory/rawhide.png
new file mode 100644
index 0000000..c72ef75
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/rawhide.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/rope.png b/apps/web-demo/assets-src/items/idylwild-inventory/rope.png
new file mode 100644
index 0000000..8daf1ae
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/rope.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/sack.png b/apps/web-demo/assets-src/items/idylwild-inventory/sack.png
new file mode 100644
index 0000000..e32429d
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/sack.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/scroll.png b/apps/web-demo/assets-src/items/idylwild-inventory/scroll.png
new file mode 100644
index 0000000..9cd6336
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/scroll.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/silk.png b/apps/web-demo/assets-src/items/idylwild-inventory/silk.png
new file mode 100644
index 0000000..79317c9
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/silk.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/silver_ingot.png b/apps/web-demo/assets-src/items/idylwild-inventory/silver_ingot.png
new file mode 100644
index 0000000..9bd8d33
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/silver_ingot.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/silver_ore.png b/apps/web-demo/assets-src/items/idylwild-inventory/silver_ore.png
new file mode 100644
index 0000000..a7adbc0
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/silver_ore.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/silver_shovel.png b/apps/web-demo/assets-src/items/idylwild-inventory/silver_shovel.png
new file mode 100644
index 0000000..06b143b
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/silver_shovel.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/steak.png b/apps/web-demo/assets-src/items/idylwild-inventory/steak.png
new file mode 100644
index 0000000..d7f2029
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/steak.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/stick.png b/apps/web-demo/assets-src/items/idylwild-inventory/stick.png
new file mode 100644
index 0000000..614b8ad
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/stick.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/string.png b/apps/web-demo/assets-src/items/idylwild-inventory/string.png
new file mode 100644
index 0000000..e37ed76
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/string.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/thread.png b/apps/web-demo/assets-src/items/idylwild-inventory/thread.png
new file mode 100644
index 0000000..0e2ebfb
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/thread.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/torch.png b/apps/web-demo/assets-src/items/idylwild-inventory/torch.png
new file mode 100644
index 0000000..fa85f28
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/torch.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/torch_lit.png b/apps/web-demo/assets-src/items/idylwild-inventory/torch_lit.png
new file mode 100644
index 0000000..771c562
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/torch_lit.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/urn.png b/apps/web-demo/assets-src/items/idylwild-inventory/urn.png
new file mode 100644
index 0000000..e093a06
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/urn.png differ
diff --git a/apps/web-demo/assets-src/items/idylwild-inventory/wheat.png b/apps/web-demo/assets-src/items/idylwild-inventory/wheat.png
new file mode 100644
index 0000000..51f5cff
Binary files /dev/null and b/apps/web-demo/assets-src/items/idylwild-inventory/wheat.png differ
diff --git a/apps/web-demo/demo-content/characters/david.ts b/apps/web-demo/demo-content/characters/david.ts
new file mode 100644
index 0000000..12c98b7
--- /dev/null
+++ b/apps/web-demo/demo-content/characters/david.ts
@@ -0,0 +1,43 @@
+// David, the demo's playable character. Pass it to the runtime:
+//
+// Demo content: NOT part of the engine packages.
+import {
+ buildFrameUrls,
+ type CharacterDefinition,
+} from "@pointclick-engine/engine-renderer-r3f";
+
+const ROOT = "/assets/sprites/david";
+
+export const DAVID: CharacterDefinition = {
+ id: "david",
+ clips: {
+ idle: { frames: [`${ROOT}/david_idle.png`], fps: 1, loop: true },
+ north: {
+ frames: buildFrameUrls(ROOT, "david-walk-north", 9).reverse(),
+ fps: 16,
+ loop: true,
+ },
+ south: {
+ frames: buildFrameUrls(ROOT, "david-walk-south", 8, 3),
+ fps: 16,
+ loop: true,
+ },
+ west: {
+ frames: buildFrameUrls(ROOT, "david-walk-west", 9).reverse(),
+ fps: 16,
+ loop: true,
+ mirror: true,
+ },
+ east: {
+ frames: buildFrameUrls(ROOT, "david-walk-west", 9).reverse(),
+ fps: 16,
+ loop: true,
+ },
+ },
+ speaking: {
+ frames: buildFrameUrls(ROOT, "david_speaking", 8),
+ fps: 8,
+ loop: true,
+ },
+ size: [1.4, 2.94],
+};
diff --git a/apps/web-demo/demo-content/characters/guide.ts b/apps/web-demo/demo-content/characters/guide.ts
new file mode 100644
index 0000000..11ba302
--- /dev/null
+++ b/apps/web-demo/demo-content/characters/guide.ts
@@ -0,0 +1,14 @@
+// El guia de `town`: reutiliza el sprite de David con otro id de personaje.
+// Demo content: NOT part of the engine packages.
+import type { CharacterDefinition } from "@pointclick-engine/engine-renderer-r3f";
+
+import { DAVID } from "./david";
+import { HELIX } from "./helix";
+
+/** Personajes de los NPCs de la demo por `characterId` (prop `characters` del viewport). */
+export const GUIDE: CharacterDefinition = { ...DAVID, id: "guide" };
+
+export const DEMO_NPC_CHARACTERS: Record = {
+ [GUIDE.id]: GUIDE,
+ [HELIX.id]: HELIX,
+};
diff --git a/apps/web-demo/demo-content/characters/helix.ts b/apps/web-demo/demo-content/characters/helix.ts
new file mode 100644
index 0000000..70979c9
--- /dev/null
+++ b/apps/web-demo/demo-content/characters/helix.ts
@@ -0,0 +1,23 @@
+// Helix: NPC de la escena de pruebas `sciFiLab`.
+// Arte: "8 Directional 2D Point and Click Male Character", de DeMoNiCaTeD (CC-BY-SA 4.0).
+// Frames recortados y escalados x4 desde la hoja original; ver `public/assets/LICENSES-art.md`.
+// Demo content: NOT part of the engine packages.
+import {
+ buildFrameUrls,
+ type CharacterDefinition,
+} from "@pointclick-engine/engine-renderer-r3f";
+
+const ROOT = "/assets/sprites/helix";
+
+export const HELIX: CharacterDefinition = {
+ id: "helix",
+ clips: {
+ idle: { frames: [`${ROOT}/helix_idle.png`], fps: 1, loop: true },
+ north: { frames: buildFrameUrls(ROOT, "helix-walk-north", 8), fps: 10, loop: true },
+ south: { frames: buildFrameUrls(ROOT, "helix-walk-south", 8), fps: 10, loop: true },
+ west: { frames: buildFrameUrls(ROOT, "helix-walk-east", 8), fps: 10, loop: true, mirror: true },
+ east: { frames: buildFrameUrls(ROOT, "helix-walk-east", 8), fps: 10, loop: true },
+ },
+ // La hoja no trae clip de habla: mientras habla se queda en reposo.
+ size: [1.4, 2.94],
+};
diff --git a/apps/web-demo/demo-content/content.test.ts b/apps/web-demo/demo-content/content.test.ts
new file mode 100644
index 0000000..26c7a38
--- /dev/null
+++ b/apps/web-demo/demo-content/content.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { validateContent } from "@pointclick-engine/engine-core";
+
+import { DEMO_RUNTIME_CONFIG } from "../app/lib/engine/runtime/demoViewportOptions";
+
+describe("contenido de la demo", () => {
+ it("pasa validateContent sin errores", () => {
+ const issues = validateContent({
+ scenes: DEMO_RUNTIME_CONFIG.scenes ?? [],
+ items: DEMO_RUNTIME_CONFIG.items ?? [],
+ ...(DEMO_RUNTIME_CONFIG.dialogues ? { dialogues: DEMO_RUNTIME_CONFIG.dialogues } : {}),
+ ...(DEMO_RUNTIME_CONFIG.dialogKeys ? { dialogKeys: DEMO_RUNTIME_CONFIG.dialogKeys } : {}),
+ });
+ const errors = issues.filter((i) => i.severity === "error");
+ expect(errors).toEqual([]);
+ });
+});
diff --git a/apps/web-demo/demo-content/dialogs/index.ts b/apps/web-demo/demo-content/dialogs/index.ts
index d568dbf..48441f1 100644
--- a/apps/web-demo/demo-content/dialogs/index.ts
+++ b/apps/web-demo/demo-content/dialogs/index.ts
@@ -34,6 +34,10 @@ export const demoDictionaries: LocaleDictionaries = {
"¡Bienvenido! Aquí puedes ser tú mismo, o alguien más.",
],
},
+ // Frase fija (antes un texto en codigo, siempre en castellano): se conserva igual en ambos idiomas.
+ personalRoomLeaveBlocked: {
+ phrases: ["Sería mejor recoger todo lo que pueda del cuarto antes de irme..."],
+ },
inventoryDropHit: {
phrases: [
"¡Exacto! El Gameboy va ahí.",
@@ -210,6 +214,39 @@ export const demoDictionaries: LocaleDictionaries = {
"Mira eso. Todo en su sitio. No suele pasar.",
],
},
+ // --- Contenido de prueba (16b): guia de la plaza, ordenador y llave ---
+ // Textos del motor para hotspots (verbos del menu y frase generica). Se definen aqui, y no
+ // se dejan a `ensureEngineTexts`, porque el menu calcula sus etiquetas en el primer render.
+ "engine.verb.look": { phrases: ["Mirar"] },
+ "engine.verb.use": { phrases: ["Usar"] },
+ "engine.verb.talk": { phrases: ["Hablar"] },
+ "engine.hotspot.noAction": { phrases: ["No sé qué hacer con eso."] },
+ "helix.name": { phrases: ["Helix"] },
+ "helix.hello": { phrases: ["Soy de otro juego. Me han dejado aquí de prueba y nadie ha venido a recogerme."] },
+ "guide.name": { phrases: ["Guía"] },
+ "guide.hello": { phrases: ["¡Eh, forastero! Pareces perdido. ¿Te echo una mano?"] },
+ "guide.c.trophy": { phrases: ["Mira, llevo un trofeo."] },
+ "guide.c.who": { phrases: ["¿Quién eres?"] },
+ "guide.c.help": { phrases: ["¿Puedes ayudarme?"] },
+ "guide.c.bye": { phrases: ["Hasta luego."] },
+ "guide.who": { phrases: ["Soy el guía de la plaza. Conozco cada rincón, menos la mina: sigue cerrada."] },
+ "guide.trophy": { phrases: ["¡Menudo trofeo! Si lo dejas en la peana de la plaza pasarán cosas."] },
+ "guide.help": { phrases: ["Toma, el mango de una llave rota. El paletón debe de andar tirado por la plaza."] },
+ "guide.bye": { phrases: ["Cuídate, forastero."] },
+ "hotspot.computer.name": { phrases: ["Ordenador"] },
+ "computer.look": { phrases: ["Mi ordenador de siempre. Aún tiene el salvapantallas de los tubos."] },
+ "computer.use": { phrases: ["Pide una contraseña. Seguro que es 1234... o no."] },
+ "computer.use.after": { phrases: ["Ni con la Gameboy a cuestas me deja entrar."] },
+ "computer.gameboy": { phrases: ["La Gameboy no tiene ningún puerto que encaje con el ordenador."] },
+ "computer.nothing": { phrases: ["Eso no tiene nada que ver con el ordenador."] },
+ "item.key-handle.description": { phrases: ["El mango de una llave rota. Le falta el paletón."] },
+ "item.key-bit.description": { phrases: ["El paletón de una llave rota. Le falta el mango."] },
+ "item.bronze-key.description": { phrases: ["Una llave de bronce, entera de nuevo. Quizá abra la mina... o no."] },
+ "item.key-part.drop.default.miss": { phrases: ["Aquí no hace nada. Lo guardo otra vez."] },
+ "combine.key.done": { phrases: ["Mango y paletón encajan: ¡una llave de bronce entera!"] },
+ inventoryCombineFailed: {
+ phrases: ["Eso no se puede combinar con eso.", "No encajan. Cada cosa vuelve a su sitio."],
+ },
// --- Intro ---
"intro.text": {
phrases: [
@@ -267,6 +304,10 @@ export const demoDictionaries: LocaleDictionaries = {
"Welcome! Be yourself here, or someone else.",
],
},
+ // Frase fija (antes un texto en codigo, siempre en castellano): se conserva igual en ambos idiomas.
+ personalRoomLeaveBlocked: {
+ phrases: ["Sería mejor recoger todo lo que pueda del cuarto antes de irme..."],
+ },
inventoryDropHit: {
phrases: [
"Perfect. The Gameboy goes there.",
@@ -443,6 +484,38 @@ export const demoDictionaries: LocaleDictionaries = {
"Look at that. Everything in its place. Doesn't happen often.",
],
},
+ // --- Test content (16b): town guide, computer and key ---
+ // Engine texts for hotspots (menu verbs and generic phrase); see the "es" block.
+ "engine.verb.look": { phrases: ["Look"] },
+ "engine.verb.use": { phrases: ["Use"] },
+ "engine.verb.talk": { phrases: ["Talk"] },
+ "engine.hotspot.noAction": { phrases: ["I don't know what to do with that."] },
+ "helix.name": { phrases: ["Helix"] },
+ "helix.hello": { phrases: ["I am from another game. They left me here as a test and nobody came back for me."] },
+ "guide.name": { phrases: ["Guide"] },
+ "guide.hello": { phrases: ["Hey, stranger! You look lost. Need a hand?"] },
+ "guide.c.trophy": { phrases: ["Look, I'm carrying a trophy."] },
+ "guide.c.who": { phrases: ["Who are you?"] },
+ "guide.c.help": { phrases: ["Can you help me?"] },
+ "guide.c.bye": { phrases: ["See you later."] },
+ "guide.who": { phrases: ["I'm the town guide. I know every corner except the mine: it's still closed."] },
+ "guide.trophy": { phrases: ["What a trophy! Put it on the pedestal in the square and things will happen."] },
+ "guide.help": { phrases: ["Here, the handle of a broken key. The bit must be lying around the square."] },
+ "guide.bye": { phrases: ["Take care, stranger."] },
+ "hotspot.computer.name": { phrases: ["Computer"] },
+ "computer.look": { phrases: ["My trusty computer. It still has the pipes screensaver."] },
+ "computer.use": { phrases: ["It asks for a password. Surely it's 1234... or not."] },
+ "computer.use.after": { phrases: ["Even carrying the Gameboy it won't let me in."] },
+ "computer.gameboy": { phrases: ["The Gameboy has no port that fits the computer."] },
+ "computer.nothing": { phrases: ["That has nothing to do with the computer."] },
+ "item.key-handle.description": { phrases: ["The handle of a broken key. The bit is missing."] },
+ "item.key-bit.description": { phrases: ["The bit of a broken key. The handle is missing."] },
+ "item.bronze-key.description": { phrases: ["A bronze key, whole again. Maybe it opens the mine... or not."] },
+ "item.key-part.drop.default.miss": { phrases: ["It does nothing here. Putting it away."] },
+ "combine.key.done": { phrases: ["Handle and bit fit: a whole bronze key!"] },
+ inventoryCombineFailed: {
+ phrases: ["Those can't be combined.", "They don't fit together. Each thing goes back."],
+ },
// --- Intro ---
"intro.text": {
phrases: [
diff --git a/apps/web-demo/demo-content/dialogues/guide.ts b/apps/web-demo/demo-content/dialogues/guide.ts
new file mode 100644
index 0000000..4a65ccf
--- /dev/null
+++ b/apps/web-demo/demo-content/dialogues/guide.ts
@@ -0,0 +1,40 @@
+// Conversacion de prueba con el guia de `town` (contenido de la demo, no del motor).
+//
+// Cubre: una opcion condicionada a tener el trofeo, opciones `once` y un efecto que pone un
+// flag y entrega un item (`key-handle`, que se combina con `key-bit`).
+import { act, cond, dialogue, type DialogueDefinition } from "@pointclick-engine/engine-core";
+
+export const GUIDE_DIALOGUE_ID = "guide-talk";
+
+export const guideDialogue: DialogueDefinition = dialogue.define(
+ GUIDE_DIALOGUE_ID,
+ "root",
+ dialogue.node("root", {
+ speaker: "guide",
+ line: "guide.hello",
+ choices: [
+ // 0: solo si se lleva el trofeo encima.
+ dialogue.choice("guide.c.trophy", {
+ when: cond.hasItem("trophy"),
+ do: [act.setFlag("guide.trophyShown")],
+ next: "trophy",
+ }),
+ // 1: una sola vez.
+ dialogue.choice("guide.c.who", { once: true, next: "who" }),
+ // 2: una sola vez; pone un flag y entrega el mango de la llave.
+ dialogue.choice("guide.c.help", {
+ once: true,
+ do: [act.setFlag("guide.helped"), act.giveItem("key-handle")],
+ next: "help",
+ }),
+ // 3: despedida.
+ dialogue.choice("guide.c.bye", { next: "bye" }),
+ ],
+ }),
+ dialogue.node("who", { speaker: "guide", line: "guide.who", next: "root" }),
+ dialogue.node("trophy", { speaker: "guide", line: "guide.trophy", next: "root" }),
+ dialogue.node("help", { speaker: "guide", line: "guide.help", next: "root" }),
+ dialogue.node("bye", { speaker: "guide", line: "guide.bye" }),
+);
+
+export const demoDialogues: DialogueDefinition[] = [guideDialogue];
diff --git a/apps/web-demo/demo-content/items/index.ts b/apps/web-demo/demo-content/items/index.ts
index 645b9fa..915474f 100644
--- a/apps/web-demo/demo-content/items/index.ts
+++ b/apps/web-demo/demo-content/items/index.ts
@@ -1,3 +1,5 @@
+import { act, otherwise } from "@pointclick-engine/engine-core";
+
import type { ItemDefinition, ItemInteractionRule } from "./types";
export type { ItemDefinition, ItemInteractionRule };
@@ -8,6 +10,7 @@ export const ITEMS: Record = {
name: "Gameboy",
spriteUrl: "/assets/gameboy/gameboy.png",
descriptionDialogKey: "item.gameboy.description",
+ pickupSoundUrl: "/assets/audio/sfx/pickup-gameboy.ogg",
interactionRules: {
"personal-room-gameboy-drop-target": {
outcome: "place",
@@ -74,6 +77,46 @@ export const ITEMS: Record = {
missDialogKey: "item.trophy.drop.default.miss",
},
},
+ // --- Combinacion de prueba: mango + paleton dan una llave de bronce (reutilizan el sprite de la llave) ---
+ // Mango: lo entrega el guia de `town` al hablar con el (opcion `once` del dialogo).
+ "key-handle": {
+ id: "key-handle",
+ name: "Mango roto",
+ spriteUrl: "/assets/key/gold-key.png",
+ descriptionDialogKey: "item.key-handle.description",
+ interactionRules: {},
+ defaultRule: { outcome: "return", missDialogKey: "item.key-part.drop.default.miss" },
+ // Se combina con el paleton (esta regla vale en ambos sentidos).
+ combine: {
+ "key-bit": [
+ otherwise(
+ // `say` espera a que se cierre el bocadillo: el resultado va antes que la frase.
+ act.removeItem("key-handle"),
+ act.removeItem("key-bit"),
+ act.giveItem("bronze-key"),
+ act.say("combine.key.done"),
+ ),
+ ],
+ },
+ },
+ // Paleton: esta en el suelo de `town` (initialItems).
+ "key-bit": {
+ id: "key-bit",
+ name: "Paletón roto",
+ spriteUrl: "/assets/key/gold-key.png",
+ descriptionDialogKey: "item.key-bit.description",
+ interactionRules: {},
+ defaultRule: { outcome: "return", missDialogKey: "item.key-part.drop.default.miss" },
+ },
+ // Resultado de la combinacion.
+ "bronze-key": {
+ id: "bronze-key",
+ name: "Llave de bronce",
+ spriteUrl: "/assets/key/gold-key.png",
+ descriptionDialogKey: "item.bronze-key.description",
+ interactionRules: {},
+ defaultRule: { outcome: "return", missDialogKey: "item.key-part.drop.default.miss" },
+ },
};
export function getItemDefinition(itemId: string): ItemDefinition | null {
diff --git a/apps/web-demo/demo-content/items/types.ts b/apps/web-demo/demo-content/items/types.ts
index c93c446..c7cbb13 100644
--- a/apps/web-demo/demo-content/items/types.ts
+++ b/apps/web-demo/demo-content/items/types.ts
@@ -1,23 +1,5 @@
-import type { DialogKey } from "../dialogs/types";
+import type { ItemDefinition, ItemInteractionRule } from "@pointclick-engine/engine-core";
-export type ItemDropOutcome = "consume" | "place" | "return";
+export type { ItemDefinition, ItemInteractionRule };
-export type ItemInteractionRule = {
- outcome: ItemDropOutcome;
- hitDialogKey?: DialogKey;
- missDialogKey?: DialogKey;
- placeCanPickup?: boolean;
- placeHasCollision?: boolean;
- placeCollisionHalfSize?: [number, number, number];
- pickupSuccessDialogKey?: DialogKey;
- pickupBlockedDialogKey?: DialogKey;
-};
-
-export type ItemDefinition = {
- id: string;
- name: string;
- spriteUrl: string;
- descriptionDialogKey?: DialogKey;
- interactionRules: Record;
- defaultRule: ItemInteractionRule;
-};
+export type ItemDropOutcome = ItemInteractionRule["outcome"];
diff --git a/apps/web-demo/demo-content/scenes/scenes.ts b/apps/web-demo/demo-content/scenes/scenes.ts
index 3f2880c..56dd6d2 100644
--- a/apps/web-demo/demo-content/scenes/scenes.ts
+++ b/apps/web-demo/demo-content/scenes/scenes.ts
@@ -1,86 +1,41 @@
-import type { DialogKey } from "../dialogs/types";
-import type { GameSceneTransition, SceneMusicConfig } from "@pointclick-engine/engine-core";
+import type {
+ GameScene,
+ GameSceneGround,
+ GameSceneInteractionDialogKeys,
+ GameSceneInteractionFull,
+ GameSceneInteractionHintDialogKeys,
+ GameSceneWall,
+ GameSceneWallOpening,
+} from "@pointclick-engine/engine-core";
import {
+ act,
+ branch,
+ cond,
+ otherwise,
sceneTransitionOnCollision,
sceneTransitionOnItemDrop,
sceneTransitionOnItemInteraction,
} from "@pointclick-engine/engine-core";
-export type SceneWallOpening = {
- id: string;
- /** Position in wall-local space relative to wall center */
- position: [number, number, number];
- /** Half-extents of the opening: [halfWidth, halfHeight, halfDepth] */
- halfSize: [number, number, number];
-};
+import { GUIDE_DIALOGUE_ID } from "../dialogues/guide";
-export type SceneWall = {
- position: [number, number, number];
- /** Rotation around Y axis in radians */
- rotationY?: number;
- /** Half-extents for CuboidCollider: [halfWidth, halfHeight, halfDepth] */
- halfSize: [number, number, number];
- /** Openings (doors/windows) cut into this wall */
- openings?: SceneWallOpening[];
- /** Optional texture URL for wall billboard */
- textureUrl?: string;
- /** Optional texture position offset [x, y, z] */
- texturePosition?: [number, number, number];
-};
-
-export type SceneInteractionDialogKeys = {
- hit: DialogKey;
- miss: DialogKey;
-};
-
-export type SceneInteractionHintDialogKeys = {
- /** Dialog cuando el personaje se acerca o inspecciona el target vacío (sin ítem colocado). */
- empty: DialogKey;
- /** Dialog cuando el personaje se acerca o inspecciona el target con un ítem colocado. */
- occupied: DialogKey;
-};
+// Aliases de compatibilidad: los tipos de geometria/interaccion viven en el core.
+export type SceneWallOpening = GameSceneWallOpening;
+export type SceneWall = GameSceneWall;
+export type SceneInteractionDialogKeys = GameSceneInteractionDialogKeys;
+export type SceneInteractionHintDialogKeys = GameSceneInteractionHintDialogKeys;
+export type SceneGround = GameSceneGround;
-export type SceneInteraction = {
- id: string;
- kind: "drop-target";
- /** World-space center position [x, y, z] */
- position: [number, number, number];
- /** Rotation around Y axis in radians */
- rotationY?: number;
- /** Half-extents for CuboidCollider: [halfWidth, halfHeight, halfDepth] */
- halfSize: [number, number, number];
- /** If true, character collides and cannot pass through this interaction */
- hasCollision?: boolean;
+/** Interaccion de la demo: el tipo del core mas campos exclusivos de la demo. */
+export type DemoSceneInteraction = GameSceneInteractionFull & {
/**
* Suppress the default drop-target visual (cylinder + box). Use when
* another renderer (e.g. SceneDoors) already shows the interactable
* surface. The pick volume + drop logic remain active.
*/
invisible?: boolean;
- /** Item ids accepted by this interaction. If omitted, any item can be accepted. */
- acceptsItemIds?: string[];
- dialogKeys: SceneInteractionDialogKeys;
- /**
- * Diálogos de pista por proximidad/inspección.
- * Si está presente se muestran cuando el personaje se acerca mucho
- * o hace click sobre el target sin arrastrar un ítem.
- */
- hintDialogKeys?: SceneInteractionHintDialogKeys;
- label: string;
-};
-
-export type SceneGround = {
- /** Límite izquierdo (X negativo) */
- minX: number;
- /** Límite derecho (X positivo) */
- maxX: number;
- /** Límite trasero/lejano (Z negativo) */
- minZ: number;
- /** Límite frontal/cercano (Z positivo) */
- maxZ: number;
- /** Y position of the ground plane */
- y: number;
};
+export type SceneInteraction = DemoSceneInteraction;
/**
* Door — interactive opening with two visual states driven by two full-wall
@@ -127,21 +82,13 @@ export type SceneDoor = {
showHintWhenOpen?: boolean;
};
-export type Scene = {
- id: string;
- label: string;
- background: string;
- playerSpawn: [number, number, number];
- ground: SceneGround;
- walls: SceneWall[];
- interactions: SceneInteraction[];
+/** Escena de la demo: el tipo del core mas `doors` y las interacciones extendidas. */
+export type DemoScene = Omit & {
+ interactions: DemoSceneInteraction[];
/** Optional interactive doors. */
doors?: SceneDoor[];
- /** Declarative scene transitions (collision/item-drop/item-consume). */
- transitions?: GameSceneTransition[];
- /** Optional music configuration for this scene. */
- music?: SceneMusicConfig;
};
+export type Scene = DemoScene;
export const SCENES: Record = {
town: {
@@ -162,6 +109,34 @@ export const SCENES: Record = {
fadeMs: 800,
},
walls: [],
+ // Paleton roto: esta en el suelo de la plaza (se combina con el mango que da el guia).
+ initialItems: [
+ {
+ item: {
+ id: "key-bit-ground",
+ itemId: "key-bit",
+ interactionId: "key-bit-pickup",
+ name: "Paletón roto",
+ spriteUrl: "/assets/key/gold-key.png",
+ worldPosition: [1.5, -2.4, 20.0],
+ canPickup: true,
+ hasCollision: true,
+ collisionHalfSize: [0.5, 0.8, 0.5],
+ sceneId: "town",
+ },
+ },
+ ],
+ // El guia: reutiliza el sprite de David (personaje "guide", ver `characters/guide.ts`).
+ npcs: [
+ {
+ id: "guide",
+ name: "guide.name",
+ characterId: "guide",
+ position: [-4.0, -2.1, 15.5],
+ facing: "south",
+ dialogueId: GUIDE_DIALOGUE_ID,
+ },
+ ],
interactions: [
{
id: "town-trophy-pedestal",
@@ -363,11 +338,61 @@ export const SCENES: Record = {
walls: [],
interactions: [],
},
+ // Escena de pruebas (solo desde el selector de debug): fondo "Sci Fi Level" de Jeremy Gooch
+ // (CC-BY 3.0) y el NPC Helix. Ver `public/assets/LICENSES-art.md`.
+ sciFiLab: {
+ id: "sciFiLab",
+ label: "Sci-Fi Lab",
+ background: "/assets/background/sciFiLab.jpg",
+ playerSpawn: [0, -1.1, 13.44],
+ ground: {
+ minX: -17,
+ maxX: 16.8,
+ minZ: -7.6,
+ maxZ: 69.7,
+ y: -2.05,
+ },
+ walls: [],
+ npcs: [
+ {
+ id: "helix",
+ name: "helix.name",
+ characterId: "helix",
+ position: [6, -1.1, 13.44],
+ verbs: { talk: [{ do: [{ say: "helix.hello", speaker: "helix" }] }] },
+ },
+ ],
+ interactions: [],
+ },
personalRoom: {
id: "personalRoom",
label: "Personal Room",
background: "/assets/background/personalRoom.png",
playerSpawn: [0, -1.1, 13.44],
+ // Trofeo inicial: solo si no existe ya (colocado en cualquier escena ni en el inventario).
+ // La escena se marca sembrada igualmente, de modo que no vuelve a aparecer.
+ initialItems: [
+ {
+ when: cond.all(
+ cond.not(cond.itemPlaced("trophy")),
+ cond.not(cond.hasItem("trophy")),
+ ),
+ item: {
+ id: "trophy-ground",
+ itemId: "trophy",
+ interactionId: "trophy-ground-pickup",
+ name: "Trophy",
+ spriteUrl: "/assets/trophy/trophy.png",
+ worldPosition: [5.5, -1.3, 22.0],
+ canPickup: true,
+ hasCollision: true,
+ collisionHalfSize: [0.5, 0.8, 0.5],
+ sceneId: "personalRoom",
+ },
+ },
+ ],
+ // Bienvenida: en cada entrada a la habitacion (tambien al recargar), sin flag.
+ onEnter: [otherwise(act.say("personalRoomWelcome"))],
ground: {
minX: -16.9,
maxX: 16.8,
@@ -499,6 +524,29 @@ export const SCENES: Record = {
targetSceneId: "dungeon",
spawnPosition: [1.56, -2.00, 23.80],
targetPosition: [2.21, -2.00, 7.52],
+ // No se sale a la mazmorra mientras el trofeo siga colocado en la habitacion.
+ when: cond.not(cond.itemPlaced("trophy", { inScene: "personalRoom" })),
+ blocked: [act.say("personalRoomLeaveBlocked")],
+ },
+ ],
+ // Hotspot de prueba: el ordenador del escritorio (mirar, usar y soltar el gameboy encima).
+ hotspots: [
+ {
+ id: "personal-room-computer",
+ label: "hotspot.computer.name",
+ position: [-10.6, 3.0, 10],
+ halfSize: [1.2, 1.0, 0.8],
+ verbs: {
+ look: [otherwise(act.setFlag("computer.seen"), act.say("computer.look"))],
+ use: [
+ branch(cond.flag("computer.gameboyTried"), act.say("computer.use.after")),
+ otherwise(act.say("computer.use")),
+ ],
+ },
+ useItem: {
+ gameboy: [otherwise(act.setFlag("computer.gameboyTried"), act.say("computer.gameboy"))],
+ },
+ useItemDefault: [otherwise(act.say("computer.nothing"))],
},
],
interactions: [
diff --git a/apps/web-demo/public/assets/LICENSES-art.md b/apps/web-demo/public/assets/LICENSES-art.md
new file mode 100644
index 0000000..928bc6e
--- /dev/null
+++ b/apps/web-demo/public/assets/LICENSES-art.md
@@ -0,0 +1,12 @@
+# Licencias del arte de terceros
+
+Arte de terceros que se sirve con la demo. Las fuentes sin modificar están en `apps/web-demo/assets-src/` (ver su `README.md`). El audio tiene su propio `audio/LICENSES.md`.
+
+| Archivos | Obra | Autor | Licencia | Origen | Cambios |
+|---|---|---|---|---|---|
+| `background/sciFiLab.jpg` | Sci Fi Level | Jeremy Gooch (jeremygooch.blogspot.com) | [CC-BY 3.0](https://creativecommons.org/licenses/by/3.0/) | https://opengameart.org/content/sci-fi-level | Capas de fondo y primer plano fundidas; recorte de 1495×841 px desde x=1880; convertido a JPEG |
+| `sprites/helix/*.png` | 8 Directional 2D Point and Click Male Character | DeMoNiCaTeD | [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) | https://opengameart.org/content/8-directional-2d-point-and-click-male-character | Frames recortados de la hoja (40×62 px por celda) y escalados ×4 sin suavizado |
+
+Los frames de `sprites/helix/` son una obra derivada y se distribuyen también bajo CC-BY-SA 4.0.
+
+Pendiente de documentar: el origen y la licencia de los demás fondos, del sprite de David y de los ítems (ver `docs/phases/phase-18-story-demo/assets.md`).
diff --git a/apps/web-demo/public/assets/background/sciFiLab.jpg b/apps/web-demo/public/assets/background/sciFiLab.jpg
new file mode 100644
index 0000000..c7c5312
Binary files /dev/null and b/apps/web-demo/public/assets/background/sciFiLab.jpg differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0001.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0001.png
new file mode 100644
index 0000000..3a42403
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0001.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0002.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0002.png
new file mode 100644
index 0000000..57ea150
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0002.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0003.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0003.png
new file mode 100644
index 0000000..33f76c9
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0003.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0004.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0004.png
new file mode 100644
index 0000000..c48649a
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0004.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0005.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0005.png
new file mode 100644
index 0000000..f3ab658
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0005.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0006.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0006.png
new file mode 100644
index 0000000..fb88929
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0006.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0007.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0007.png
new file mode 100644
index 0000000..ebc7916
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0007.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0008.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0008.png
new file mode 100644
index 0000000..eb336ff
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-east_0008.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0001.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0001.png
new file mode 100644
index 0000000..358fdbd
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0001.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0002.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0002.png
new file mode 100644
index 0000000..692c81d
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0002.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0003.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0003.png
new file mode 100644
index 0000000..b21d959
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0003.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0004.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0004.png
new file mode 100644
index 0000000..6cf1d00
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0004.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0005.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0005.png
new file mode 100644
index 0000000..9f36ed7
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0005.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0006.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0006.png
new file mode 100644
index 0000000..10de4ab
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0006.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0007.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0007.png
new file mode 100644
index 0000000..6c32af6
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0007.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0008.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0008.png
new file mode 100644
index 0000000..8002e3e
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-north_0008.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0001.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0001.png
new file mode 100644
index 0000000..fe22c9c
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0001.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0002.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0002.png
new file mode 100644
index 0000000..6ec3aa3
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0002.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0003.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0003.png
new file mode 100644
index 0000000..de98ddc
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0003.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0004.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0004.png
new file mode 100644
index 0000000..d31f2d7
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0004.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0005.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0005.png
new file mode 100644
index 0000000..0944600
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0005.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0006.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0006.png
new file mode 100644
index 0000000..24d2c3e
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0006.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0007.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0007.png
new file mode 100644
index 0000000..bc9379c
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0007.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0008.png b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0008.png
new file mode 100644
index 0000000..84bb581
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix-walk-south_0008.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix_idle.png b/apps/web-demo/public/assets/sprites/helix/helix_idle.png
new file mode 100644
index 0000000..434b68a
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix_idle.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix_idle_east.png b/apps/web-demo/public/assets/sprites/helix/helix_idle_east.png
new file mode 100644
index 0000000..56508e1
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix_idle_east.png differ
diff --git a/apps/web-demo/public/assets/sprites/helix/helix_idle_north.png b/apps/web-demo/public/assets/sprites/helix/helix_idle_north.png
new file mode 100644
index 0000000..73ce145
Binary files /dev/null and b/apps/web-demo/public/assets/sprites/helix/helix_idle_north.png differ
diff --git a/dev.log b/dev.log
deleted file mode 100644
index 3b6bec1..0000000
--- a/dev.log
+++ /dev/null
@@ -1,29 +0,0 @@
-
-> dev
-> npm run dev -w apps/web-demo
-
-
-> @pointclick-engine/web-demo@0.1.0 dev
-> next dev
-
-⚠ Port 3000 is in use by process 11816, using available port 3001 instead.
-▲ Next.js 16.2.6 (Turbopack)
-- Local: http://localhost:3001
-- Network: http://100.105.191.78:3001
-✓ Ready in 415ms
-⨯ Another next dev server is already running.
-
-- Local: http://localhost:3000
-- PID: 11816
-- Dir: C:\COMPARTIDO\2d-game-test\2d-game-test\apps\web-demo
-- Log: .next\dev\logs\next-development.log
-
-Run taskkill /PID 11816 /F to stop it.
-[?25h
-npm error Lifecycle script `dev` failed with error:
-npm error code 1
-npm error path C:\COMPARTIDO\2d-game-test\2d-game-test\apps\web-demo
-npm error workspace @pointclick-engine/web-demo@0.1.0
-npm error location C:\COMPARTIDO\2d-game-test\2d-game-test\apps\web-demo
-npm error command failed
-npm error command C:\WINDOWS\system32\cmd.exe /d /s /c next dev
diff --git a/docs/LIBRARY_API_CONTRACT_V1.md b/docs/LIBRARY_API_CONTRACT_V1.md
index 79fd406..c7d3e76 100644
--- a/docs/LIBRARY_API_CONTRACT_V1.md
+++ b/docs/LIBRARY_API_CONTRACT_V1.md
@@ -12,46 +12,48 @@ Este documento define qué superficie está soportada oficialmente para consumid
### 2.1 Engine public API
-Archivo fuente:
+Archivos fuente:
-- `app/lib/engine/publicApi.ts`
+- `packages/engine-core/src/game/runtime/` (runtime agnóstico; se re-exporta desde `packages/engine-core/src/index.ts`)
+- `packages/engine-renderer-r3f/src/index.ts` (viewport, hooks y componentes R3F)
+- `apps/web-demo/app/lib/engine/publicApi.ts`: barrel de compatibilidad. Re-exporta ambos paquetes con los nombres del contrato v1; ningún nombre se ha renombrado ni eliminado.
-Exports soportados:
+Exports soportados de `@pointclick-engine/engine-core`:
- Tipos de contenido:
- - `GameVec3`
- - `GameSceneGround`
- - `GameSceneWall`
+ - `GameVec3`, `GameSceneGround`, `GameSceneWall`
- `GameSceneInteractionDialogKeys`
- - `GameSceneInteraction`
- - `GameSceneConfig`
- - `GameItemDropOutcome`
- - `GameItemRule`
- - `GameItemConfig`
- - `GameRuleConfig`
- - `GameRuntimeConfig`
- - `GameRuntime`
- - `GameState`
- - `GameActions`
- - `GameRuntimeEvent`
- - `GameRuntimeEventHandler`
- - `GameViewportProps`
-- Funciones/componentes:
- - `registerScene`
- - `registerItem`
- - `registerRule`
- - `createGameRuntime`
- - `getGameState`
- - `getGameActions`
- - `useGameState`
- - `useGameActions`
- - `GameViewport`
+ - `GameSceneConfig` (incluye `transitions?` y `music?`)
+ - `GameItemDropOutcome`, `GameItemRule`, `GameItemConfig`, `GameRuleConfig`
+ - `GameRuntimeConfig`, `GameRuntime`, `GameState`, `GameActions`
+ - `GameRuntimeEvent`, `GameRuntimeEventHandler`
+ - `InventoryUIAdapter`, `DialogUIAdapter`
+- Funciones:
+ - `registerScene`, `registerItem`, `registerRule`
+ - `createGameRuntime`, `getGameRuntime`
+ - `getGameState`, `getGameActions`
+ - `toRuntimeScene`, `createInventoryRuleContext`
+- Comandos y eventos: `GameCommand`, `GameCommandType`, `GameEvent`, `GameEventType`, `GameEventHandler`.
+
+Exports soportados de `@pointclick-engine/engine-renderer-r3f`:
+
+- Tipos: `GameViewportProps`, `GameViewportViewProps`, `GameViewportController`, `GameViewportControllerOptions`, `GameViewportAudioOptions`, `CharacterDefinition`, `CharacterClip`, `CharacterDirection`.
+- Componentes: `GameViewport`, `GameViewportView`, `CharacterSprite`.
+- Hooks: `useGameState`, `useGameActions`, `useGameViewportController`, `useSceneRuntime`, `useTransitionSystem`, `useInventoryRuntime`, `useAudioSystem`.
+- Funciones: `attachAudioSystem`.
+
+Notas de la superficie:
+
+- `GameSceneInteraction` en el barrel de la demo es un alias de `GameSceneInteractionFull` del core. En `engine-core` el nombre `GameSceneInteraction` designa la interfaz base.
+- `GameActions.setScene` es `(sceneId: string) => void` (`packages/engine-core/src/game/runtime/types.ts`).
+- `GameViewportProps` = opciones de `useGameViewportController` + props de `GameViewportView` + `debug` + `onRuntimeEvent`. Todas opcionales; ver [`LIBRARY_CONSUMPTION_GUIDE.md`](LIBRARY_CONSUMPTION_GUIDE.md).
+- Superficie i18n (Fase 13): ver [`architecture/02-public-api.md`](architecture/02-public-api.md).
### 2.2 Platform adapters
Archivo fuente:
-- `app/lib/platform-web.ts`
+- `apps/web-demo/app/lib/platform-web.ts`
Puertos soportados:
@@ -72,21 +74,49 @@ Adapters y barrel soportados:
- `browserEnvironmentAdapter`
- `webPlatform`
+### 2.3 Novedades 0.5.0
+
+Solo adiciones, salvo la nota breaking.
+
+- `engine-core`: runtime agnóstico (`createGameRuntime` y registros), `scene:set` con `spawnPosition?`, `player:stop` implementado, stores `useDialogStore`, `useInventoryUiStore`, `useInventoryStateStore`, `usePlacedItemsStateStore` y persistencia por puerto (`gameStatePersistence.ts`).
+- `engine-renderer-r3f`: `GameViewport` jugable con valores por defecto, `useGameViewportController` + `GameViewportView`, `CharacterSprite` / `CharacterDefinition`, `attachAudioSystem`, y las props nuevas de `GameViewport` (`storage`, `canLeaveScene`, `getInitialPlacedItems`, `onSceneEnter`, `audio`, `character`, `children`, `overlay`, entre otras).
+- `GameSceneConfig.transitions` y `music` se conservan al registrar la escena y al ejecutar `scene:set` (`toRuntimeScene`).
+- Obsoletos (siguen exportados): `DavidSprite` y los exports de `sprite/clips.ts`.
+
+**Cambio breaking de comportamiento**: recoger un ítem viaja por el bus como `item:pickedUp`; antes llegaba como `item:dropped` con `outcome: "pickup-success"`. Quien detectaba recogidas por `item:dropped` debe pasar a `item:pickedUp`. El callback legacy `onRuntimeEvent` no cambia. Las reglas de audio solo reproducen el sonido de soltar con `outcome: "place"`.
+
+Limitaciones conocidas en 0.5.0: algunos outcomes legacy viajaban como `item:dropped` fuera del tipo; `inventory:pickup` e `inventory:drop` no tenían executor; `player:stop` no detiene el movimiento manual (sigue igual). Los dos primeros se resuelven en 0.6.0 (ver 2.4).
+
+### 2.4 Novedades 0.6.0 (sin publicar; los paquetes siguen en 0.5.0)
+
+Solo adiciones. Guía de uso: [`authoring/README.md`](authoring/README.md); modelo: [`architecture/10-narrative-model.md`](architecture/10-narrative-model.md).
+
+- `engine-core` (raíz): `cond`, `evaluateCondition`, `getConditionContext`, `act`, `branch`, `otherwise`, `pickBranch`, `dialogue`, `createSequencer`, `validateContent`, `resolveCombine`, `npcToHotspot`, `getAvailableVerbs`, `getDefaultVerb`, `isHotspotVisible`, `resolveInitialItems`, `resolveEnterScript`, `evaluateTransitionGate`, `getSceneRuleContext`, `getDeclaredScene`; tipos `Condition`, `Action`, `Script`, `Branch`, `ScriptRun`, `DialogueDefinition`, `DialogueNode`, `DialogueChoice`, `ContentIssue`, `GameContent`.
+- Tipos de contenido: `Verb`, `GameSceneHotspot`, `GameSceneNpc`, `NpcFacing`, `SceneInitialItem`; campos nuevos opcionales `hotspots`, `npcs`, `initialItems`, `onEnter` (escena), `when` y `blocked` (transición), `combine` (ítem).
+- Estado y guardado: `useWorldStateStore`, `getWorldState`, `useDialogueStore`, `useInputLockStore`, `captureSnapshot`, `applySnapshot`, `saveGame`, `loadGame`, `clearSave`, `resetGameState`, `migrateLegacySave`, `SAVE_FORMAT_VERSION`, `SAVE_STORAGE_KEY`, `GameSnapshot`.
+- Puertos: `ClockPort`, `systemClock`, `HeadlessClock`.
+- Subpath `@pointclick-engine/engine-core/testing`: `createPlaythrough`, `Playthrough`.
+- `GameRuntime`: `runScript`, `registerHandler`, `getDialogues`. `GameRuntimeConfig`: `dialogues`, `storage`, `saveKey`, `clock`, `instantWalk`, `validate`, `dialogKeys`, `handlerNames`. `DialogUIAdapter.show` recibe `speaker?`.
+- Comandos nuevos: `state:setFlag`, `state:clearFlag`, `game:save`, `game:load`, `game:reset`, `script:run`, `script:cancelAll`, `hotspot:interact`, `inventory:combine`, `dialogue:start`, `dialogue:choose`, `dialogue:advance`, `dialogue:end`. Campos opcionales nuevos: `inventory:pickup.placedItemId`, `inventory:drop.interactionId` / `hotspotId`, `dialog:trigger.speaker`.
+- Eventos nuevos: `state:flagChanged`, `game:saved`, `game:loaded`, `game:reset`, `script:started`, `script:finished`, `input:lockChanged`, `custom`, `hotspot:interacted`, `hotspot:noAction`, `dialogue:started`, `dialogue:nodeEntered`, `dialogue:choiceMade`, `dialogue:ended`, `inventory:pickupFailed`, `inventory:full`, `item:removed`, `item:combined`, `item:combineFailed`. `dialog:triggered` gana `speaker?`. `item:dropped.outcome` declara ahora todos sus valores (`rule-miss`, `unknown-item`, `on-player`, y los obsoletos `pickup-blocked`, `item-interact`).
+- `engine-renderer-r3f`: props nuevas de `GameViewport` / `GameViewportView`: `characters`, `verbMenu`, `noActionDialogKey`, `dialogueChoices`. Componentes y hooks: `VerbMenu`, `DialogueChoices`, `SceneHotspots`, `SceneNpcs`, `NpcSprite`, `useDialogue`, `useHotspotInteractions`, `useVisibleHotspots`, `useVisibleNpcs`, `ensureEngineTexts`, `ENGINE_VERB_LABEL_KEYS`, `ENGINE_NO_ACTION_KEY`.
+- Vía avanzada (siguen soportados, se evalúan después de las reglas declarativas): `canLeaveScene`, `onSceneEnter`, `getInitialPlacedItems`.
+
## 3. No soportado para consumidores externos
No se garantiza estabilidad en:
-- `app/lib/engine/runtime/*`
-- `app/lib/engine/render/*`
-- `app/lib/engine/movement/*`
-- `app/components/*`
-- `app/store/*`
+- `apps/web-demo/app/lib/engine/runtime/*` (incluye `useDoorSystem.ts`: las puertas son de la demo)
+- `apps/web-demo/app/components/*`
+- `apps/web-demo/app/store/*`
+- `packages/engine-core/src/game/runtime/executors.ts` y `registry.ts` (internos; los registros son globales de módulo)
+- Cualquier símbolo de los paquetes no listado en 2.1 o 2.3.
Estos módulos pueden cambiar internamente sin política de compatibilidad para integradores.
## 4. Reglas de consumo
-1. Consumir runtime desde `publicApi`.
+1. Consumir el runtime desde `@pointclick-engine/engine-core` y el viewport desde `@pointclick-engine/engine-renderer-r3f` (o desde el barrel `publicApi`).
2. Consumir interoperabilidad desde `platform-web`.
3. No depender de comportamiento implícito de stores internos.
4. Tratar tipos/eventos públicos como contrato de integración.
@@ -117,9 +147,10 @@ Cambios breaking (requieren plan de migración):
## 7. Validación mínima para PRs que toquen contrato
1. Actualizar este documento si cambia la superficie pública.
-2. Mantener tests de contrato de `publicApi` en verde.
+2. Mantener tests de contrato de `publicApi` en verde (`apps/web-demo/app/lib/engine/publicApi.test.ts`).
3. Mantener tests de `platform-web` en verde.
4. Ejecutar y validar:
- `npm run lint`
- `npm run test`
- `npm run build`
+5. Con la demo en marcha: `npm run smoke` (`e2e/smoke.mjs` y `e2e/smoke-minimal.mjs`).
diff --git a/docs/LIBRARY_CONSUMPTION_GUIDE.md b/docs/LIBRARY_CONSUMPTION_GUIDE.md
index 012e730..bdf30c5 100644
--- a/docs/LIBRARY_CONSUMPTION_GUIDE.md
+++ b/docs/LIBRARY_CONSUMPTION_GUIDE.md
@@ -1,173 +1,200 @@
# Library Consumption Guide
-Guía para integrar el Point & Click Game Engine en una aplicación host.
+Guía para integrar el Point & Click Game Engine en una aplicación host (paquetes 0.5.0; las novedades 0.6.0, sin publicar, se marcan como tales). Ejemplo verificable: `apps/web-demo/app/example-minimal/page.tsx`. Para escribir escenas, puzzles y diálogos: [`authoring/README.md`](authoring/README.md).
-**Estado**: v2 (post Phase 4 + Phase 5) | **Última revisión**: 2026-05-27
-
----
-
-## 1. Packages disponibles
+## 1. Paquetes
```bash
-npm install @pointclick-engine/engine-core
-npm install @pointclick-engine/engine-renderer-r3f # + peer deps (ver README del package)
+npm install @pointclick-engine/engine-core @pointclick-engine/engine-renderer-r3f
+# + peer deps del renderer (ver packages/engine-renderer-r3f/README.md)
```
-| Package | Responsabilidad |
+| Paquete | Responsabilidad |
|---------|----------------|
-| `@pointclick-engine/engine-core` | Estado, reglas, pathfinding, ports. Cero React, cero browser globals. |
-| `@pointclick-engine/engine-renderer-r3f` | Renderer React Three Fiber. `GameViewport`, `createGameRuntime`, sprites, scene primitives. |
+| `@pointclick-engine/engine-core` | Runtime agnóstico (`createGameRuntime`, registros, comandos/eventos), stores, reglas, pathfinding, puertos. Cero React. |
+| `@pointclick-engine/engine-renderer-r3f` | `GameViewport` jugable, hooks de estado, sprites y escena R3F. Depende del core. |
----
+El runtime vive en `packages/engine-core/src/game/runtime/`. Contrato exacto de exports: [`LIBRARY_API_CONTRACT_V1.md`](LIBRARY_API_CONTRACT_V1.md).
## 2. Flujo canónico
-### Paso 1: Crear el runtime
+Resumen de `apps/web-demo/app/example-minimal/page.tsx` (importa solo de los paquetes): crear el runtime una vez, y montar `GameViewport` cuando exista.
```tsx
"use client";
-import { useEffect } from "react";
-import { createGameRuntime, GameViewport } from "@pointclick-engine/engine-renderer-r3f";
-
-const myScenes = [
- {
- id: "town",
- label: "Town",
- background: "/assets/bg/town.jpg",
- playerSpawn: [0, 0, 10],
- ground: { minX: -15, maxX: 15, minZ: -10, maxZ: 30, y: -3 },
- walls: [],
- interactions: [],
- },
-];
-
-export default function GamePage() {
+
+import { useEffect, useState } from "react";
+import {
+ createGameRuntime,
+ sceneTransitionOnCollision,
+ type GameItemConfig,
+ type GameRuntime,
+ type GameSceneConfig,
+} from "@pointclick-engine/engine-core";
+import { GameViewport } from "@pointclick-engine/engine-renderer-r3f";
+
+const SCENE_A: GameSceneConfig = {
+ id: "minimal-a",
+ label: "Minimal Scene A",
+ background: "/assets/background/town.jpg",
+ playerSpawn: [3.08, 1.05, 13.44],
+ ground: { minX: -12, maxX: 17, minZ: -15, maxZ: 30, y: -3.25 },
+ walls: [], interactions: [],
+ // Ítem inicial declarado en la propia escena (sin callback del host).
+ initialItems: [
+ {
+ item: {
+ id: "trophy-in-scene-a", itemId: "trophy", interactionId: "trophy-pickup-zone",
+ name: "Trophy", spriteUrl: "/assets/trophy/trophy.png",
+ worldPosition: [6.5, -2.4, 13.4], canPickup: true,
+ },
+ },
+ ],
+ transitions: [
+ sceneTransitionOnCollision({
+ id: "transition-a-to-b",
+ targetSceneId: "minimal-b",
+ position: [2, -1, -12], halfSize: [6, 4, 2],
+ spawnPosition: [0, -1.1, 20], targetPosition: [0, -1.1, 10],
+ }),
+ ],
+};
+
+// Resumida: el ejemplo real añade la transición de vuelta B -> A.
+const SCENE_B: GameSceneConfig = {
+ id: "minimal-b", label: "Minimal Scene B", background: "/assets/background/mazmorra.jpg",
+ playerSpawn: [0, -1.1, 13.44],
+ ground: { minX: -14.4, maxX: 15.8, minZ: -20.6, maxZ: 60.6, y: -3.15 },
+ walls: [], interactions: [],
+};
+
+const TROPHY_ITEM: GameItemConfig = {
+ id: "trophy", name: "Trophy", spriteUrl: "/assets/trophy/trophy.png",
+ interactionRules: {}, defaultRule: { outcome: "return" },
+};
+
+export default function MinimalGame() {
+ const [runtime, setRuntime] = useState(null);
useEffect(() => {
- const runtime = createGameRuntime({
- scenes: myScenes,
- });
- return () => runtime.dispose();
+ const created = createGameRuntime({ scenes: [SCENE_A, SCENE_B], items: [TROPHY_ITEM] });
+ setRuntime(created);
+ return () => {
+ created.dispose();
+ setRuntime(null);
+ };
}, []);
- return ;
+ if (!runtime) return null;
+ return ;
}
```
-### Paso 2: Comunicación bidireccional (host → juego)
+Con estos valores por defecto el juego es jugable: personaje incluido, inventario, recogida/colocación de ítems y transiciones. Sin `storage` no persiste la escena; sin `audio` no suena.
-Desde cualquier componente HTML (fuera del Canvas), envía comandos al runtime:
+## 3. Opciones de `GameViewport`
-```ts
-import { getGameRuntime } from "@pointclick-engine/engine-renderer-r3f";
+`GameViewportProps` = opciones de `useGameViewportController` + props de `GameViewportView` + `debug` y `onRuntimeEvent`. Todas son opcionales.
-const runtime = getGameRuntime();
+| Para... | Opciones |
+|---------|----------|
+| **Escena inicial y persistencia** | `initialSceneId` (escena si no hay guardada), `storage` (`SceneProgressStorage`: `loadSceneId`/`saveSceneId`), `startPersistence` (arranca el guardado de inventario e ítems; devuelve su limpieza), `resolveScene` (por defecto, el registro del runtime) |
+| **Reglas del juego** | `getPhrase(key)`, `itemContext`, `filterPlacedItems`, `canPickupItems`. Vía avanzada (0.6.0 prefiere los datos de escena, ver sección 5b): `canLeaveScene` (`true` deja salir; `{ text, dialogKey? }` bloquea), `getInitialPlacedItems(sceneId, allItems)` (array = siembra; `null` = no marca la escena como sembrada), `onSceneEnter(sceneId, { showDialog })` |
+| **Narrativa (0.6.0)** | `characters` (`Record` para los `characterId` de los NPC), `verbMenu` (sustituye `VerbMenu`), `dialogueChoices` (sustituye `DialogueChoices`), `noActionDialogKey` (frase de `hotspot:noAction`) |
+| **Audio** | `audio`: `{ port, defaults, items, transitions, settingsStore, scenes? }`. Sin `audio` no hay sonido. Los sonidos se declaran en datos (`pickupSoundUrl`/`dropSoundUrl` del ítem, `music` de la escena). Solo `outcome: "place"` reproduce el sonido de soltar |
+| **Personaje** | `character: CharacterDefinition` (por defecto, el incluido), `spriteRuntimeProps` |
+| **Extensión** | `children` (dentro de ``, p. ej. puertas), `canvasChildren` (en el Canvas, fuera de ``), `overlay` (HTML sobre el canvas), `cameraMode` (`"fixed"` por defecto), `onSceneReady` |
+| **Observación** | `runtime` (por defecto, `getGameRuntime()`), `onRuntimeEvent` (callback legacy), `debug` |
-// Cambiar escena
-runtime?.executeCommand({ type: "scene:set", sceneId: "dungeon" });
+## 4. `useGameViewportController` + `GameViewportView`
-// Mostrar diálogo
-runtime?.executeCommand({ type: "dialog:trigger", dialogKey: "welcomeMessage" });
+`GameViewport` es la composición de ambos. Úsalos por separado cuando tu UI necesita datos del controlador (escena actual, estado del diálogo, inventario) fuera del Canvas:
-// Abrir/cerrar inventario
-runtime?.executeCommand({ type: "inventory:toggle" });
+```tsx
+import {
+ GameViewportView,
+ useGameViewportController,
+} from "@pointclick-engine/engine-renderer-r3f";
+
+function Game() {
+ const controller = useGameViewportController({ initialSceneId: "minimal-a" });
+ return {controller.sceneId}
} />;
+}
```
-### Paso 3: Escuchar eventos del juego (juego → host)
+## 5. Comandos y eventos
```ts
-const unsub = runtime?.on("scene:changed", (ev) => {
- console.log("Entered scene:", ev.sceneId);
-});
+import { getGameRuntime } from "@pointclick-engine/engine-core";
-// También: "player:moved", "dialog:triggered", "dialog:dismissed"
+const runtime = getGameRuntime(); // null antes de createGameRuntime o tras dispose()
-// Limpiar al desmontar:
+runtime?.executeCommand({ type: "scene:set", sceneId: "minimal-b", spawnPosition: [0, -1.1, 20] });
+runtime?.executeCommand({ type: "dialog:trigger", dialogKey: "welcomeMessage" });
+runtime?.executeCommand({ type: "inventory:toggle" });
+
+const unsub = runtime?.on("item:pickedUp", (ev) => console.log(ev.itemId));
unsub?.();
```
-### Paso 4: Leer estado React desde la UI
+- `scene:set` acepta `spawnPosition?`; `transition:activate` respeta el `spawnPosition` de la transición.
+- `player:stop` aborta una caminata por ruta (emite `player:walkAborted`); **no** detiene el movimiento manual por teclado/joystick.
+- Texto de diálogos: `registerRule({ key, phrases })` (o `rules` en `createGameRuntime`) o un `dialogAdapter` propio que traduzca la clave. Sin ninguno, `dialog:trigger` muestra la propia clave.
+- Catálogo completo de comandos y eventos: [`architecture/05-bidirectional-communication.md`](architecture/05-bidirectional-communication.md).
+
+## 5b. Narrativa declarativa (0.6.0, sin publicar)
+
+Escenas con `hotspots`, `npcs`, `initialItems` y `onEnter`, transiciones con `when`/`blocked`, ítems con `combine` y árboles de diálogo (`dialogues` en la config) son datos: ver [`authoring/`](authoring/README.md) y [`architecture/10-narrative-model.md`](architecture/10-narrative-model.md).
+
+- Comandos nuevos: `hotspot:interact`, `inventory:combine`, `dialogue:start|choose|advance|end`, `script:run`, `script:cancelAll`, `state:setFlag|clearFlag`, `game:save|load|reset`. Eventos: `hotspot:interacted|noAction`, `dialogue:*`, `item:combined|combineFailed`, `script:started|finished`, `state:flagChanged`, `game:saved|loaded|reset`. Lista en [`LIBRARY_API_CONTRACT_V1.md`](LIBRARY_API_CONTRACT_V1.md) (2.4).
+- Guardado: `storage` (y `saveKey`) en `createGameRuntime` activan `game:save` / `game:load`. Una partida de 0.5.0 se migra con `migrateLegacySave`.
+- `call` en un guion invoca lo que registres con `runtime.registerHandler(name, fn)`. `validate` en la config valida el contenido (solo en desarrollo por defecto); `dialogKeys` y `handlerNames` amplían la comprobación.
+- Si sobrescribes `resolveScene` con tus propias escenas, proyecta tú los NPC con `npcToHotspot` (`toRuntimeScene` lo hace solo para el registro).
+- Tests sin renderer: `createPlaythrough` de `@pointclick-engine/engine-core/testing`. Los outcomes `pickup-blocked` e `item-interact` de `item:dropped` son obsoletos.
+
+## 6. Leer estado desde la UI
```tsx
-import { useGameState, useGameActions } from "@pointclick-engine/engine-renderer-r3f";
+import { useGameActions, useGameState } from "@pointclick-engine/engine-renderer-r3f";
export function SceneSwitcher() {
const sceneId = useGameState((s) => s.sceneId);
- const { setScene, requestRespawn } = useGameActions();
-
+ const { setScene } = useGameActions();
return (
-
-
Escena: {sceneId}
-
-
-
+
);
}
```
----
-
-## 3. Subpath exports de `engine-core`
-
-Para trees-haking granular, importa solo el módulo que necesitas:
-
-```ts
-import type { GameCommand } from "@pointclick-engine/engine-core/commands";
-import type { GameEvent } from "@pointclick-engine/engine-core/events";
-import type { IGameLoopPort } from "@pointclick-engine/engine-core/ports";
-import type { GameVec3 } from "@pointclick-engine/engine-core/types";
-import { useSceneStore } from "@pointclick-engine/engine-core/state";
-```
-
----
-
-## 4. Registrar diálogos personalizados
-
-```ts
-import { registerRule } from "@pointclick-engine/engine-renderer-r3f";
-
-registerRule({ key: "welcomeMessage", phrases: ["¡Bienvenido al pueblo!", "¿Primera vez por aquí?"] });
-registerRule({ key: "boundaryHit", phrases: ["¡Hay una pared ahí!"] });
-```
-
----
-
-## 5. Consideraciones SSR
-
-- `GameViewport` lleva `"use client"` — no renderiza en servidor.
-- `createGameRuntime` inicializa el store; hacerlo en `useEffect` para evitar hidratación conflictiva.
-- `getGameRuntime()` devuelve `null` antes de que el runtime se cree (útil para verificar antes de llamar).
-
----
+`GameState` = `sceneId`, `scene`, `playerPosition`, `respawnSignal`. `GameActions` también trae `setPlayerPosition` y `requestRespawn`. `GameActions.setScene` es `(sceneId: string) => void`.
-## 6. Errores comunes
+Stores reactivos del core (selector de zustand): `useSceneStore`, `useInventoryStateStore` (`slots`), `usePlacedItemsStateStore` (`items`), `useDialogStore`, `useInventoryUiStore` y, en 0.6.0, `useWorldStateStore` (`flags`, `visitedSceneIds`) y `useDialogueStore`. La persistencia va por puerto (`KeyValueStoragePort`).
-| ❌ Hacer | ✅ En su lugar |
-|----------|--------------|
-| Importar módulos internos de `app/lib/engine/runtime/` directamente | Importar desde `@pointclick-engine/engine-renderer-r3f` |
-| Usar `window.document` en lógica de juego | Pasar por ports / platform adapters |
-| Mutar `useSceneStore` directamente desde la UI | Usar `useGameActions()` o `executeCommand()` |
-| Crear el runtime varias veces | Un solo `createGameRuntime()` por instancia de juego |
+## 7. SSR
----
+- `GameViewport` y los hooks del renderer llevan `"use client"`: no renderizan en servidor.
+- Crea el runtime en `useEffect` y monta el viewport cuando exista (como en el flujo canónico).
-## 7. Criterio de breaking change
+## 8. Limitaciones conocidas
-**Compatible** (no requiere migración):
-- Nuevas funciones en la API pública sin cambiar firmas existentes.
-- Nuevos campos opcionales en tipos públicos.
-- Nuevos subpath exports.
+- `inventory:pickup` e `inventory:drop` tienen executor en 0.6.0 (solo cambian estado y emiten eventos; los textos los muestra el viewport).
+- El renderer no trae UI para combinar ítems: el host lanza `inventory:combine` (la demo lo hace en `GameTouchCanvas.tsx`).
+- Las puertas son de la demo (`apps/web-demo/app/lib/engine/runtime/useDoorSystem.ts`), no del motor.
+- Los registros de escenas, ítems y reglas son globales de módulo: un solo juego por página.
-**Breaking** (requiere issue + guía de migración):
-- Renombrar o eliminar exports públicos.
-- Cambiar la semántica de commands/events.
-- Cambiar la forma de `GameViewport` props.
+## 9. Errores comunes
----
+| No hacer | En su lugar |
+|----------|-------------|
+| Importar `createGameRuntime` o `registerRule` de `engine-renderer-r3f` | Importar del core: `@pointclick-engine/engine-core` |
+| Escuchar `item:dropped` para detectar recogidas | Escuchar `item:pickedUp` |
+| Montar `GameViewport` antes de crear el runtime | Esperar al runtime (estado + `useEffect`) |
+| Crear el runtime varias veces | Un `createGameRuntime()` por juego; `dispose()` al desmontar |
+| Esperar que `player:stop` frene el teclado | Solo detiene caminatas por ruta |
-## 8. Ver también
+## 10. Ver también
-- [`architecture/05-bidirectional-communication.md`](architecture/05-bidirectional-communication.md) — Protocolo completo de commands & events
-- [`architecture/06-renderer-implementation-guide.md`](architecture/06-renderer-implementation-guide.md) — Escribir un renderer alternativo
-- [`architecture/02-public-api.md`](architecture/02-public-api.md) — Contrato estable de `publicApi`
-- `packages/engine-core/README.md` — Quickstart engine-core aislado
-- `packages/engine-renderer-r3f/README.md` — Quickstart renderer R3F
+- [`LIBRARY_API_CONTRACT_V1.md`](LIBRARY_API_CONTRACT_V1.md) — Superficie soportada y novedades 0.5.0 y 0.6.0
+- [`architecture/02-public-api.md`](architecture/02-public-api.md) — Resumen de la API pública
+- [`architecture/05-bidirectional-communication.md`](architecture/05-bidirectional-communication.md) — Commands & Events
diff --git a/docs/README.md b/docs/README.md
index 4751838..d9bdcf5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,12 +9,28 @@
Diseño del sistema. Lee antes de tocar arquitectura.
- [`architecture/01-layers.md`](architecture/01-layers.md) — Las 4 capas y su responsabilidad
-- [`architecture/02-public-api.md`](architecture/02-public-api.md) — Contrato de `publicApi.ts` (estable v1)
+- [`architecture/02-public-api.md`](architecture/02-public-api.md) — API pública (contrato v1; `publicApi.ts` es barrel de los paquetes)
- [`architecture/03-rules-core-vs-render.md`](architecture/03-rules-core-vs-render.md) — Decisión: ¿este código va en core o renderer?
- [`architecture/04-platform-ports.md`](architecture/04-platform-ports.md) — Adapters web (storage, clipboard, timer)
- [`architecture/05-bidirectional-communication.md`](architecture/05-bidirectional-communication.md) — Commands & Events API (web ↔ juego)
- [`architecture/06-renderer-implementation-guide.md`](architecture/06-renderer-implementation-guide.md) — Cómo escribir un renderer alternativo
+- [`architecture/07-walls-with-openings.md`](architecture/07-walls-with-openings.md) — Walls with openings: pathfinding & rendering
+- [`architecture/08-scene-transitions.md`](architecture/08-scene-transitions.md) — Scene transitions as first-class primitives
- [`architecture/09-multiplayer.md`](architecture/09-multiplayer.md) — Multijugador agnóstico (port + partición world/presence/private)
+- [`architecture/10-narrative-model.md`](architecture/10-narrative-model.md) — Modelo narrativo: estado de mundo → condiciones → ramas → secuenciador → comandos y eventos (0.6.0)
+
+---
+
+## ✍️ Authoring (guía para escribir una aventura)
+
+Escenas, puzzles y diálogos como datos. Empieza por el índice y sigue el orden.
+
+- [`authoring/README.md`](authoring/README.md) — Índice, ejemplos ejecutables y textos (`say`)
+- [`authoring/01-scenes-and-hotspots.md`](authoring/01-scenes-and-hotspots.md) — Escenas, transiciones, hotspots y verbos
+- [`authoring/02-conditions-and-actions.md`](authoring/02-conditions-and-actions.md) — Flags, condiciones, acciones, ramas y `call`
+- [`authoring/03-dialogues-and-npcs.md`](authoring/03-dialogues-and-npcs.md) — Diálogos con opciones y NPCs
+- [`authoring/04-items-and-combining.md`](authoring/04-items-and-combining.md) — Ítems, reglas de drop y combinaciones
+- [`authoring/05-saving-and-testing.md`](authoring/05-saving-and-testing.md) — Guardado, validación y `createPlaythrough`
---
@@ -27,6 +43,7 @@ Cómo trabajar en este repo.
- [`workflow/how-to-spawn-subagent.md`](workflow/how-to-spawn-subagent.md) — Delegar tareas autocontenidas
- [`workflow/pre-commit-checklist.md`](workflow/pre-commit-checklist.md) — Validación antes de commit
- [`workflow/commit-convention.md`](workflow/commit-convention.md) — Formato de commits
+- Smoke headless: `npm run smoke` (`e2e/smoke.mjs` + `e2e/smoke-minimal.mjs`; requiere la demo en marcha)
---
@@ -39,10 +56,18 @@ Trabajo actual y futuro. Una fase = un directorio con tareas modulares.
- [`phases/phase-4-bidirectional-web-game/`](phases/phase-4-bidirectional-web-game/) — ✅ Completed: Comunicación web ↔ juego
- [`phases/phase-5-publish/`](phases/phase-5-publish/) — ✅ Completed: Publicación en npm (v0.1.0 publishable)
- [`phases/phase-6-walls-with-openings/`](phases/phase-6-walls-with-openings/) — ✅ Completed: Walls with openings & pathfinding
-- [`phases/phase-7-walls-first-class/`](phases/phase-7-walls-first-class/) — ✅ Completed: Walls as first-class scene elements
+- [`phases/phase-7-walls-first-class/`](phases/phase-7-walls-first-class/) — 📋 Planned (not started)
- [`phases/phase-8-scene-transitions/`](phases/phase-8-scene-transitions/) — ✅ Completed: Scene transitions (collision + item-drop)
- [`phases/phase-9-placed-items-agnóstic/`](phases/phase-9-placed-items-agnóstic/) — ✅ Phases A-C: Placed items refactoring to core (types, dialog keys, stores)
+- [`phases/phase-10-scene-entry-positions-and-pathwalking/`](phases/phase-10-scene-entry-positions-and-pathwalking/) — ✅ Completed: Player spawn positions and pathwalking
+- [`phases/phase-11-audio/`](phases/phase-11-audio/) — ✅ Completed: Audio system (música + SFX + mute)
+- [`phases/phase-12-architecture-cleanup/`](phases/phase-12-architecture-cleanup/) — ✅ Completed: Core agnosticism & library boundaries
+- [`phases/phase-13-i18n/`](phases/phase-13-i18n/) — ✅ Completed: Localization system (i18n)
- [`phases/phase-14-multiplayer/`](phases/phase-14-multiplayer/) — 📋 Planning: Multijugador en tiempo real, agnóstico de transporte
+- [`phases/phase-15-green-baseline/`](phases/phase-15-green-baseline/) — ✅ Completed: Base verde (tests, tipos, lint, CI) y docs resincronizadas
+- [`phases/phase-16-runtime-in-library/`](phases/phase-16-runtime-in-library/) — ✅ Completed: Runtime en los paquetes (core + renderer); la demo es consumidora (0.5.0)
+- [`phases/phase-17-narrative-primitives/`](phases/phase-17-narrative-primitives/) — ✅ Completed: Flags, condiciones, acciones, hotspots con verbos, NPCs, diálogos con opciones, guardado único (0.6.0)
+- [`phases/phase-18-story-demo/`](phases/phase-18-story-demo/) — 📋 Next: Aventura corta con historia, de principio a fin
---
@@ -72,6 +97,12 @@ Decisiones arquitectónicas registradas.
- [`decisions/0002-useframe-for-loop.md`](decisions/0002-useframe-for-loop.md)
- [`decisions/0003-monorepo-with-demo.md`](decisions/0003-monorepo-with-demo.md)
- [`decisions/0004-modular-docs-strategy.md`](decisions/0004-modular-docs-strategy.md)
+- [`decisions/0005-renderer-ports-design.md`](decisions/0005-renderer-ports-design.md)
+- [`decisions/0006-command-event-architecture.md`](decisions/0006-command-event-architecture.md)
+- [`decisions/0007-release-strategy.md`](decisions/0007-release-strategy.md)
+- [`decisions/0008-multiplayer-architecture.md`](decisions/0008-multiplayer-architecture.md)
+- [`decisions/0009-runtime-lives-in-packages.md`](decisions/0009-runtime-lives-in-packages.md)
+- [`decisions/0010-declarative-narrative-model.md`](decisions/0010-declarative-narrative-model.md)
---
@@ -80,6 +111,7 @@ Decisiones arquitectónicas registradas.
- [`ROADMAP_FRAMEWORK_AGNOSTIC_REFACTORING.md`](ROADMAP_FRAMEWORK_AGNOSTIC_REFACTORING.md) — Plan high-level de 5 fases
- [`LIBRARY_API_CONTRACT_V1.md`](LIBRARY_API_CONTRACT_V1.md) — Contrato v1 de API pública
- [`LIBRARY_CONSUMPTION_GUIDE.md`](LIBRARY_CONSUMPTION_GUIDE.md) — Cómo consumir la librería
+- [`authoring/README.md`](authoring/README.md) — Cómo escribir escenas, puzzles y diálogos
- [`_archive/`](_archive/) — Documentos reemplazados (referencia histórica)
---
diff --git a/docs/DEBUG_MODE_REVIEW.md b/docs/_archive/DEBUG_MODE_REVIEW.md
similarity index 100%
rename from docs/DEBUG_MODE_REVIEW.md
rename to docs/_archive/DEBUG_MODE_REVIEW.md
diff --git a/FEATURE_WALLS_OPENINGS_VISUAL_GUIDE.md b/docs/_archive/FEATURE_WALLS_OPENINGS_VISUAL_GUIDE.md
similarity index 100%
rename from FEATURE_WALLS_OPENINGS_VISUAL_GUIDE.md
rename to docs/_archive/FEATURE_WALLS_OPENINGS_VISUAL_GUIDE.md
diff --git a/PHASE_6_EXECUTIVE_SUMMARY.md b/docs/_archive/PHASE_6_EXECUTIVE_SUMMARY.md
similarity index 100%
rename from PHASE_6_EXECUTIVE_SUMMARY.md
rename to docs/_archive/PHASE_6_EXECUTIVE_SUMMARY.md
diff --git a/TODAY_DELIVERABLES.md b/docs/_archive/TODAY_DELIVERABLES.md
similarity index 100%
rename from TODAY_DELIVERABLES.md
rename to docs/_archive/TODAY_DELIVERABLES.md
diff --git a/docs/architecture/01-layers.md b/docs/architecture/01-layers.md
index 08d475a..9e66305 100644
--- a/docs/architecture/01-layers.md
+++ b/docs/architecture/01-layers.md
@@ -12,16 +12,19 @@
↕ props / callbacks
┌────────────────────┴────────────────────────────────────┐
│ 2. Renderer R3F │
-│ apps/web-demo/app/lib/engine/runtime/, render/ │
-│ - GameTouchCanvas, useFrame loops │
+│ packages/engine-renderer-r3f/src/ │
+│ - GameViewport (composición jugable), hooks de │
+│ escena/transiciones/inventario/audio, sprites │
│ - Renderizado 3D (Three.js, Rapier) │
│ - Sería diferente con otro renderer │
└────────────────────┬────────────────────────────────────┘
↕ events / state subscriptions
┌────────────────────┴────────────────────────────────────┐
│ 3. Core (AGNÓSTICO) │
-│ packages/engine-core/ (Fase 2+) │
-│ - Zustand stores, rules, pathfinding │
+│ packages/engine-core/src/ │
+│ - Runtime (game/runtime/): createGameRuntime, │
+│ registros, executors de comandos │
+│ - Zustand stores, rules, pathfinding, puertos │
│ - Sin React, sin R3F, sin Next.js │
│ - Testeable sin mocks de framework │
└────────────────────┬────────────────────────────────────┘
@@ -44,6 +47,17 @@
| Core | Solo types y puertos | React, R3F, navegador |
| Platform | API del navegador + puertos | Lógica de juego |
+## Qué queda en la demo (`apps/web-demo`)
+
+Tras la Fase 16 el runtime ya no vive en la demo. La demo es **consumidora y punto de composición**:
+
+- `app/lib/engine/publicApi.ts`: barrel de re-export del contrato v1 (ver [`02-public-api.md`](02-public-api.md)).
+- `demo-content/`: escenas, ítems, diálogos y personaje de la demo.
+- `app/components/` y `app/store/`: UI propia (inventario, joystick, paneles de depuración, editores) y puertas (`SceneDoors.tsx`, `useDoorSystem.ts`).
+- `app/lib/engine/runtime/`: opciones de la demo para `useGameViewportController` (`demoViewportOptions.ts`, `demoSceneRules.ts`) y hooks de depuración/editores.
+- `app/lib/platform-web.ts`, `platform-web-audio.ts`, `platform-web-i18n.ts`, `gamePersistence.ts`: adapters web.
+- `app/example-minimal/page.tsx`: juego que importa solo de los paquetes.
+
## Flujo de datos
**Entrada usuario** → Presentación → Renderer → Core (state update)
@@ -51,7 +65,7 @@
## Verificación
-Test rápido: si borras `react` de `package.json` de `engine-core/`, debe seguir compilando.
+Test rápido: si borras `react` de `package.json` de `engine-core/`, debe seguir compilando. Además, `packages/engine-core/src/__tests__/` incluye un test de agnosticismo del core.
## Ver también
diff --git a/docs/architecture/02-public-api.md b/docs/architecture/02-public-api.md
index a8107f8..add3c26 100644
--- a/docs/architecture/02-public-api.md
+++ b/docs/architecture/02-public-api.md
@@ -1,82 +1,27 @@
-# API Pública (`publicApi.ts`)
+# API Pública
-**Ubicación actual**: `app/lib/engine/publicApi.ts`
-**Ubicación post-Fase 2**: `packages/engine-core/src/index.ts` (parte agnóstica) + `apps/web-demo/.../publicApi.ts` (parte R3F)
+**Ubicación**: el runtime agnóstico vive en `packages/engine-core/src/game/runtime/` y el viewport/hooks R3F en `packages/engine-renderer-r3f/src/index.ts`. `apps/web-demo/app/lib/engine/publicApi.ts` es un **barrel de compatibilidad** que re-exporta ambos con los nombres del contrato v1.
## Contrato Estable (v1)
-Estos exports **NO se rompen sin issue + migración + bump semver**.
+Estos exports **NO se rompen sin issue + migración + bump semver**. La lista completa y separada por paquete está en [`../LIBRARY_API_CONTRACT_V1.md`](../LIBRARY_API_CONTRACT_V1.md) (fuente única; no se duplica aquí).
-### Tipos
+Resumen:
-```ts
-GameVec3
-GameSceneGround, GameSceneWall, GameSceneConfig
-GameSceneInteraction, GameSceneInteractionDialogKeys
-GameItemDropOutcome, GameItemRule, GameItemConfig
-GameRuleConfig
-GameRuntimeConfig, GameRuntime
-GameState, GameActions
-GameRuntimeEvent, GameRuntimeEventHandler
-GameViewportProps
-```
-
-### Funciones / Componentes
-
-```ts
-createGameRuntime(config?: GameRuntimeConfig): GameRuntime
-registerScene(config: GameSceneConfig): void
-registerItem(config: GameItemConfig): void
-registerRule(config: GameRuleConfig): void
-getGameState(): GameState
-getGameActions(): GameActions
-useGameState(selector: (s: GameState) => T): T
-useGameActions(): GameActions
-GameViewport(props: GameViewportProps): ReactNode
-```
-
-### i18n (v0.4.0+, Phase 13)
+| Paquete | Contenido |
+|---------|-----------|
+| `@pointclick-engine/engine-core` | `createGameRuntime`, `getGameRuntime`, `registerScene/Item/Rule`, `getGameState`, `getGameActions`, tipos `Game*Config`, `GameRuntime`, `GameState`, `GameActions`, `GameCommand`, `GameEvent` |
+| `@pointclick-engine/engine-renderer-r3f` | `GameViewport`, `GameViewportView`, `useGameViewportController`, `useGameState`, `useGameActions`, `CharacterSprite`, `attachAudioSystem` |
-Tipos:
+Cómo se usa, paso a paso: [`../LIBRARY_CONSUMPTION_GUIDE.md`](../LIBRARY_CONSUMPTION_GUIDE.md).
-```ts
-Locale, DialogEntry, DialogDictionary, LocaleDictionaries
-I18nConfig, I18nState, I18nPort, I18nStore
-UseI18nResult, UseLocaleDetectionOptions
-LocaleSwitcherProps, LocaleSwitcherRenderOption, I18nProviderProps
-```
+## i18n (v0.4.0+, Phase 13)
-Funciones / componentes:
+Core (`@pointclick-engine/engine-core`): `registerDictionary`, `registerDictionaries`, `getDictionary`, `translate`, `getRandomPhrase`, `matchLocale`, `createI18nStore`, `getI18nStore`, `resetI18nStore`, `subscribeI18n`, `setI18nStoreEmitter`, `HeadlessI18nAdapter`, `registerI18nExecutors`; tipos `Locale`, `DialogEntry`, `DialogDictionary`, `LocaleDictionaries`, `I18nConfig`, `I18nState`, `I18nPort`, `I18nStore`.
-```ts
-// Core
-registerDictionary(locale, dict): void
-registerDictionaries(all): void
-getDictionary(locale): DialogDictionary | undefined
-translate(key, opts?): string
-getRandomPhrase(key, opts?): string
-matchLocale(candidate, available): Locale | null
-createI18nStore(config): I18nStore
-getI18nStore(): I18nStore
-resetI18nStore(config?): void
-subscribeI18n(listener): () => void
-setI18nStoreEmitter(emitter): void
-HeadlessI18nAdapter // class implements I18nPort
-registerI18nExecutors(handler, emit?): () => void
-
-// R3F
-useI18n(): UseI18nResult
-useLocaleDetection({ port, config? }): void
-...
-
-```
+Renderer (`@pointclick-engine/engine-renderer-r3f`): `useI18n`, `useLocaleDetection`, `I18nProvider`, `LocaleSwitcher`; tipos `UseI18nResult`, `UseLocaleDetectionOptions`, `LocaleSwitcherProps`, `LocaleSwitcherRenderOption`, `I18nProviderProps`.
-Adapter web (no es parte del package; vive en `apps/web-demo/app/lib/`):
-
-```ts
-createWebI18nAdapter({ availableLocales, storageKey? }): WebI18nAdapter
-bindI18nPersistence(store, port): () => void
-```
+Adapter web (no es parte de los paquetes; vive en `apps/web-demo/app/lib/platform-web-i18n.ts`): `createWebI18nAdapter`, `bindI18nPersistence`.
Recetas Next.js: ver [`../integrations/nextjs-i18n.md`](../integrations/nextjs-i18n.md).
@@ -90,7 +35,7 @@ Recetas Next.js: ver [`../integrations/nextjs-i18n.md`](../integrations/nextjs-i
- ❌ Renombrar / remover exports
- ❌ Cambiar firmas (parámetros, return)
-- ❌ Cambiar semántica de eventos / acciones
+- ❌ Cambiar semántica de eventos / acciones (p. ej. 0.5.0: recoger un ítem pasó de `item:dropped` con `outcome: "pickup-success"` a `item:pickedUp`)
## Si necesitas cambiar la API pública
@@ -101,13 +46,13 @@ Recetas Next.js: ver [`../integrations/nextjs-i18n.md`](../integrations/nextjs-i
## Commands & Events (Phase 4)
-`createGameRuntime()` ahora devuelve también `executeCommand`, `on`, `emit`, `dispose`:
+`createGameRuntime()` devuelve un handle con `executeCommand`, `on`, `emit`, `dispose`, además de `getScenes`, `getItems`, `getRules`:
```ts
const runtime = createGameRuntime({ scenes });
runtime.on("scene:changed", handler); // suscribirse a eventos
runtime.executeCommand({ type: "scene:set", sceneId: "town" }); // enviar comandos
-const rt = getGameRuntime(); // acceso al singleton desde cualquier sitio
+const rt = getGameRuntime(); // handle activo (null antes de crearlo o tras dispose)
```
Ver catálogo completo en [`05-bidirectional-communication.md`](05-bidirectional-communication.md).
diff --git a/docs/architecture/05-bidirectional-communication.md b/docs/architecture/05-bidirectional-communication.md
index 69a3616..2874610 100644
--- a/docs/architecture/05-bidirectional-communication.md
+++ b/docs/architecture/05-bidirectional-communication.md
@@ -1,6 +1,6 @@
# Bidirectional Communication
-**Estado**: estable v0.4 | **Última revisión**: 2026-05-27
+**Estado**: estable v0.4; catálogo ampliado en 0.6.0 (sin publicar) | **Última revisión**: 2026-10-11
## TL;DR
@@ -14,7 +14,7 @@ Ambos son sincrónicos, fire-and-forget, y **no requieren React**.
## Quickstart
```ts
-import { createGameRuntime } from "@pointclick-engine/engine-renderer-r3f"; // facade re-export
+import { createGameRuntime } from "@pointclick-engine/engine-core";
const runtime = createGameRuntime({ scenes, items, rules });
@@ -35,17 +35,36 @@ runtime.dispose();
| Type | Payload | Efecto |
|------|---------|--------|
-| `scene:set` | `{ sceneId: string }` | Cambia la escena activa |
+| `scene:set` | `{ sceneId: string, spawnPosition? }` | Cambia la escena activa |
| `scene:respawn` | — | Reinicia player en spawn de la escena actual |
| `player:move` | `{ position: [x,y,z] }` | Teleporta player (sin pathfinding) |
-| `player:stop` | — | Cancela movimiento en curso *(not yet wired — Phase 5)* |
-| `inventory:toggle` | — | Abre/cierra UI inventario *(not yet wired — Phase 5)* |
-| `inventory:pickup` | `{ itemId: string }` | Mete ítem al inventario *(not yet wired — Phase 5)* |
-| `inventory:drop` | `{ itemId: string, slotIndex: number }` | Suelta ítem *(not yet wired — Phase 5)* |
-| `dialog:trigger` | `{ dialogKey: string }` | Muestra diálogo por clave *(not yet wired — Phase 5)* |
-| `dialog:dismiss` | — | Cierra diálogo activo *(not yet wired — Phase 5)* |
+| `player:stop` | — | Aborta una caminata por ruta (emite `player:walkAborted`) |
+| `inventory:toggle` | — | Abre/cierra UI inventario |
+| `inventory:pickup` | `{ itemId, placedItemId? }` | Recoge un ítem colocado de la escena activa |
+| `inventory:drop` | `{ itemId, slotIndex, interactionId? \| hotspotId? }` | Suelta ítem sobre una interacción o un hotspot |
+| `dialog:trigger` | `{ dialogKey, speaker? }` | Muestra el bocadillo de una clave |
+| `dialog:dismiss` | — | Cierra diálogo activo |
-Comandos sin executor real loguean un `console.warn` y no hacen nada. Se cablearán en Phase 5.
+Comandos sin executor registrado loguean un `console.warn` y no hacen nada.
+
+### Comandos nuevos en 0.6.0
+
+Fuente: `packages/engine-core/src/game/commands/types.ts`.
+
+| Type | Payload | Efecto |
+|------|---------|--------|
+| `state:setFlag` | `{ name, value }` | Pone un flag (`boolean \| number \| string`) |
+| `state:clearFlag` | `{ name }` | Borra un flag |
+| `game:save` | `{ extra? }` | Guarda la partida (requiere `storage`) |
+| `game:load` | — | Carga la partida guardada |
+| `game:reset` | — | Vacía la partida y borra el guardado |
+| `script:run` | `{ script, interrupt? }` | Ejecuta un guion |
+| `script:cancelAll` | — | Cancela el guion en curso y la cola |
+| `hotspot:interact` | `{ hotspotId, verb, itemId? }` | Verbo (`look`, `use`, `talk`) o `useItem` sobre un hotspot o NPC |
+| `inventory:combine` | `{ itemId, withItemId }` | Combina dos ítems del inventario |
+| `dialogue:start` | `{ dialogueId }` | Abre una conversación |
+| `dialogue:choose` | `{ index }` | Elige una opción |
+| `dialogue:advance` / `dialogue:end` | — | Cierra la línea / termina la conversación |
## Catálogo de eventos
@@ -57,9 +76,28 @@ Comandos sin executor real loguean un `console.warn` y no hacen nada. Se cablear
| `player:collided` | `{ reason, position }` | Boundary / stuck |
| `item:pickedUp` | `{ itemId, quantity }` | Tras pickup exitoso |
| `item:dropped` | `{ itemId, outcome, interactionId? }` | Tras drop |
-| `dialog:triggered` | `{ text, dialogKey?, source }` | Diálogo mostrado |
+| `dialog:triggered` | `{ text, dialogKey?, source, speaker? }` | Diálogo mostrado |
| `dialog:dismissed` | `{ dialogKey? }` | Diálogo cerrado |
+### Eventos nuevos en 0.6.0
+
+Fuente: `packages/engine-core/src/game/events/types.ts`.
+
+| Type | Payload | Cuándo |
+|------|---------|--------|
+| `state:flagChanged` | `{ name, value?, previous? }` | Cambia o se borra un flag |
+| `game:saved` / `game:reset` | — | Tras guardar / reiniciar |
+| `game:loaded` | `{ found, applied?, extra? }` | Tras `game:load` |
+| `script:started` / `script:finished` | `{ id }` / `{ id, result }` | Un guion empieza / termina (`"finished"` o `"cancelled"`) |
+| `input:lockChanged` | `{ locked }` | Cambia el bloqueo de entrada |
+| `custom` | `{ name, payload? }` | Acción `emit` de un guion |
+| `hotspot:interacted` | `{ hotspotId, verb, itemId? }` | Se aplicó una rama |
+| `hotspot:noAction` | `{ hotspotId, verb, itemId?, reason }` | Sin rama (`not-found`, `hidden`, `missing-item`, `no-rule`) |
+| `dialogue:started` / `nodeEntered` / `choiceMade` / `ended` | ver tipos | Ciclo de una conversación (`ended.reason`: `finished`, `ended`, `cancelled`) |
+| `inventory:pickupFailed` | `{ itemId, reason }` | `not-found`, `blocked`, `full`, `unknown-item` |
+| `inventory:full` / `item:removed` | `{ itemId }` | `giveItem` sin sitio / `removeItem` |
+| `item:combined` / `item:combineFailed` | `{ itemId, withItemId }` | Resultado de `inventory:combine` |
+
> **Nota sobre `player:moved`**: se emite a ~60Hz. Si el consumer hace operaciones costosas
> en este handler, añadir throttle/debounce en el callback — nunca en el motor.
@@ -110,7 +148,7 @@ window.addEventListener("message", (msg) => {
Si no tienes referencia directa al handle (ej. dentro de un componente que no lo creó):
```ts
-import { getGameRuntime } from "@pointclick-engine/engine-renderer-r3f";
+import { getGameRuntime } from "@pointclick-engine/engine-core";
const rt = getGameRuntime(); // null si no se ha llamado createGameRuntime todavía
rt?.executeCommand({ type: "scene:respawn" });
```
diff --git a/docs/architecture/10-narrative-model.md b/docs/architecture/10-narrative-model.md
new file mode 100644
index 0000000..02ac489
--- /dev/null
+++ b/docs/architecture/10-narrative-model.md
@@ -0,0 +1,73 @@
+# Modelo narrativo (0.6.0)
+
+**Estado**: implementado (Fase 17, sin publicar) | **Decisión**: [ADR-0010](../decisions/0010-declarative-narrative-model.md) | **Cómo se usa**: [`../authoring/README.md`](../authoring/README.md)
+
+## TL;DR
+
+El contenido narrativo es **dato serializable**, no código. Un intérprete pequeño en `engine-core` lo ejecuta despachando los comandos que ya existían y esperando eventos del bus. Nada de esto importa React ni el renderer.
+
+## Cómo encajan las piezas
+
+```
+ contenido (datos) core (packages/engine-core/src/game/narrative/)
+ ───────────────── ──────────────────────────────────────────────
+ scene.hotspots / npcs ──┐
+ scene.onEnter │ evento del jugador / de escena
+ transition.when/blocked ├──► hotspot:interact · dialogue:start · inventory:combine ·
+ item.combine │ entrada a escena · transición
+ dialogue nodes/choices ─┘ │
+ ▼
+ estado de mundo ──► condiciones ──► ramas (pickBranch: gana la primera)
+ (flags, visitadas, evaluateCondition │ guion = Action[]
+ inventario, ítems ▼
+ colocados, escena) secuenciador (createSequencer)
+ ▲ cola FIFO · cancelable · ClockPort
+ │ │ una acción cada vez
+ │ ▼
+ │ comandos (dialog:trigger, state:setFlag,
+ │ player:walkTo, scene:set, ...)
+ │ │
+ └──────── stores (sceneStore, ▼
+ worldStateStore, ...) eventos (dialog:dismissed,
+ player:walkCompleted, state:flagChanged,
+ script:finished, ...) ──► host / UI / sequencer
+```
+
+1. **Estado de mundo** (`state/worldStateStore.ts`): flags `boolean | number | string` y escenas visitadas. Junto al inventario, los ítems colocados y la escena activa forma el `ConditionContext` (`getConditionContext`).
+2. **Condiciones** (`narrative/conditions.ts`): `Condition` evaluable sin efectos con `evaluateCondition`. Una forma desconocida es `false`.
+3. **Ramas** (`narrative/branches.ts`): `pickBranch(branches, ctx)` devuelve el guion de la primera rama cuyo `when` se cumple. Hotspots, NPC, `useItem`, `combine` y `onEnter` son listas de ramas.
+4. **Secuenciador** (`narrative/sequencer.ts`, `actionExecutors.ts`): ejecuta un guion acción a acción. Cada acción **despacha comandos existentes** y espera el evento que la completa (`say` espera `dialog:dismissed`; `walkTo`, `player:walkCompleted` o `player:walkAborted`; `wait`, el `ClockPort`). Cola FIFO; `interrupt` y `script:cancelAll` cancelan. `lockInput` bloquea la entrada del jugador.
+5. **Comandos y eventos**: lo único que cruza hacia fuera. El host observa con `runtime.on(...)` y actúa con `executeCommand(...)`; los catálogos nuevos están en [05](05-bidirectional-communication.md).
+
+## Un mismo motor para todo
+
+`registerHotspotCommands`, `registerDialogueCommands` y `registerCombineCommands` reciben `runScript` del secuenciador: hablar con un NPC, usar un ítem y combinar son el mismo mecanismo con distinto disparador. Un diálogo es un ejecutor de la acción `startDialogue` que recorre nodos y espera el cierre del bocadillo o la elección.
+
+`say` y las líneas de diálogo emiten `dialog:trigger` con una **clave** que se resuelve en las reglas del runtime o en un `dialogAdapter` del host (ver [`../authoring/README.md`](../authoring/README.md)).
+
+## Quién aplica qué
+
+| Regla | Funciones puras (core) | Las aplica |
+|-------|------------------------|------------|
+| `initialItems` | `resolveInitialItems` | el renderer al entrar a la escena; `createPlaythrough` en headless |
+| `onEnter` | `resolveEnterScript` | ídem |
+| `transition.when` / `blocked` | `evaluateTransitionGate` | ídem, antes de cambiar de escena |
+| Verbos, `useItem`, `combine`, diálogos | comandos del runtime (`hotspot:interact`, `inventory:combine`, `dialogue:*`) | el core, sin renderer |
+
+Los callbacks de 0.5.0 (`canLeaveScene`, `onSceneEnter`, `getInitialPlacedItems`) siguen disponibles como **vía avanzada** y se evalúan después de las reglas declarativas.
+
+## Guardado
+
+La instantánea `GameSnapshot` (`state/saveGame.ts`) serializa exactamente ese estado: escena, posición, inventario, ítems colocados, escenas sembradas, flags y escenas visitadas, más `extra` para el host. Por eso el contenido declarativo se puede guardar, validar (`validateContent`) y repetir en headless (`createPlaythrough`). Ver [`../authoring/05-saving-and-testing.md`](../authoring/05-saving-and-testing.md).
+
+## Dónde vive cada cosa
+
+| Capa | Qué | Ruta |
+|------|-----|------|
+| Core | tipos, evaluador, secuenciador, comandos narrativos, stores, guardado, validador | `packages/engine-core/src/game/{narrative,state}/` |
+| Core | `ClockPort`, `HeadlessClock` | `packages/engine-core/src/ports/` |
+| Core (subpath `/testing`) | `createPlaythrough` | `packages/engine-core/src/testing/` |
+| Renderer | `SceneHotspots`, `SceneNpcs`, `NpcSprite`, `VerbMenu`, `DialogueChoices`, `useDialogue`, `useHotspotInteractions` | `packages/engine-renderer-r3f/src/` |
+| Host | textos (`rules` o `dialogAdapter`), `characters`, UI de inventario/combinar | `apps/web-demo/` |
+
+Cumple la [regla de oro](03-rules-core-vs-render.md): el core no importa React, R3F, `window` ni `document`.
diff --git a/docs/authoring/01-scenes-and-hotspots.md b/docs/authoring/01-scenes-and-hotspots.md
new file mode 100644
index 0000000..dd17572
--- /dev/null
+++ b/docs/authoring/01-scenes-and-hotspots.md
@@ -0,0 +1,129 @@
+# 1. Escenas, transiciones, hotspots y verbos
+
+Una escena es un objeto `GameSceneConfig` (`packages/engine-core/src/game/runtime/types.ts`). Esta guía cubre lo que añade la 0.6.0: `hotspots`, `npcs` (ver [03](03-dialogues-and-npcs.md)), `initialItems` y `onEnter` (ver [02](02-conditions-and-actions.md) y [04](04-items-and-combining.md)) y las condiciones de las transiciones.
+
+## Hotspots
+
+Un hotspot es una caja clicable con reglas por **verbo**. Tipos reales (`packages/engine-core/src/game/types/index.ts`):
+
+```ts
+export type Verb = "look" | "use" | "talk";
+
+export interface GameSceneHotspot {
+ id: string;
+ /** Clave de i18n. */
+ label: string;
+ position: GameVec3;
+ halfSize: GameVec3;
+ rotationY?: number;
+ visibleWhen?: Condition;
+ hasCollision?: boolean;
+ /** Punto al que camina el jugador antes de actuar. Sin el, actua desde donde esta. */
+ approach?: GameVec3;
+ verbs?: Partial>;
+ /** Ramas por itemId al usar un item del inventario sobre el hotspot. */
+ useItem?: Record;
+ /** Ramas para un item sin regla propia en `useItem`. */
+ useItemDefault?: Branch[];
+}
+```
+
+- Cada verbo (y cada `useItem[itemId]`) es una lista de **ramas** `{ when?, do }`: gana la primera cuyo `when` se cumple (sin `when` se cumple siempre). Ver [02](02-conditions-and-actions.md).
+- Un verbo sin rama aplicable no aparece en el menú. Orden de preferencia del verbo por defecto: `talk`, `use`, `look` (`getDefaultVerb`, `packages/engine-core/src/game/narrative/hotspots.ts`).
+- Si solo hay un verbo aplicable, el click lo ejecuta; si hay varios, el renderer muestra `VerbMenu`.
+- `approach`: el jugador camina ahí antes del guion (se antepone un `walkTo`).
+- `visibleWhen`: oculta el hotspot mientras no se cumpla.
+- Soltar un ítem del inventario sobre el hotspot equivale al verbo `useItem` (`hotspot:interact` con `verb: "useItem"`).
+
+Si no hay regla aplicable, el comando emite `hotspot:noAction` (`reason`: `"not-found" | "hidden" | "missing-item" | "no-rule"`) y el renderer dice la frase `engine.hotspot.noAction`.
+
+## Ejemplo: el cofre y el mapa de "El faro"
+
+Copiado de `packages/engine-core/src/__tests__/fixtures/miniAdventure.ts` (escena `beach`):
+
+```ts
+import { act, branch, cond, otherwise, type GameSceneConfig } from "@pointclick-engine/engine-core";
+
+const zone = [0.5, 1, 0.5] as [number, number, number];
+
+const hotspots: GameSceneConfig["hotspots"] = [
+ {
+ id: "chest",
+ label: "chest.label",
+ position: [-3, 0, 2],
+ halfSize: zone,
+ approach: [-2, 0, 2],
+ verbs: {
+ look: [otherwise(act.say("chest.look"))],
+ use: [
+ branch(cond.flag("chest.open"), act.say("chest.empty")),
+ otherwise(act.say("chest.locked")),
+ ],
+ },
+ useItem: {
+ "rusty-key": [
+ branch(cond.flag("chest.open"), act.say("chest.alreadyOpen")),
+ otherwise(
+ act.say("chest.unlock"),
+ act.removeItem("rusty-key"),
+ act.setFlag("chest.open"),
+ act.giveItem("lens"),
+ ),
+ ],
+ },
+ useItemDefault: [otherwise(act.say("chest.nothing"))],
+ },
+ {
+ id: "map",
+ label: "map.label",
+ position: [0, 0, -3],
+ halfSize: zone,
+ verbs: { look: [otherwise(act.say("map.look"), act.setFlag("map.seen"))] },
+ },
+];
+```
+
+Lee: mirar el cofre siempre da la misma frase; usarlo dice "cerrado" hasta que `chest.open`; la llave lo abre una vez; cualquier otro ítem cae en `useItemDefault`.
+
+## Transiciones con condición
+
+Todas las transiciones (`collision`, `item-drop`...) aceptan dos campos nuevos (`BaseSceneTransition`, mismo archivo de tipos):
+
+```ts
+ /**
+ * Condicion para que la transicion ocurra (todos los tipos). Sin ella, siempre ocurre.
+ * Si no se cumple no hay cambio de escena y, si existe, corre `blocked`.
+ */
+ when?: Condition;
+ /** Guion que corre al intentar la transicion sin cumplir `when`. */
+ blocked?: Script;
+```
+
+Del fixture (escena `cove`):
+
+```ts
+transitions: [
+ {
+ id: "to-lighthouse",
+ kind: "collision",
+ targetSceneId: "lighthouse",
+ position: [0, 0, 7],
+ halfSize: [2, 1, 0.5],
+ when: cond.flag("keeper.lit"),
+ blocked: [act.say("lighthouse.locked")],
+ },
+],
+```
+
+El renderer aplica `when`/`blocked` con `evaluateTransitionGate` antes de cambiar de escena. El callback `canLeaveScene` de 0.5.0 sigue existiendo como vía avanzada y se evalúa **después**: solo si `when` deja pasar puede además vetar.
+
+## Elementos de escena declarativos
+
+| Campo | Qué es | Guía |
+|-------|--------|------|
+| `hotspots` | cajas con verbos | esta |
+| `npcs` | personajes con los que hablar | [03](03-dialogues-and-npcs.md) |
+| `initialItems` | ítems sembrados una vez por escena, con `when` opcional | [04](04-items-and-combining.md) |
+| `onEnter` | ramas que corren en cada entrada | [02](02-conditions-and-actions.md) |
+
+Los hotspots y NPC se conservan al registrar la escena (`registerScene` / `scenes` de `createGameRuntime`).
diff --git a/docs/authoring/02-conditions-and-actions.md b/docs/authoring/02-conditions-and-actions.md
new file mode 100644
index 0000000..983d910
--- /dev/null
+++ b/docs/authoring/02-conditions-and-actions.md
@@ -0,0 +1,111 @@
+# 2. Flags, condiciones y acciones
+
+El estado de mundo son **flags** con nombre (`boolean | number | string`, `FlagValue` en `packages/engine-core/src/game/state/worldStateStore.ts`) y la lista de escenas visitadas. Las condiciones lo leen sin efectos; las acciones lo cambian y mueven el juego.
+
+## Condiciones
+
+Tipo real (`packages/engine-core/src/game/narrative/conditions.ts`):
+
+```ts
+export type Condition =
+ | { flag: string; equals?: FlagValue; gte?: number; lte?: number } // sin operador: "es verdadero"
+ | { hasItem: string; atLeast?: number }
+ | { itemPlaced: string; inScene?: string; at?: string } // at = interactionId
+ | { inScene: string }
+ | { visited: string }
+ | { all: Condition[] }
+ | { any: Condition[] }
+ | { not: Condition };
+```
+
+- `flag` sin operador es verdadero para `true`, un número distinto de 0 o un texto no vacío. Un flag nunca puesto es falso.
+- Una condición `undefined` cuenta como verdadera. Una forma desconocida se evalúa a `false` (con un `console.warn`).
+- Constructores `cond`: `cond.flag("x")`, `cond.flag("n", { gte: 3 })`, `cond.hasItem`, `cond.itemPlaced`, `cond.inScene`, `cond.visited`, `cond.all(...)`, `cond.any(...)`, `cond.not(c)`. Devuelven objetos planos.
+
+## Acciones y guiones
+
+Tipo real (`packages/engine-core/src/game/narrative/actions.ts`):
+
+```ts
+export type Action =
+ | { say: string; speaker?: string } // clave de dialogo; espera al cierre
+ | { setFlag: string; value?: FlagValue } // por defecto true
+ | { giveItem: string }
+ | { removeItem: string }
+ | { placeItem: PlacedSceneItem }
+ | { removePlacedItem: string }
+ | { changeScene: string; spawnPosition?: GameVec3 }
+ | { walkTo: GameVec3 } // espera al fin o al aborto de la caminata
+ | { wait: number } // ms, via ClockPort
+ | { playSfx: string }
+ | { startDialogue: string } // tarea 07; espera al final
+ | { lockInput: boolean }
+ | { emit: string; payload?: unknown } // evento { type: "custom", name, payload }
+ | { call: string; args?: unknown }; // manejador registrado por el host
+
+export type Script = Action[];
+export type Branch = { when?: Condition; do: Script };
+```
+
+Un **guion** es una lista de acciones que se ejecutan **en orden**, una a la vez. Constructores `act.*` (uno por acción) y, para ramas, `branch(when, ...acciones)` y `otherwise(...acciones)` (rama sin condición, siempre la última).
+
+Un guion lo ejecuta el secuenciador: cola FIFO, cancelable, con `ClockPort` inyectado. Desde fuera: `runtime.runScript(script, { interrupt? })` o el comando `script:run` (`interrupt` cancela el actual y vacía la cola); `script:cancelAll` los cancela todos. Eventos: `script:started`, `script:finished` (`result: "finished" | "cancelled"`).
+
+### Ramas: gana la primera
+
+`pickBranch` recorre las ramas en orden y corre la primera cuyo `when` se cumple. Por eso `otherwise(...)` va al final:
+
+```ts
+use: [
+ branch(cond.flag("chest.open"), act.say("chest.empty")),
+ otherwise(act.say("chest.locked")),
+],
+```
+
+## Dos reglas de orden que muerden
+
+**`say` espera a que se cierre el bocadillo** (unos segundos): el guion no sigue hasta el evento `dialog:dismissed`. Los cambios de estado que deban quedar hechos cuanto antes (`giveItem`, `removeItem`, `setFlag`...) van **antes** del `say`. Así lo hace la demo en `demo-content/items/index.ts`:
+
+```ts
+combine: {
+ "key-bit": [
+ otherwise(
+ // `say` espera a que se cierre el bocadillo: el resultado va antes que la frase.
+ act.removeItem("key-handle"),
+ act.removeItem("key-bit"),
+ act.giveItem("bronze-key"),
+ act.say("combine.key.done"),
+ ),
+ ],
+},
+```
+
+**`onEnter` "solo la primera vez" se hace con un flag, no con `visited`.** Cuando se evalúa `onEnter`, la escena ya cuenta como visitada: `not(visited(...))` nunca se cumpliría. Del fixture (escena `beach`):
+
+```ts
+// Solo la primera vez: el flag, no `visited` (al evaluarse la escena ya cuenta como visitada).
+onEnter: [branch(cond.not(cond.flag("intro.done")), act.say("beach.intro"), act.setFlag("intro.done"))],
+```
+
+`onEnter` corre en **cada** entrada a la escena; sin flag, repite (la demo lo usa así para su bienvenida: `onEnter: [otherwise(act.say("personalRoomWelcome"))]`).
+
+## Cuándo usar `call`
+
+`call` invoca un manejador con nombre que registra el host: es la vía de escape para lo que el vocabulario no cubre (créditos, analíticas, abrir una pantalla). Si el mismo `call` se repite en varios juegos, es candidato a acción nueva. Del fixture, escena `lighthouse`:
+
+```ts
+onEnter: [
+ branch(
+ cond.flag("keeper.lit"),
+ act.say("lighthouse.ending"),
+ act.call("credits", { ending: "good" }),
+ act.setFlag("game.finished"),
+ ),
+],
+```
+
+El host lo registra con `runtime.registerHandler("credits", (args) => ...)` (devuelve la función que lo quita). Para que `validateContent` avise de un `call` sin manejador, pasa sus nombres en `handlerNames` de la config del runtime (en `GameContent` el campo se llama `handlers`). Un `call` sin manejador avisa por consola y el guion continúa; si el manejador devuelve una promesa, el guion la espera.
+
+## Quién aplica las reglas declarativas
+
+`initialItems`, `onEnter` y `transition.when`/`blocked` los aplica el **renderer** con funciones puras del core (`resolveInitialItems`, `resolveEnterScript`, `evaluateTransitionGate`). En headless los aplica `createPlaythrough` ([05](05-saving-and-testing.md)). Los callbacks de 0.5.0 (`canLeaveScene`, `onSceneEnter`, `getInitialPlacedItems`) siguen funcionando, se evalúan **después** de los declarativos y son vía avanzada.
diff --git a/docs/authoring/03-dialogues-and-npcs.md b/docs/authoring/03-dialogues-and-npcs.md
new file mode 100644
index 0000000..f186668
--- /dev/null
+++ b/docs/authoring/03-dialogues-and-npcs.md
@@ -0,0 +1,159 @@
+# 3. Diálogos con opciones y NPCs
+
+No confundir: `dialog:*` (singular) es el **bocadillo de una frase**; `dialogue:*` es una **conversación** con varios turnos y opciones.
+
+## Árbol de diálogo
+
+Tipos reales (`packages/engine-core/src/game/narrative/dialogueTypes.ts`):
+
+```ts
+export interface DialogueChoice {
+ /** Clave de i18n del texto de la opcion. */
+ text: string;
+ /** Opcion oculta si no se cumple. */
+ when?: Condition;
+ /** Desaparece tras elegirla (se recuerda con el flag `dlg...`). */
+ once?: boolean;
+ do?: Script;
+ next?: string;
+}
+
+export interface DialogueNode {
+ id: string;
+ /** Id de NPC o "player". */
+ speaker?: string;
+ /** Clave de i18n; sin linea, el nodo solo ejecuta `do`. */
+ line?: string;
+ /** Efectos al entrar en el nodo (se esperan antes de seguir). */
+ do?: Script;
+ /** Sin opciones visibles, avanza a `next`. */
+ choices?: DialogueChoice[];
+ /** Sin next ni opciones visibles, el dialogo termina. */
+ next?: string;
+}
+
+export interface DialogueDefinition { id: string; start: string; nodes: DialogueNode[] }
+```
+
+Constructores: `dialogue.define(id, start, ...nodos)`, `dialogue.node(id, props)`, `dialogue.choice(text, props)`. Se registran en `dialogues` de `createGameRuntime`. La conversación termina con `dialogue:ended` (`reason`: `"finished" | "ended" | "cancelled"`).
+
+Ejemplo del fixture (`miniAdventure.ts`, pescador de la playa):
+
+```ts
+import { act, cond, dialogue } from "@pointclick-engine/engine-core";
+
+dialogue.define(
+ "fisher-talk",
+ "root",
+ dialogue.node("root", {
+ speaker: "fisherman",
+ line: "fisher.hello",
+ choices: [
+ // 0: la pista solo si ya se miro el mapa; una sola vez.
+ dialogue.choice("ask.frame", {
+ when: cond.flag("map.seen"),
+ once: true,
+ do: [act.say("fisher.frame", "fisherman"), act.giveItem("lamp-frame")],
+ next: "root",
+ }),
+ // 1: saludo, solo la primera vez.
+ dialogue.choice("ask.weather", { once: true, do: [act.say("fisher.weather", "fisherman")], next: "root" }),
+ // 2: despedida (sin next: termina la conversacion).
+ dialogue.choice("bye"),
+ ],
+ }),
+);
+```
+
+Reglas que se ven ahí:
+
+- El **índice** de una opción es su posición original en `node.choices` (0, 1, 2), aunque otras estén ocultas. Es lo que usan `dialogue:choose` y `choose()` del playthrough.
+- `when` oculta la opción; `once` la oculta tras elegirla (queda el flag `dlg.fisher-talk.root.0`).
+- Una opción sin `next` termina la conversación.
+- Al elegir, se cierra la línea, corre el `do` de la opción (espera cada acción, `say` incluido, ver [02](02-conditions-and-actions.md)) y luego se pasa a `next`.
+
+Un caso real de la demo (`apps/web-demo/demo-content/dialogues/guide.ts`) usa `cond.hasItem("trophy")` en una opción y `act.giveItem("key-handle")` en otra con `once`.
+
+## NPCs
+
+Un NPC es un hotspot con sprite. Tipo real (`packages/engine-core/src/game/types/index.ts`):
+
+```ts
+export interface GameSceneNpc {
+ id: string;
+ /** Clave de i18n. */
+ name: string;
+ /** Id de un personaje registrado en el viewport (prop `characters`). */
+ characterId: string;
+ position: GameVec3;
+ facing?: NpcFacing; // "north" | "south" | "west" | "east"
+ visibleWhen?: Condition;
+ hasCollision?: boolean;
+ approach?: GameVec3;
+ clickBox?: { halfSize: GameVec3; offset?: GameVec3 };
+ /** Atajo: hablar inicia este diálogo. Equivale a `verbs.talk = [{ do: [{ startDialogue }] }]`. */
+ dialogueId?: string;
+ verbs?: Partial>;
+ useItem?: Record;
+}
+```
+
+Del fixture (escena `cove`): un guardián con diálogo, que además acepta la lámpara y se deja mirar:
+
+```ts
+npcs: [
+ {
+ id: "keeper",
+ name: "keeper.name",
+ characterId: "keeper",
+ position: [2, 0, 2],
+ dialogueId: "keeper-talk",
+ useItem: {
+ lamp: [
+ otherwise(
+ act.say("keeper.thanks", "keeper"),
+ act.removeItem("lamp"),
+ act.setFlag("keeper.lit"),
+ ),
+ ],
+ },
+ verbs: { look: [otherwise(act.say("keeper.look"))] },
+ },
+],
+```
+
+- `dialogueId` es un atajo de `verbs.talk`; un `verbs.talk` explícito gana.
+- `clickBox` ajusta la caja clicable (por defecto cubre un sprite de tamaño estándar, de los pies a la cabeza).
+- `characterId` apunta a un `CharacterDefinition` que pasas en la prop `characters` de `GameViewport` (`Record`). La demo lo hace en `apps/web-demo/demo-content/characters/guide.ts` (`DEMO_NPC_CHARACTERS`).
+
+### El `speaker` debe ser el `id` del NPC
+
+Para que el bocadillo salga sobre el NPC, el `speaker` de la línea (`node.speaker`) o de `say` debe ser **exactamente el `id`** del NPC (`"fisherman"`, `"keeper"`). Si no coincide con un NPC visible, el bocadillo sale sobre el jugador (`resolveSpeakingNpcId`).
+
+### Proyección a hotspot y `resolveScene`
+
+`toRuntimeScene` añade cada NPC a `scene.hotspots` con `npcToHotspot`, para que `hotspot:interact` los encuentre. Un host que **sobrescriba `resolveScene`** con sus propias escenas debe proyectar él los NPC. Así lo hace la demo (`apps/web-demo/app/lib/engine/runtime/demoViewportOptions.ts`):
+
+```ts
+import { npcToHotspot, type GameScene } from "@pointclick-engine/engine-core";
+
+function resolveDemoScene(id: string): GameScene | null {
+ const scene = SCENES[id];
+ if (!scene) return null;
+ if (!scene.npcs?.length) return scene;
+ return { ...scene, hotspots: [...(scene.hotspots ?? []), ...scene.npcs.map(npcToHotspot)] };
+}
+```
+
+## Comandos, eventos y UI
+
+| Comando | Efecto |
+|---------|--------|
+| `dialogue:start` `{ dialogueId }` | Abre la conversación (también la acción `startDialogue`) |
+| `dialogue:choose` `{ index }` | Elige la opción con ese índice original |
+| `dialogue:advance` | Cierra la línea abierta (sin opciones) y sigue al `next` |
+| `dialogue:end` | Cierra la conversación |
+
+Eventos: `dialogue:started`, `dialogue:nodeEntered`, `dialogue:choiceMade`, `dialogue:ended`.
+
+El renderer pinta las opciones con `DialogueChoices` (flechas, Enter/Espacio y teclas 1-9) y la línea en el bocadillo del `speaker`. Sustitúyelo con la prop `dialogueChoices` de `GameViewport`; `useDialogue()` da `{ active, speaker, choices, choose, advance, end }` para una UI propia. Mientras hay conversación la entrada del jugador queda bloqueada.
diff --git a/docs/authoring/04-items-and-combining.md b/docs/authoring/04-items-and-combining.md
new file mode 100644
index 0000000..47f35e5
--- /dev/null
+++ b/docs/authoring/04-items-and-combining.md
@@ -0,0 +1,105 @@
+# 4. Ítems, reglas de drop y combinaciones
+
+## Ítems
+
+`GameItemConfig` (`packages/engine-core/src/game/runtime/types.ts`):
+
+```ts
+export type GameItemConfig = {
+ id: string;
+ name: string;
+ spriteUrl: string;
+ descriptionDialogKey?: string;
+ pickupSoundUrl?: string;
+ dropSoundUrl?: string;
+ interactionRules: Record;
+ defaultRule: GameItemRule;
+ /** Ramas condicionales para combinar este ítem con otro por id. */
+ combine?: Record;
+};
+```
+
+`interactionRules` (por id de interacción) y `defaultRule` son las **reglas de drop** de 0.5.0: qué pasa al soltar el ítem sobre una diana de arrastre (`GameItemRule.outcome`: `"place"` lo deja en la escena, `"consume"` lo gasta, `"return"` vuelve al inventario; más `hitDialogKey`, `missDialogKey`...). No cambian en 0.6.0. Los ítems que no se sueltan en dianas usan `interactionRules: {}` y `defaultRule: { outcome: "return" }`, como el fixture:
+
+```ts
+const item = (id: string, extra: Partial = {}): GameItemConfig => ({
+ id,
+ name: `item.${id}`,
+ spriteUrl: `/${id}.png`,
+ interactionRules: {},
+ defaultRule: { outcome: "return" },
+ ...extra,
+});
+```
+
+## Combinar dos ítems
+
+La regla se declara en **uno** de los ítems: `combine[idDelOtro]` es una lista de ramas ([02](02-conditions-and-actions.md)). Vale en **ambos sentidos**: `resolveCombine(a, b)` busca primero `a.combine[b.id]` y, si no existe, `b.combine[a.id]`. Del fixture:
+
+```ts
+import { act, otherwise, type GameItemConfig } from "@pointclick-engine/engine-core";
+
+const lens: GameItemConfig = item("lens", {
+ combine: {
+ "lamp-frame": [
+ otherwise(
+ act.say("combine.lamp"),
+ act.removeItem("lens"),
+ act.removeItem("lamp-frame"),
+ act.giveItem("lamp"),
+ ),
+ ],
+ },
+});
+```
+
+El guion **decide** el resultado: el comando `inventory:combine` no quita ni da nada por su cuenta, solo corre la rama. Recuerda el orden de [02](02-conditions-and-actions.md): `say` espera al cierre del bocadillo, así que la demo (`demo-content/items/index.ts`) pone `removeItem`/`giveItem` **antes** del `say`.
+
+Comando y eventos:
+
+| | |
+|--|--|
+| Comando | `inventory:combine` `{ itemId, withItemId }` |
+| Éxito | `item:combined` `{ itemId, withItemId }` y se corre el guion |
+| Fallo | `item:combineFailed` si son el mismo ítem, falta alguno en el inventario, no está registrado o no hay rama aplicable |
+
+El renderer **no** trae UI de combinar: la UI del inventario es del host. La demo lanza el comando al soltar un ítem sobre otro slot ocupado (`apps/web-demo/app/components/GameTouchCanvas.tsx`) y explica `item:combineFailed` con una frase.
+
+## Usar un ítem sobre un hotspot o NPC
+
+`useItem[itemId]` del hotspot/NPC (ver [01](01-scenes-and-hotspots.md)) y `useItemDefault` para el resto. Solo se ejecuta si el jugador tiene el ítem: si no, `hotspot:noAction` con `reason: "missing-item"`. En el fixture, la llave abre el cofre y cualquier otra cosa cae en `useItemDefault`.
+
+## Ítems iniciales en la escena (`initialItems`)
+
+Se siembran **una vez por escena** al entrar por primera vez; cada uno con un `when` opcional evaluado en ese momento (`SceneInitialItem`, `packages/engine-core/src/game/types/index.ts`):
+
+```ts
+export interface SceneInitialItem {
+ item: PlacedSceneItem;
+ when?: Condition;
+}
+```
+
+Del fixture (escena `cove`), el pescado solo aparece si ya se pasó por la playa:
+
+```ts
+initialItems: [
+ { item: placed("fish-on-rocks", "fish", "rocks", "cove"), when: cond.visited("beach") },
+],
+```
+
+Notas:
+
+- `PlacedSceneItem` (mismo archivo): `id`, `itemId`, `interactionId`, `name`, `spriteUrl`, `worldPosition`, `canPickup`, y opcionales `hasCollision`, `collisionHalfSize`, `pickupSuccessDialogKey`, `pickupBlockedDialogKey`, `sceneId`. Un ítem sin `sceneId` recibe el de la escena que lo siembra.
+- El `interactionId` de un ítem colocado es una **etiqueta libre**, no una referencia validada: no tiene que existir en `interactions` (el validador no lo comprueba).
+- Una escena sembrada no vuelve a sembrarse al reentrar (se recuerda en `seededSceneIds` del guardado). La demo (`scenes.ts`, `personalRoom`) usa un `when` con `cond.not(cond.itemPlaced("trophy"))` para no duplicar el trofeo.
+- Los ítems también se pueden dar y quitar en un guion: `act.giveItem`, `act.removeItem`, `act.placeItem`, `act.removePlacedItem`.
+
+## Recoger y soltar por comando
+
+| Comando | Campos nuevos en 0.6.0 |
+|---------|------------------------|
+| `inventory:pickup` | `placedItemId?` (el `id` del ítem colocado) |
+| `inventory:drop` | `interactionId?` o `hotspotId?` (como mucho uno; `hotspotId` equivale a `hotspot:interact` con `verb: "useItem"`) |
+
+Eventos: recoger emite `item:pickedUp` (desde 0.5.0; no `item:dropped`) o `inventory:pickupFailed` (`reason`: `"not-found" | "blocked" | "full" | "unknown-item"`); un guion emite además `item:removed` e `inventory:full` (inventario lleno al hacer `giveItem`). Estos comandos solo cambian estado: los textos (`hitDialogKey`, `pickup*DialogKey`) los muestra el renderer, y un guion los declara con `say`.
diff --git a/docs/authoring/05-saving-and-testing.md b/docs/authoring/05-saving-and-testing.md
new file mode 100644
index 0000000..d086c72
--- /dev/null
+++ b/docs/authoring/05-saving-and-testing.md
@@ -0,0 +1,112 @@
+# 5. Guardado, validación y test de recorrido
+
+## Guardado único
+
+Toda la partida vive en **una instantánea** JSON bajo una sola clave (`pointclick-save` por defecto). Tipo real (`packages/engine-core/src/game/state/saveGame.ts`):
+
+```ts
+export interface GameSnapshot {
+ version: number;
+ sceneId: string;
+ playerPosition?: GameVec3;
+ inventory: InventorySlotsState;
+ placedItems: PlacedSceneItem[];
+ seededSceneIds: string[];
+ flags: Record;
+ visitedSceneIds: string[];
+ /** Estado propio del host (p. ej. puertas de la demo). Opaco para el core. */
+ extra?: Record;
+}
+```
+
+Se activa pasando un almacenamiento a `createGameRuntime` (`storage: KeyValueStoragePort`, y opcionalmente `saveKey`). Sin `storage`, los comandos solo avisan por consola.
+
+| Comando | Evento | Qué hace |
+|---------|--------|----------|
+| `game:save` `{ extra? }` | `game:saved` | Escribe la instantánea (`extra` = estado propio del host) |
+| `game:load` | `game:loaded` `{ found, applied?, extra? }` | Lee y restaura; `applied` es `false` si la escena guardada no está registrada |
+| `game:reset` | `game:reset` | Vacía inventario, ítems, flags y borra la clave de guardado (no cambia de escena) |
+
+Detalles que importan:
+
+- Orden al restaurar: inventario, ítems colocados, flags, y **al final** la escena, para que lo que se evalúe al entrar vea el estado ya restaurado (`applySnapshot`).
+- `loadGame` nunca lanza: devuelve `null` si no hay partida, el JSON es inválido, la forma no cuadra o la versión es superior a `SAVE_FORMAT_VERSION` (hoy 1).
+- Para cambiar el formato: sube `SAVE_FORMAT_VERSION` y añade la entrada a `SAVE_MIGRATIONS` (`{ [versionOrigen]: migración }`).
+- `playerPosition` es opcional: sin ella, la escena usa su `playerSpawn`.
+- Una partida de 0.5.0 (cuatro claves sueltas: `inventory-slots`, `current-scene-id`, `placed-items-state`...) se convierte con `migrateLegacySave(storage, { defaultSceneId, legacySeededSceneId?, extraKeys? })`, que **no** borra las claves antiguas ni escribe la nueva: eso lo decides tú. La demo lo hace en `apps/web-demo/app/lib/gamePersistence.ts`, que además guarda sus puertas en `extra`.
+
+## Validación del contenido
+
+`validateContent(content)` recorre escenas, ítems y diálogos y devuelve una lista de incidencias (`ContentIssue`: `severity`, `code`, `where`, `message`). Con `createGameRuntime` corre sola, según la opción `validate`:
+
+| `validate` | Efecto |
+|------------|--------|
+| (sin valor) | Como `true` solo cuando `NODE_ENV === "development"`; nada en test o producción |
+| `true` | Un único `console.warn` agrupado |
+| `"throw"` | Lanza si hay errores (los avisos van a consola) |
+| `false` | No valida |
+
+Para que compruebe las claves de texto y los `call`, pasa `dialogKeys` (conjunto de claves conocidas) y `handlerNames` (nombres de manejadores) en la config del runtime. En `GameContent`, que recibe `validateContent` directamente, se llaman `dialogKeys` y `handlers`.
+
+Códigos (`packages/engine-core/src/game/narrative/validate*.ts`):
+
+| Severidad | Códigos |
+|-----------|---------|
+| error | `duplicate-id`, `unknown-item`, `unknown-scene`, `unknown-interaction`, `unknown-dialogue`, `unknown-dialogue-start`, `unknown-dialogue-node`, `dialogue-dead-end`, `unknown-verb`, `unknown-action`, `unknown-branch`, `unknown-condition` |
+| warning | `unknown-dialog-key`, `unknown-handler`, `unreachable-scene`, `unreachable-dialogue-node`, `unused-item`, `flag-never-set`, `flag-never-read` |
+
+El `interactionId` de un ítem colocado no se valida (es una etiqueta libre).
+
+## Test de recorrido headless
+
+`createPlaythrough` monta el runtime real con reloj virtual (`HeadlessClock`), almacenamiento en memoria y caminata instantánea, **sin renderer**. Se importa del subpath `@pointclick-engine/engine-core/testing`. Valida el contenido y lanza si hay errores. Hay **una sola partida viva por proceso** (los registros son globales): llama a `dispose()` al terminar cada test.
+
+Sin renderer, `createPlaythrough` aplica por su cuenta las reglas declarativas que en el juego aplica el renderer (`initialItems`, `onEnter`, `when`/`blocked`). Del test `miniAdventure.playthrough.test.ts`:
+
+```ts
+import { createPlaythrough, type Playthrough } from "@pointclick-engine/engine-core/testing";
+import { miniAdventure } from "./fixtures/miniAdventure";
+
+const p = createPlaythrough(miniAdventure, {
+ handlers: { credits: (args) => void credits.push(args) },
+ onRuntime: (rt) =>
+ void rt.on("dialog:triggered", (e) => {
+ if (e.dialogKey) said.push(e.dialogKey);
+ }),
+});
+await p.settle();
+
+// Puzzle 1: recoger y usar.
+await p.pickUp("key-on-sand");
+await p.useItemOn("rusty-key", "chest");
+expect(p.state().inventory).toEqual(["lens"]);
+expect(p.state().flags["chest.open"]).toBe(true);
+
+// Puzzle 2: conversacion condicionada por haber mirado el mapa.
+await p.look("map");
+await p.talk("fisherman");
+await p.choose(0);
+await p.choose(2);
+
+// Puzzle 3: combinar; luego cambio de escena.
+await p.combine("lens", "lamp-frame");
+await p.goThrough("to-cove");
+```
+
+API de `Playthrough` (`packages/engine-core/src/testing/playthrough.ts`):
+
+| Método | Qué hace |
+|--------|----------|
+| `look(id)`, `use(id)`, `talk(id)` | Verbo sobre el hotspot o NPC `id`; `talk` se detiene en la primera elección pendiente |
+| `useItemOn(itemId, id)` | Usa un ítem del inventario sobre el hotspot o NPC |
+| `combine(a, b)` | Combina dos ítems del inventario |
+| `pickUp(placedItemId)` | Recoge un ítem colocado de la escena activa |
+| `choose(index)` | Elige por **índice original** de `node.choices`; lanza si no está disponible ("no disponible") |
+| `goThrough(transitionId)` | Cruza una transición respetando `when`/`blocked` |
+| `settle()` | Avanza el reloj y cierra bocadillos hasta que no queden guiones |
+| `state()` | `{ sceneId, inventory, flags, dialogueActive }` |
+| `save()` | `GameSnapshot`; pásalo como `opts.snapshot` para reanudar |
+
+Opciones de `createPlaythrough`: `initialSceneId`, `handlers` (se registran antes de entrar en la escena inicial), `onRuntime` (antes de entrar, para suscribirse a eventos del arranque) y `snapshot`.
+
+Escribe también los recorridos "equivocados" (usar la llave sin tenerla, hablar antes de mirar el mapa, cruzar una transición bloqueada): el fixture los cubre en el mismo archivo.
diff --git a/docs/authoring/README.md b/docs/authoring/README.md
new file mode 100644
index 0000000..984f5eb
--- /dev/null
+++ b/docs/authoring/README.md
@@ -0,0 +1,79 @@
+# Guía de autoría
+
+Cómo escribir una aventura con el motor (0.6.0): escenas, puzzles y diálogos como **datos** TypeScript, sin callbacks. Modelo y motivación: [`../architecture/10-narrative-model.md`](../architecture/10-narrative-model.md) y [ADR-0010](../decisions/0010-declarative-narrative-model.md).
+
+> La versión de los paquetes todavía es 0.5.0: lo de esta guía es la 0.6.0 sin publicar (ver los `CHANGELOG.md`).
+
+## Orden de lectura
+
+1. [`01-scenes-and-hotspots.md`](01-scenes-and-hotspots.md) — escenas, transiciones, hotspots y verbos.
+2. [`02-conditions-and-actions.md`](02-conditions-and-actions.md) — flags, condiciones, acciones, ramas y `call`.
+3. [`03-dialogues-and-npcs.md`](03-dialogues-and-npcs.md) — árboles de diálogo con opciones y NPCs.
+4. [`04-items-and-combining.md`](04-items-and-combining.md) — ítems, reglas de drop y combinaciones.
+5. [`05-saving-and-testing.md`](05-saving-and-testing.md) — guardado, validación y test de recorrido.
+
+## Ejemplos que se ejecutan
+
+Los fragmentos de la guía están copiados de código que corre:
+
+- `packages/engine-core/src/__tests__/fixtures/miniAdventure.ts`: "El faro", una mini-aventura completa (3 escenas, 2 NPC, 5 ítems, 4 puzzles encadenados). Su test `miniAdventure.playthrough.test.ts` la resuelve sin renderer.
+- `apps/web-demo/demo-content/`: escenas, ítems y el diálogo `dialogues/guide.ts` de la demo.
+- `apps/web-demo/app/example-minimal/page.tsx`: un hotspot y un ítem inicial en una escena, montados con `GameViewport`.
+
+## Lo mínimo: un hotspot que habla
+
+Tomado de `example-minimal/page.tsx`. Una escena con un hotspot `notice` cuyo verbo `look` pone un flag y dice una frase:
+
+```ts
+import { act, otherwise, type GameSceneConfig } from "@pointclick-engine/engine-core";
+
+const SCENE_A: GameSceneConfig = {
+ id: "minimal-a",
+ label: "Minimal Scene A",
+ background: "/assets/background/town.jpg",
+ playerSpawn: [3.08, 1.05, 13.44],
+ ground: { minX: -12, maxX: 17, minZ: -15, maxZ: 30, y: -3.25 },
+ walls: [],
+ interactions: [],
+ hotspots: [
+ {
+ id: "notice",
+ label: "notice.label",
+ position: [6.0, 2.6, 13.4],
+ halfSize: [0.7, 1.2, 0.5],
+ verbs: {
+ look: [otherwise(act.setFlag("notice.seen"), act.say("notice.look"))],
+ },
+ },
+ ],
+};
+```
+
+Con un solo verbo, un click lo ejecuta directamente; con varios sale un menú de verbos.
+
+## Textos: `say` y las líneas resuelven una clave
+
+`say`, `line`, `text` y `label` son **claves**, no texto. Se resuelven así (`dialog:trigger`, `packages/engine-core/src/game/runtime/executors.ts`):
+
+- Con reglas registradas: `rules: [{ key, phrases }]` en `createGameRuntime` (o `registerRule`). Se elige una frase al azar.
+- O con un `dialogAdapter` propio que traduzca la clave, como hace la demo (`apps/web-demo/app/lib/engine/runtime/demoViewportOptions.ts`).
+- Sin ninguno de los dos se muestra la clave literal.
+
+```ts
+const created = createGameRuntime({
+ scenes: [SCENE_A, SCENE_B],
+ items: [TROPHY_ITEM],
+ rules: [{ key: "notice.look", phrases: ["Un cartel de la plaza: 'SE BUSCA... un buen guía.'"] }],
+});
+```
+
+## Dónde mirar cuando algo no funciona
+
+| Síntoma | Causa habitual | Guía |
+|---------|----------------|------|
+| El bocadillo sale sobre el jugador y no sobre el NPC | `speaker` no es exactamente el `id` del NPC | [03](03-dialogues-and-npcs.md) |
+| El `onEnter` de "solo la primera vez" no se dispara nunca | Se usó `not(visited(...))` | [02](02-conditions-and-actions.md) |
+| El cambio de estado tarda en aplicarse | Va después de un `say`, que espera al cierre del bocadillo | [02](02-conditions-and-actions.md) |
+| Aparece la clave en lugar del texto | Faltan `rules` o `dialogAdapter` | esta página |
+| El NPC no se puede clicar | El host usa su propio `resolveScene` y no proyecta NPC | [03](03-dialogues-and-npcs.md) |
+| Avisos en consola al arrancar | `validateContent` encontró referencias rotas | [05](05-saving-and-testing.md) |
diff --git a/docs/decisions/0009-runtime-lives-in-packages.md b/docs/decisions/0009-runtime-lives-in-packages.md
new file mode 100644
index 0000000..7434e44
--- /dev/null
+++ b/docs/decisions/0009-runtime-lives-in-packages.md
@@ -0,0 +1,51 @@
+# ADR-0009: El runtime vive en los paquetes, no en la demo
+
+**Status**: accepted (aprobado por el owner el 2026-10-10)
+**Issue**: [#21](https://github.com/DanielMartinezSebastian/pointclick-engine/issues/21)
+**Date**: 2026-10-10
+
+## Context
+
+`createGameRuntime`, los registros de escenas/ítems/reglas, los executors de comandos, `useGameState`, `useGameActions` y `GameViewport` viven en `apps/web-demo/app/lib/engine/publicApi.ts`. Consecuencias medidas en la auditoría del 2026-10-10:
+
+- `docs/LIBRARY_CONSUMPTION_GUIDE.md` documenta esos símbolos como exports de `@pointclick-engine/engine-renderer-r3f`, que no los exporta. Quien instale los paquetes publicados (0.4.0) no tiene runtime.
+- `GameViewport` renderiza un `