TypeScript Interfaces
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Kilo Man project utilizes a centralized TypeScript type system to ensure type safety across its game engine, UI components, and level design modules. These interfaces define the shape of game entities, internal state management for physics and animation, and the configuration parameters that govern the game's mechanics.
The core type definitions are primarily located in app/components/Game/types.ts, serving as the single source of truth for the GameCanvas, GameContainer, and UIOverlay components. This structured approach allows for predictable data flow between the React-based UI and the imperative HTML5 Canvas rendering loop.
Sources: app/components/Game/types.ts:1-51, architecture_plan.md:65-80
Core Data Structures
Game State and Lifecycle
The system tracks the progression of the game through a union type that represents all possible high-level states. This state is managed in the GameContainer and passed down to both the rendering engine and the UI.
The game lifecycle transitions between these states based on player collision with goals, hazards, or monsters.
Sources: app/components/Game/types.ts:40, app/components/Game/GameContainer.tsx:10-15
Entity Definitions
The game world is composed of various LevelEntity objects. Each entity is defined by its spatial coordinates, dimensions, and a specific EntityType which dictates its behavior and rendering style.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the entity instance. |
x, y | number | The horizontal and vertical position in the world. |
w, h | number | Width and height dimensions. |
type | EntityType | Can be 'platform', 'hazard', 'goal', 'start', or 'monster'. |
patrolStart | number? | (Optional) Starting X-coordinate for monster patrol. |
patrolEnd | number? | (Optional) Ending X-coordinate for monster patrol. |
speed | number? | (Optional) Movement speed for monsters. |
Sources: app/components/Game/types.ts:1-16, app/components/Game/levelData.ts:6-10
Physics and Actor States
Player Dynamics
The PlayerState interface maintains the mutable properties of the player character, including velocity vectors for physics calculations and orientation for rendering humanoid animations.
The facing property (1 for right, -1 for left) is used by the drawHumanoid function in GameCanvas.tsx to determine eye placement and animation offsets.
Sources: app/components/Game/types.ts:18-28, app/components/Game/GameCanvas.tsx:210-213
Monster Logic
While monsters originate from LevelEntity definitions in the level data, they are instantiated as MonsterState objects within the game loop to track their independent horizontal velocity (vx) during patrols.
| Field | Description | Source |
|---|---|---|
vx | Current horizontal velocity of the monster. | app/components/Game/types.ts:34 |
patrolStart | Left boundary of movement. | app/components/Game/types.ts:35 |
patrolEnd | Right boundary of movement. | app/components/Game/types.ts:36 |
Sources: app/components/Game/types.ts:30-38, app/components/Game/GameCanvas.tsx:313-323
Engine Configuration
Physics Constants
Global game behavior is controlled via the GameConfig interface. This allows for unified tuning of gravity, friction, and movement speeds.
The baseJumpForce is specifically modified by a jumpModifier provided by the UIOverlay slider, demonstrating how external UI state interacts with typed physics constants.
Sources: app/components/Game/types.ts:47-54, app/components/Game/GameCanvas.tsx:44-51, app/components/Game/UIOverlay.tsx:33-45
Completion Metrics
When a player reaches the 'goal' entity, the system calculates performance metrics defined by the CompletionData interface.
export interface CompletionData {
completionTime: number; // Time in seconds
points: number;
}
Points are calculated in GameContainer.tsx using a base value of 10,000, subtracting 100 points per second of completionTime.
Sources: app/components/Game/types.ts:42-45, app/components/Game/GameContainer.tsx:18-25
Component Interop
The following sequence diagram illustrates how these interfaces facilitate communication between the main game components.
Summary
The TypeScript interfaces in the Kilo Man project provide a robust framework for managing 2D platformer mechanics. By separating static level definitions (LevelEntity) from dynamic actor states (PlayerState, MonsterState) and global configurations (GameConfig), the architecture ensures that the rendering engine remains decoupled from the game logic while maintaining strict type safety across the Next.js application.