Skip to content

Home

Jump to bottom
Michael Voitovich edited this page Jun 19, 2026 · 19 revisions

Welcome to the Scanline wiki!

*** WORK IN PROGRESS ***

0. Introduction & Engine Architecture

About Scanline: Overview of the hybrid 2.5D interface (Point-n-Click + Text Parser), retro CRT aesthetics, and the AI-driven Game Master.

Tech Stack & Rendering Pipeline: Exploring the React + Vite + TypeScript foundation, HTML5 Canvas rendering, WebGL post-processing, and the Entity-Component System (ECS) architecture.

Installation & Deployment: Setting up the Node.js environment, hosting via web servers, and building native desktop applications using Tauri (Rust).

Codebase Map: A high-level guide to the src/ directory, covering mechanics, systems, scene, and core.

1. Main Elements of the Game World: Scenes and Objects

  • Scenes, Scene Object Hierarchy
  • Types of Scene Objects: Static, Actor, Quad, Triggerbox, Walkbox
  • Common Object Properties

2. World Model & Spatial System

  • Raw vs. Semantic Spatial Projection: Understanding the difference between strict geometric object placement and the text-facing semantic model.
  • Anchor-Relative Rules: How the engine evaluates spatial relations (in, on, under, behind) relative to titled semantic anchors while collapsing untitled technical nodes.
  • Containers & Storage: Rules for explicitly defining storage using Inventory and Surface components, and why the near relation is restricted.
  • Visibility & Actionability: Managing access through Blocker components, closed Switch objects, and discovering lookable/examinable hidden items.
  • Subscenes: Activating close-up modal views, managing virtual spatial nodes, and handling subscene-specific item scaling.

3. Entities & Component System

Scene Object Classes: The hierarchy of Static, Actor, QuadObject, WalkBox, and TriggerBox entities

. Core Components Overview: Utilizing the strict AnyComponent system to attach modular logic like Shadow, Exit/Entry transitions, and Switch states . State Event System: Defining mutable states (e.g., open/close, power) and automa

tically dispatching script events (state:=) upon runtime changes . Correctional vs. Portable Scale: How to use Scene Correctional Scale for editor-only normalization without breaking portable object references

.

4. Text Parser & UI

The 3-Stage Parser Cascade: How input flows sequentially through Regex (Stage 1.1) ➔ NLP.js (Stage 1.2) ➔ LLM Game Master (Stage 2)

. Parser Core Orchestrator: Handling target resolution, resolving ambiguities through numbered clarification loops, and dispatching valid actions to the Game API . Unified Parser DSL: The declarative ParserPlannedAction format used to securely send linear execution plans to the engine without executing raw code . Custom Command Assets: Creating data-driven parser commands (like TELEPORT WITH) using JSON configurations . Text Assets & Lore: Configuring JSON text assets, injecting semanticTags and relationFacts, and handling multi-line descriptions . Console & Inventory UI: The closed/open state of the text console, multiline modal output, input history, and image-only inventory previews

.

5. Artificial Intelligence & NPCs

The LLM Game Master: Leveraging Anthropic's Claude to orchestrate atmospheric fallbacks for unsupported intents and enforce "Spoiler Protection" for hidden entities

. Prompt Caching & Splitting: Splitting the LLM payload into a scene-static system block and a dynamic per-call user block to minimize token latency . Parser Notes (PN): Using runtime-only, private memory for the AI to track invented facts, along with the parserNoteNeedsCheck stale-flag mechanic . NPC Puppet Master System: The architecture of autonomous NPCs, scene logs, dialog generation (SAY), background timer events, and DSL execution (MOVE_TO, TAKE)

.

6. 3D Audio Environment

Web Audio API Integration: The routing graph utilizing DSP effects and HRTF panning

. 2.5D Spatial Mathematics: Mapping visual parallax and camera zoom into acoustic Z-depth for 3D positional audio . Proximity EQ & Crossfading: Implementing +6dB bass boosts at close ranges and true dry/wet convolution reverb crossfades governed by Reverb Drown Distances

.

7. Scripting System

TypeScript & Hot-Reloading: Registering scripts in src/scripts/ and attaching them to in-game triggers

. ScriptAPI Reference: Utilizing api.wait(), api.playSoundAttached(), api.getQuad(), and scene manipulation functions . Async Timing Limits: Understanding scene-bound execution and why native browser Promises or fetch() should be avoided during inactive scenes . Actor Navigation: Routing actor movement via actor.moveTo(x, y) and utilizing A* pathfinding responses (ActorMoveResult)

.

8. Editor Tools & Testing

Integrated Editors (F1/F5): Using the React/Zustand-powered Scene Editor and Sprite Editor, dynamic SVG component icons, and prefab exporting

. Debugging Console: Utilizing developer preprocessors like #PEEK-ON, #PEEKLLM-ON, #PEEKPN-ON, and #VALIDATE-SPATIAL . Autotests Framework: Running isolated Node.js/Vitest programmatic fixtures for parser resolution, game semantic logic, and scene boundaries .

Clone this wiki locally