Codebase Map

For developers navigating the architecture, the Scanline Engine delegates its logic into specialized subsystems. Here is a high-level guide to the src/ directory:

• src/mechanics/: This directory houses the Text Parser and the AI Orchestrator (LLM Integration cascade). It handles all natural language processing and converts player text into executable execution plans.

Parser.ts: The central orchestrator that manages stage execution, target resolution, clarification loops, and linear plan execution.

ParserWorldModelBuilder.ts: Evaluates the current game state to construct the semantic projection (context and scope) that the parser relies on.

LlmCascade.ts: The Stage 2 AI layer that manages the scene-static and dynamic prompt splits, talks to the provider (e.g., Anthropic), and extracts JSON plans from the AI's responses.

NlpCascade.ts: The Stage 1.2 local neural network (NLP.js) for flexible intent recognition.

parserCommands.ts & parserLanguage.ts: Handles vocabulary normalization and data-driven custom command matching (e.g., TELEPORT WITH).

• src/systems/: This directory contains high-level gameplay logic and managers that actually mutate the world state.

GameSemanticAPI.ts: Implements semantic interactions triggered by parser plans (e.g., look, examine, take, put, open/close).

InventoryManager.ts: Manages player inventory, generic nested containers, and capacities.

SoundManager.ts: Governs the 3D Web Audio environment, including HRTF panning, reverb crossfading, and proximity EQ.

StateEventSystem.ts: Handles routing authored State component mutations into reusable script events (e.g., triggering a script when a TV turns on).

ShadowSystem.ts: Renders and manages dynamic actor shadows.

• src/scene/: Handles spatial topology, scene transitions, and world geometry.

Scene.ts: The primary data structure for loaded environments and collision logic (Walkbox movement constraints).

SceneManager.ts: Manages scene loading and centralized actor transfers between scenes.

SceneTextLayer.ts: Projects raw spatial hierarchies into titled, anchor-relative semantic text data for the parser.

SceneSpatialValidator.ts: Enforces world logic rules, such as preventing recursive containment and rejecting invalid storage setups.

• src/core/: The fundamental engine loops, text asset loaders, and UI managers.

Game.ts: The central game loop and singleton holding the primary state and execution contexts.

IGame.ts: The shared gameplay API contract utilized by the parser, UI, and custom scripts.

Console.ts: Controls the in-game text console, handles word-wrapping, manages modal dialogue states, and processes developer commands (#PEEK, #LLM-ON).

TextAssetManager.ts: Loads, caches, and provides lookup for .json text assets, semantic tags, and lore.