Collision Detection

Relevant source files

The following files were used as context for generating this wiki page:

• app/components/Game/GameCanvas.tsx
• app/components/Game/levelData.ts
• app/components/Game/types.ts
• architecture_plan.md
• app/components/Game/GameContainer.tsx

Collision detection in the Kilo Man project is a central system responsible for managing interactions between the player character, static environment entities, and dynamic hazards. It ensures physical constraints are met, such as preventing the player from passing through platforms, and triggers game state transitions when the player contacts lethal objects or reaching the goal.

The system operates within the main game loop, specifically inside the update function of the GameCanvas component. It processes Axis-Aligned Bounding Box (AABB) checks against various entity types defined in the level data to determine movement resolution or game termination.

Sources: architecture_plan.md:37-43, app/components/Game/GameCanvas.tsx:244-245

Collision Logic and Architecture

The collision system is categorized into three primary flows: World Boundary Clamping, Static Entity Interaction, and Dynamic Monster Collision.

Execution Flow

The following diagram illustrates the sequence of checks performed during every frame of the game loop:

The update cycle prioritizes position clamping before resolving specific entity overlaps.
Sources: app/components/Game/GameCanvas.tsx:246-318

Boundary and Environmental Constraints

World Boundaries

The game world is constrained by the CONFIG.levelWidth. The system prevents the player from moving beyond the left (x < 0) and right edges. Vertical boundaries are handled as a "death pit" logic; if the player's y-coordinate exceeds 800, the game state is updated to 'lost'.

Constraint	Logic	Result
Left Edge	player.x < 0	Clamp x to 0, reset vx to 0
Right Edge	player.x > CONFIG.levelWidth	Clamp x to levelWidth, reset vx to 0
Bottom Pit	player.y > 800	Trigger setGameState('lost')

Sources: app/components/Game/GameCanvas.tsx:252-258

Platform Resolution

For entities defined as 'platform', the system calculates the overlap on both axes to determine the direction of the collision. It uses the "Minimum Translation Vector" approach by comparing overlapX and overlapY.

• Horizontal Resolution: If overlapX < overlapY, the player is pushed out to the left or right of the platform, and horizontal velocity (vx) is zeroed.
• Vertical Resolution: If overlapY < overlapX, the system checks the vertical velocity (vy). If vy > 0 (falling), the player is placed on top of the platform, isGrounded is set to true, and vy is zeroed.

Sources: app/components/Game/GameCanvas.tsx:281-299

Entity-Specific Collision Types

Collision behavior is determined by the EntityType property assigned to each object in the levelData.ts.

The EntityType dictates whether the collision results in physical resolution or a state change.
Sources: app/components/Game/types.ts:1-15, app/components/Game/levelData.ts:6-15

Hazards and Goal Detection

Hazards and goals are treated as trigger volumes. They use the same AABB intersection logic as platforms but skip physical resolution in favor of immediate game state updates:

// Hazard Detection
if (entity.type === 'hazard') {
  setGameState('lost');
  return;
}

// Goal Detection
if (entity.type === 'goal') {
  setGameState('won');
  return;
}

Sources: app/components/Game/GameCanvas.tsx:271-279

Dynamic Monster Collision

Monsters are handled in a separate loop from static level entities because they possess mutable MonsterState and are stored in a specific monstersRef.

• Logic: The system iterates through the active monsters and checks if the player's bounding box intersects with the monster's bounding box.
• Outcome: Any intersection between the player and a monster immediately triggers the 'lost' game state.
• Data Structure: Monsters include patrol parameters (patrolStart, patrolEnd) which govern their movement, but collision only relies on their current x, y, w, and h.

Sources: app/components/Game/GameCanvas.tsx:305-316, app/components/Game/types.ts:31-40

Summary

The collision detection system in Kilo Man provides a robust foundation for platforming mechanics. By combining AABB intersection checks with a prioritized resolution strategy, it handles environmental navigation, lethal hazards, and goal-oriented win conditions. This system is tightly integrated with the GameStatus state machine, ensuring that physical interactions directly drive the gameplay experience from start to completion.

Sources: architecture_plan.md:37-43, app/components/Game/GameContainer.tsx:10-50