Architecture Plan Analysis
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Architecture Plan for Kilo Man (v2.0) outlines a technical roadmap for a 2D side-scrolling platformer built using Next.js 16, React 19, and HTML5 Canvas. The project aims for a "3D-seeming" aesthetic through advanced rendering techniques like parallax backgrounds and procedural geometry, moving away from external assets to maintain high performance and technical control.
Sources: architecture_plan.md:1-10, package.json:11-16
The system is structured around a centralized game loop that manages physics, entity logic, and camera tracking. Data is driven by a structured level configuration, allowing for complex world layouts including platforms, hazards, and patrolling monsters.
Sources: architecture_plan.md:12-21, app/components/Game/GameCanvas.tsx:189-210
Component Hierarchy and State Management
The application follows a modular React component structure where state flows from high-level management to specialized rendering and UI components.
Component Structure
| Component | Responsibility |
|---|---|
GameContainer | Manages high-level game state (Start/Playing/Won/Lost), jump modifiers, and scoring logic. |
GameCanvas | Core engine handling the Game Loop, Physics, Camera tracking, and Entity rendering. |
UIOverlay | Renders the HUD, jump power sliders, control hints, and game-over/victory screens. |
levelData.ts | Defines the static world layout, entity positions, and monster patrol parameters. |
Sources: architecture_plan.md:14-21, app/components/Game/GameContainer.tsx:10-25, app/components/Game/UIOverlay.tsx:15-30
Application Flow
The following diagram illustrates the data flow and communication between the primary components during active gameplay:
The GameContainer acts as the orchestrator, passing configuration down while receiving status updates from the physics engine within the canvas.
Sources: app/components/Game/GameContainer.tsx:47-65, app/components/Game/GameCanvas.tsx:10-15
Core Systems Analysis
Physics and Movement
The engine utilizes a tuned set of constants to simulate weight and momentum. Movement involves horizontal acceleration with friction and a gravity-based vertical system.
| Constant | Value | Description |
|---|---|---|
GRAVITY | 0.6 | Constant downward acceleration. |
FRICTION | 0.85 | Velocity decay applied to horizontal movement. |
MOVE_SPEED | 0.8 | Horizontal acceleration per frame. |
MAX_SPEED | 8.0 | Velocity cap to prevent tunneling. |
JUMP_FORCE | -14 | Initial upward impulse, modified by UI settings. |
Sources: architecture_plan.md:104-109, app/components/Game/GameCanvas.tsx:36-43
Camera and Viewport
To support expansive levels (e.g., levelWidth: 7000), the system implements a dynamic camera. The camera follows the player's x position while clamping to level boundaries. Vertical tracking includes a "deadzone" to avoid jitter during small jumps, only following if the player climbs high or falls deep into hazards.
Sources: architecture_plan.md:27-35, app/components/Game/GameCanvas.tsx:291-325
Entity and AI System
Entities are categorized into types that dictate interaction logic within the collision detection loop.
- Monsters: Implement a patrol behavior defined by
patrolStartandpatrolEndcoordinates. - Hazards: Trigger an immediate "lost" state upon collision (e.g., spikes).
- Goal: Triggers the "won" state and calculates final score based on completion time.
Visual Architecture ("3D-Seeming")
The architectural plan emphasizes procedural visuals to create depth without external sprite assets.
Rendering Layers
- Sky Gradient: A linear gradient from
#0f172ato#3b0764. - Parallax Backgrounds:
- Stars move at
cameraX * 0.1. - Far Mountains move at
cameraX * 0.2. - Near Hills move at
cameraX * 0.5.
- Stars move at
- Procedural Characters: The player is rendered as a humanoid using primitives (rectangles for limbs, arcs for the head) with oscillation logic for "bobbing" during movement.
- 3D Platforms: Platforms are drawn with a light "top face" (
#fbbf24) and a darker "front face" gradient to simulate thickness.
Sources: architecture_plan.md:43-56, app/components/Game/GameCanvas.tsx:112-187
Data Structures
The system relies on strongly typed interfaces to ensure consistency between level definitions and runtime state.
export interface LevelEntity {
id: string;
x: number;
y: number;
w: number;
h: number;
type: EntityType; // platform, hazard, goal, monster, etc.
patrolStart?: number;
patrolEnd?: number;
speed?: number;
}
Sources: app/components/Game/types.ts:3-15, app/components/Game/levelData.ts:6-15
Conclusion
The Kilo Man Architecture Plan Analysis reveals a robust, modular system designed for scalability and visual depth. By decoupling level data from the core engine and utilizing a multi-layered parallax rendering system, the architecture achieves a complex aesthetic through purely mathematical Canvas operations. The integration of React for UI and high-level state management provides a modern framework for the imperative game loop.
Sources: architecture_plan.md:91-102, app/components/Game/GameContainer.tsx:35-45