How vixan/ghost-in-the-graveyard works
Project type and purpose
• This is a single‐page, front‐end React/TypeScript simulation application.
• Purpose: visually simulate the “Ghost in the Graveyard” multi‐agent game using an HTML5 canvas (via Konva), with agents (Players, Ghosts, Exit, Tombstones) moving on a grid according to simple BDI‐inspired rules.
File structure
• Top level: package.json/lock, tsconfig.json, README, public/ (static HTML, manifest, robots.txt)
• src/
• App.tsx & index.tsx – application entry and root container
• components/
– ui/ (Button, NumberInput, RangeInput, Switch)
– Environment.tsx, Grid.tsx – canvas staging and layout
– agents/ (Agent base class, and specific Agent subcomponents: Ghost, Player, Exit, Tombstone)
• utils/ – pure helpers (gridUtils, positionUtils), custom hooks (useLatestState, useWindowSize)
• types/ – TS types (position, simulationStatus)
• reportWebVitals, react-app-env.d.ts – CRA boilerplate
README for additional insights
• Dependencies: React, TypeScript, react-konva/konva for canvas rendering, styled-components for styling, pathfinding for shortest‐path calculations.
• No backend or external services—pure client‐side logic.
Main components & their interactions
a. Presentation Layer (UI controls)
• Button, Inputs, Switch emit user events (start/stop, change grid size, speed).
• → Events dispatched to App’s state handler.
b. Simulation Engine
• Maintains current agent positions & statuses in React state.
• Uses gridUtils + positionUtils + pathfinding library to compute next moves.
• Custom hook (useLatestState) ensures engine always works on up‐to‐date state.
c. Rendering Layer
• Environment.tsx wraps a Konva Stage/Layer.
• Grid.tsx draws cell boundaries.
d. State Management
• Centralized in App.tsx via React hooks (useState, useEffect).
• Prop drilling or context passes state and updater functions to child components.
e. External libraries
• react-konva for canvas integration
• styled-components for styling UI controls
• pathfinding for graph search
Architectural patterns & design principles
• Component-based (separation of concerns between UI, simulation logic, rendering).
• Unidirectional data‐flow (Flux-like): UI → App state → Simulation engine → state updates → view re‐render.
• Custom hooks encapsulate cross‐cutting concerns (window resizing, latest state refs).
• Pure utility modules (gridUtils, positionUtils) isolated from React, making them testable.
Final advice
• Simulation loop explicitly, as that is the heart of the architecture.
• Use visual conventions consistently so that any new engineer can immediately see how state flows from user input through the engine to the canvas.