Repository Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Kilo Man repository is structured as a modern web-based game application built using Next.js 15, React 19, and Tailwind CSS. The project follows the Next.js App Router convention, organizing logic into a root layout, a main entry page, and a dedicated component directory for game-specific logic.
The architecture separates high-level state management from low-level rendering. A central container manages the game's lifecycle and UI state, while a specialized canvas component handles the game loop, physics, and character rendering. Data is externalized into configuration and level definition files to maintain a clean separation of concerns.
Sources: architecture_plan.md:1-15, package.json:11-20, app/page.tsx:1-9
Core Application Structure
The application's entry point is defined in the app/ directory, utilizing React Server Components for the layout and client-side components for the interactive game engine.
Directory Hierarchy
app/
├── layout.tsx # Global providers, fonts, and metadata
├── page.tsx # Application entry point rendering GameContainer
├── globals.css # Tailwind CSS and global style definitions
└── components/
└── Game/
├── GameContainer.tsx # Orchestrates UI and Canvas state
├── GameCanvas.tsx # Core game loop and HTML5 Canvas rendering
├── UIOverlay.tsx # HUD, menus, and user input sliders
├── levelData.ts # Static level geometry and entity definitions
└── types.ts # TypeScript interfaces and shared types
Sources: architecture_plan.md:12-21, app/page.tsx:3-8
Component Relationship Flow
The following diagram illustrates the relationship between the main components and the flow of state through the system.
The GameContainer acts as the parent controller, synchronizing the game's status (start, playing, won, lost) between the rendering engine and the user interface.
Sources: app/components/Game/GameContainer.tsx:10-25, app/components/Game/GameCanvas.tsx:7-12
Game Engine Architecture
The game engine is encapsulated within GameCanvas.tsx, which manages a high-performance animation loop using requestAnimationFrame.
Systems and Logic
- Physics Engine: Implements gravity (0.6), friction (0.85), and collision detection against platforms and hazards.
- Camera System: A scrolling viewport that tracks the player's position, clamping to the level boundaries (up to 7000px wide).
- Entity System: Manages dynamic objects including the player humanoid and "Monster" entities with autonomous patrol logic.
- Parallax Rendering: Draws multiple background layers at varying speeds relative to the camera to create a 3D depth effect.
Sources: architecture_plan.md:25-60, app/components/Game/GameCanvas.tsx:40-60, app/components/Game/GameCanvas.tsx:320-350
Interaction Sequence
This sequence diagram shows how the game loop handles frame updates and state transitions.
Data Models and Configuration
The project uses TypeScript to define the shape of game entities and configurations, ensuring consistency across the UI and the Canvas engine.
Key Data Structures
| Type | Purpose | Key Properties |
|---|---|---|
LevelEntity | Defines objects in the world | x, y, w, h, type (platform, hazard, monster) |
PlayerState | Tracks player movement | vx, vy, facing, isGrounded |
MonsterState | Tracks AI movement | patrolStart, patrolEnd, speed |
GameConfig | Physics constants | gravity, friction, maxSpeed, levelWidth |
Sources: app/components/Game/types.ts:1-55
Physics Constants
Defined within GameCanvas.tsx, these constants control the feel of the platformer movement:
const CONFIG: GameConfig = {
gravity: 0.6,
friction: 0.85,
moveSpeed: 0.8,
maxSpeed: 8.0,
baseJumpForce: -14,
levelWidth: 7000,
};
Sources: app/components/Game/GameCanvas.tsx:40-47
Technical Specifications Summary
| Layer | Technology | Role |
|---|---|---|
| Framework | Next.js 15.0.3 | Routing and Project Structure |
| UI Library | React 19 (RC) | Component lifecycle and state management |
| Styling | Tailwind CSS 4 | Responsive HUD and overlay design |
| Rendering | HTML5 Canvas API | 2D pixel-based game rendering |
| Language | TypeScript 5 | Static typing and interface definitions |
Sources: package.json:11-25, architecture_plan.md:5-9
Conclusion
The Kilo Man repository is organized to support a scalable 2D platformer by decoupling the game's data (levels and types) from its execution (the canvas loop) and its management (the React container). This structure allows for independent updates to level design in levelData.ts without modifying the core physics logic in GameCanvas.tsx.