Scoring System
Relevant source files
The following files were used as context for generating this wiki page:
The Scoring System in Kilo Man is a time-based performance evaluation mechanism that rewards players for completing levels quickly. It calculates a final score upon successful completion of the game (reaching the 'won' state) by analyzing the elapsed time between the start of the mission and the moment the player interacts with the goal entity.
The system is integrated within the high-level game state management, ensuring that points are only awarded upon successful mission completion and are displayed to the user through the mission-complete interface.
Sources: app/components/Game/GameContainer.tsx:1-46, app/components/Game/types.ts:48-51
Scoring Logic and Calculation
The scoring mechanism follows a "time-decay" model where the player begins with a theoretical maximum and loses points as time progresses. The calculation is performed within the GameContainer component using the calculatePoints function.
Core Calculation Parameters
The system uses the following logic to determine the final score:
- Base Points: The starting value is 10,000 points.
- Time Penalty: The player loses 100 points for every second elapsed during gameplay.
- Minimum Threshold: To ensure a baseline reward, the score cannot drop below 1,000 points, regardless of how long the player takes to finish.
Sources: app/components/Game/GameContainer.tsx:15-22
Scoring Table
| Parameter | Value | Description |
|---|---|---|
basePoints | 10,000 | The starting point value for a level. |
pointsPerSecond | 100 | The rate at which points are deducted based on time. |
Minimum Score | 1,000 | The lower bound for points earned. |
Sources: app/components/Game/GameContainer.tsx:18-20
Technical Architecture and Data Flow
The scoring system relies on a reactive data flow triggered by changes in the gameState. Time tracking is handled via a useRef to maintain the start time without triggering unnecessary re-renders.
Data Structures
The scoring system utilizes a specific interface to pass results between components:
export interface CompletionData {
completionTime: number; // Time in seconds
points: number;
}
Sources: app/components/Game/types.ts:48-51
Scoring Process Flow
The following diagram illustrates how the game transitions from the active playing state to the scoring phase.
The system captures the start time using Date.now() when the gameState transitions to 'playing'. When the gameState changes to 'won', the elapsed time is calculated by subtracting the start time from the current timestamp and dividing by 1000.
Sources: app/components/Game/GameContainer.tsx:25-46, app/components/Game/GameCanvas.tsx:288-292
Component Integration
The Scoring System is distributed across three primary components:
1. GameContainer
Acts as the central controller for the scoring logic. It manages the startTimeRef and the completionData state. It contains the mathematical logic for point deduction.
Sources: app/components/Game/GameContainer.tsx:10-46
2. GameCanvas
While not calculating scores directly, the GameCanvas is responsible for detecting the collision with the 'goal' entity and updating the gameState to 'won', which triggers the calculation in the container.
Sources: app/components/Game/GameCanvas.tsx:288-292
3. UIOverlay
The UIOverlay component consumes the completionData. When the game is won, it displays the "MISSION COMPLETE" screen, including the total points earned and the final completion time formatted to two decimal places.
Sources: app/components/Game/UIOverlay.tsx:50-65
The sequence shows the hand-off from gameplay detection to state management and finally to the user interface display.
Sources: app/components/Game/GameContainer.tsx:35-46, app/components/Game/UIOverlay.tsx:50-65, architecture_plan.md:21-25
Summary
The Scoring System provides a competitive layer to Kilo Man by implementing a performance-based point system. By leveraging React's effect hooks and refs, the system accurately tracks player performance from start to finish, ensuring that speed is directly correlated with the final score shown on the post-mission summary.
Sources: app/components/Game/GameContainer.tsx:15-22, app/components/Game/UIOverlay.tsx:50-55