GameContainer Component
Relevant source files
The following files were used as context for generating this wiki page:
The GameContainer component serves as the high-level orchestrator for the "Kilo Man" game environment. It is responsible for managing the global game state, handling synchronization between the rendering engine and the user interface, and calculating performance metrics such as completion time and scoring. As a "Client Component" in the Next.js architecture, it encapsulates both the physical game world and the interactive HUD.
Sources: app/components/Game/GameContainer.tsx:1-7, architecture_plan.md:13-19
Component Architecture
GameContainer acts as the parent wrapper that maintains the "source of truth" for the game's lifecycle. It passes state and control functions down to two primary children: GameCanvas (which handles the physics loop and rendering) and UIOverlay (which handles menus, HUD, and input configuration).
Hierarchy and Data Flow
The architecture follows a unidirectional data flow pattern where the container manages state and passes it via props.
The diagram above illustrates the structural relationship and the primary callback paths between the container and its sub-components.
Sources: app/components/Game/GameContainer.tsx:49-62, architecture_plan.md:16-19
State Management
The component manages four primary pieces of state that dictate the behavior of the entire game system:
| State Variable | Type | Description |
|---|---|---|
gameState | GameStatus | Tracks the current lifecycle phase: start, playing, won, or lost. |
jumpModifier | number | A multiplier (default 1.0) adjusted by the user to influence player jump force. |
completionData | CompletionData | null | Stores the final time and calculated points upon a successful mission. |
startTimeRef | useRef<number> | A mutable reference capturing the timestamp when the 'playing' state begins. |
Sources: app/components/Game/GameContainer.tsx:10-14, app/components/Game/types.ts:47-55
Game Lifecycle Transitions
The game transitions through various states based on player performance and user interaction.
The logic for transitioning into the playing state is centralized in the handleRestart function, which resets the state and triggers the initialization logic within the GameCanvas.
Sources: app/components/Game/GameContainer.tsx:45-47, app/components/Game/GameCanvas.tsx:84-118
Game Scoring and Metrics
GameContainer contains the logic for evaluating player performance. When a level is completed, it calculates a score based on the elapsed time stored in the startTimeRef.
Point Calculation Formula
The scoring system rewards speed, starting with a base potential and decaying as time passes.
- Base Points: 10,000
- Penalty: 100 points per second elapsed.
- Minimum Floor: 1,000 points.
const calculatePoints = (timeInSeconds: number): number => {
const basePoints = 10000;
const pointsPerSecond = 100;
const points = Math.max(1000, basePoints - Math.floor(timeInSeconds * pointsPerSecond));
return points;
};
Sources: app/components/Game/GameContainer.tsx:16-23
Mission Completion Logic
A useEffect hook monitors the gameState. When the state changes to won, it calculates the final duration and calls the scoring function to populate completionData.
Component Interfaces
GameContainer interacts with defined TypeScript interfaces to ensure type safety across the game module.
CompletionData Interface
Used to pass final statistics to the UIOverlay.
completionTime:number(Time in seconds)points:number(Final score)
GameStatus Type
'start': Initial landing screen.'playing': Active game loop and physics.'won': Mission success screen.'lost': Game over screen.
Sources: app/components/Game/types.ts:47-55
Implementation Details
The GameContainer ensures that the UIOverlay remains functional even when the game is paused or in a menu state by utilizing relative/absolute positioning. The GameCanvas receives the jumpModifier directly from the container's state, allowing real-time physics adjustments while the game is running.
Sources: app/components/Game/GameContainer.tsx:50-62, app/components/Game/GameCanvas.tsx:168-171
The GameContainer component effectively separates high-level game management from low-level rendering and physics. By centralizing the state and scoring logic, it provides a stable foundation for the "Kilo Man" mission-based gameplay.