Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The architecture of Kilo Man is designed as a modular 2D platformer engine built with Next.js and React. It leverages the HTML5 Canvas API for high-performance rendering and a centralized state management system to coordinate gameplay, user interface, and game logic. The system is divided into high-level containers that manage game state and specialized components for rendering and HUD overlays.
Sources: architecture_plan.md:1-12, app/components/Game/GameContainer.tsx:1-10
Component Hierarchy
The application follows a strict hierarchical structure where GameContainer acts as the orchestrator. It manages the high-level GameStatus (start, playing, won, lost) and communicates this state down to the GameCanvas for the physics loop and UIOverlay for the head-up display and menus.
The diagram above illustrates the component nesting and data dependencies within the game module.
Sources: architecture_plan.md:14-23, app/components/Game/GameContainer.tsx:50-65
Core Systems
Game Loop and Physics
The GameCanvas component houses the core game loop using requestAnimationFrame. It manages mutable game state through React refs (playerRef, cameraRef, monstersRef) to avoid unnecessary re-renders while maintaining 60 FPS performance.
- Physics Engine: Implements gravity, friction, and collision detection.
- Collision Detection: Handles interactions between the player and platforms, hazards, goals, and monsters.
- Input Handling: Listens for keyboard events (Arrow Keys and Space) to update player velocity.
Sources: app/components/Game/GameCanvas.tsx:75-103, app/components/Game/GameCanvas.tsx:210-275
Camera and Viewport
The game utilizes a camera system to allow levels to be larger than the visible screen (up to 7000px wide). The camera tracks the player's position and implements clamping to stay within level boundaries.
This flow describes how the camera follows the player to determine what is rendered on screen.
Sources: architecture_plan.md:27-36, app/components/Game/GameCanvas.tsx:327-366
Entity and AI System
Entities are defined in levelData.ts and categorized by EntityType. Monsters utilize a simple AI patrol system, moving between patrolStart and patrolEnd coordinates at a defined speed.
| Entity Type | Description | Interaction Logic |
|---|---|---|
platform | Solid ground or steps | Prevents falling; provides jumping base |
hazard | Spikes or pits | Triggers 'lost' state on collision |
monster | Moving enemies | Triggers 'lost' state on collision; patrols area |
goal | Level finish point | Triggers 'won' state on collision |
start | Spawn point | Sets initial player coordinates |
Sources: app/components/Game/types.ts:1-15, app/components/Game/levelData.ts:5-10, app/components/Game/GameCanvas.tsx:280-323
Data Structures
The project uses TypeScript interfaces to enforce data consistency across the physics engine and the UI.
export interface PlayerState {
x: number;
y: number;
vx: number;
vy: number;
width: number;
height: number;
isGrounded: boolean;
facing: 1 | -1;
frame: number;
}
Sources: app/components/Game/types.ts:25-35
Technical Specifications
The game engine is tuned with specific constants to define the "feel" of movement and world constraints.
| Constant | Value | Source File |
|---|---|---|
GRAVITY | 0.6 | app/components/Game/GameCanvas.tsx:43 |
FRICTION | 0.85 | app/components/Game/GameCanvas.tsx:44 |
BASE_JUMP_FORCE | -14 | app/components/Game/GameCanvas.tsx:47 |
MAX_SPEED | 8.0 | app/components/Game/GameCanvas.tsx:46 |
LEVEL_WIDTH | 7000 | app/components/Game/GameCanvas.tsx:48 |
Rendering Pipeline
Rendering is performed in a specific order within the draw function to ensure correct layering:
- Parallax Background: Sky gradients and layers (stars, mountains, hills) moving at varying speeds relative to the camera.
- Level Entities: Static platforms (with 3D depth effects), hazards (spikes), and goals.
- Monsters: Dynamic entities with red spiky visual styles.
- Player: A procedural humanoid shape with bobbing and walking animations.
Sources: app/components/Game/GameCanvas.tsx:125-207, app/components/Game/GameCanvas.tsx:372-416
The architecture prioritizes a separation of concerns between the React-driven UI and the Canvas-driven game engine, allowing for a responsive HUD that doesn't interfere with the high-frequency physics updates of the platformer.