Contributing Guide
Relevant source files
The following files were used as context for generating this wiki page:
This guide provides technical specifications and architectural standards for contributing to Kilo Man, a 2D side-scrolling platformer. The project leverages Next.js 15, React 19, and HTML5 Canvas to create a performant gaming experience with a "3D-seeming" aesthetic.
Developers contributing to this repository should focus on maintaining the decoupled nature of the game engine logic, physics constants, and level data structures. Key areas for contribution include physics tuning, level design via the entity system, and visual rendering enhancements.
Sources: architecture_plan.md:1-10, package.json:11-20
Development Environment Setup
The project is built on the Next.js framework and requires a Node.js environment. Contributors should follow standard npm or yarn workflows for local development.
| Tool | Version/Specification | Purpose |
|---|---|---|
| Next.js | 15.0.3 | Application Framework |
| React | 19.0.0-rc | UI Library |
| TypeScript | ^5 | Type Safety |
| Tailwind CSS | ^4 | Styling |
| Node.js | ^20 (defined in @types/node) | Runtime Environment |
Sources: package.json:1-25, README.md:5-15
Local Execution
To start the development server, use one of the following commands:
npm run dev
# or
yarn dev
The application will be accessible at http://localhost:3000.
Sources: README.md:7-18
System Architecture
The application follows a modular React component structure where high-level state management is separated from the low-level rendering loop.
The diagram above illustrates the component hierarchy and data dependencies within the game module.
Sources: architecture_plan.md:13-22, app/page.tsx:1-10
Core Component Responsibilities
- GameContainer.tsx: Manages high-level state including game status (
start,playing,won,lost), scoring logic, and timers. - GameCanvas.tsx: Orchestrates the Game Loop, Physics, Camera Tracking, and Canvas Rendering.
- UIOverlay.tsx: Handles the HUD, input sliders for game modifiers, and win/loss screen overlays.
- levelData.ts: Contains the static definition of world entities, including platforms, hazards, and monsters.
Sources: architecture_plan.md:15-22, app/components/Game/GameContainer.tsx:10-30
Technical Standards for Contributions
1. Physics and Constants
Contributors adjusting movement or difficulty should modify the CONFIG object within GameCanvas.tsx or update the global types.
| Constant | Value | Description |
|---|---|---|
GRAVITY | 0.6 | Downward acceleration per frame |
FRICTION | 0.85 | Horizontal velocity decay |
MOVE_SPEED | 0.8 | Horizontal acceleration per input frame |
MAX_SPEED | 8.0 | Maximum horizontal velocity clamp |
JUMP_FORCE | -14 | Initial upward velocity for jumps |
Sources: architecture_plan.md:105-110, app/components/Game/GameCanvas.tsx:39-46
2. Entity Management
The game uses a unified LevelEntity interface for all world objects. New entities must be added to the LEVEL_1 array in levelData.ts.
export type EntityType = 'platform' | 'hazard' | 'goal' | 'start' | 'monster';
export interface LevelEntity {
id: string;
x: number;
y: number;
w: number;
h: number;
type: EntityType;
patrolStart?: number; // For monsters
patrolEnd?: number; // For monsters
speed?: number; // For monsters
}
Sources: app/components/Game/types.ts:1-15, app/components/Game/levelData.ts:1-10
3. Monster AI and Logic
Monsters follow a simple patrol behavior. When contributing new monsters, ensure they have patrolStart and patrolEnd properties defined in the level data. The GameCanvas logic automatically handles their oscillation based on these bounds.
The diagram shows the patrol logic implemented in the game loop for non-player entities.
Sources: app/components/Game/GameCanvas.tsx:220-230, architecture_plan.md:36-40
Camera and Viewport System
The game world (currently 7000px wide) is larger than the viewport. Contributors must ensure all rendering calls account for the camera offset.
- Camera Tracking: Centered on the player with X-axis clamping between
0andlevelWidth - canvasWidth. - Rendering Offset: All entities must be drawn at
entity.x - camera.xandentity.y - camera.y. - Parallax: Background layers use a multiplier (e.g.,
cameraX * 0.2for mountains) to create a sense of depth.
Sources: architecture_plan.md:27-34, app/components/Game/GameCanvas.tsx:278-315
Conclusion
Contributing to Kilo Man requires adherence to the established entity-component-system patterns and the TypeScript interfaces defined in the core types. By following this guide, developers can ensure that new features like monsters, hazards, or visual effects integrate seamlessly with the existing physics engine and camera system.
Sources: architecture_plan.md:95-103