UIOverlay Component
Relevant source files
The following files were used as context for generating this wiki page:
The UIOverlay component serves as the primary Heads-Up Display (HUD) and user interface layer for the Kilo Man platformer. It is a functional React component that sits on top of the GameCanvas, providing essential game state feedback, control configurations, and session results to the player. Its scope includes managing the start screen, the active gameplay HUD (including jump power adjustment), and the end-of-game victory or defeat screens.
As a part of the GameContainer hierarchy, UIOverlay remains synchronized with the core game loop via props, ensuring that visual feedback such as points and completion time are accurately displayed when the game status transitions. Sources: architecture_plan.md:21-27, app/components/Game/GameContainer.tsx:49-62
Component Architecture and State Management
The UIOverlay is designed as a stateless presentation component that relies on props passed down from its parent, GameContainer. It uses Tailwind CSS for styling and positioning, ensuring it covers the entire game viewport while allowing underlying canvas interactions through the use of pointer-events-none on the container and pointer-events-auto on specific interactive UI elements.
Data Flow and Props
The component receives several critical pieces of data to determine its rendering state:
- gameState: A
GameStatusstring ('start', 'playing', 'won', 'lost') that dictates which overlay layer is visible. - jumpModifier: A numerical value representing the current jump power scaling.
- completionData: An object containing the final time and points calculated upon winning.
- Event Handlers: Functions for restarting the mission (
onRestart) and updating game settings (setJumpModifier).
Sources: app/components/Game/UIOverlay.tsx:4-15, app/components/Game/types.ts:47-51
The following diagram illustrates the flow of state from the GameContainer into the UIOverlay and the resulting UI transitions:
The state transitions are managed by the parent container, while UIOverlay handles the visual representation of those transitions. Sources: app/components/Game/GameContainer.tsx:39-64
Functional Sections
Gameplay HUD (Active State)
When the gameState is 'playing', the top bar of the overlay is active. It displays the game title "KILO MAN" and provides a functional slider to adjust the player's jump power dynamically. This slider maps to the jumpModifier prop, which influences the baseJumpForce in the physics engine.
| Feature | Description | File Reference |
|---|---|---|
| Jump Power Slider | Range: 0.5 to 2.0, step: 0.1. Adjusts vertical velocity. | UIOverlay.tsx:32-42 |
| Control Legend | Static display of keyboard shortcuts (ARROWS: Move, SPACE: Jump). | UIOverlay.tsx:47-50 |
| Dynamic Labels | Displays current jump power percentage (e.g., 100%). | UIOverlay.tsx:30 |
Mission Completion and Game Over
Upon game termination, the UIOverlay renders a centered modal.
- Victory Screen: Displays "MISSION COMPLETE" in yellow, showing the total points earned and the completion time. The points are calculated in
GameContainerby subtracting time-based penalties from a base score of 10,000. - Game Over Screen: Displays "GAME OVER" in red with a flavor text indicating mission compromise.
Sources: app/components/Game/UIOverlay.tsx:55-87, app/components/Game/GameContainer.tsx:14-23
Screen Structure and Technical Implementation
The overlay utilizes absolute positioning to overlay the GameCanvas.
// Example of the point display logic within the Won state
{gameState === 'won' && completionData && (
<div className="mb-6 space-y-3">
<div className="bg-yellow-500/20 border border-yellow-500 p-4 rounded">
<div className="text-yellow-400 text-5xl font-bold mb-2">
{completionData.points.toLocaleString()}
</div>
<div className="text-yellow-300 text-sm font-mono">POINTS EARNED</div>
</div>
</div>
)}
Sources: app/components/Game/UIOverlay.tsx:64-73
The interface styling is defined primarily through utility classes, but global layout constraints such as overflow: hidden on the body ensure the UI stays contained within the viewport. Sources: app/globals.css:26-31
Interaction Sequence
The following sequence diagram represents the interaction between the user, the UIOverlay, and the GameContainer during a typical game session:
Summary
The UIOverlay component is a critical bridge between the HTML5 Canvas game engine and the React-based user interface. By isolating UI logic into this component, the project maintains a clean separation of concerns, where GameCanvas focuses on high-performance rendering and physics, while UIOverlay handles complex CSS layouts, user input settings, and game state messaging. Sources: architecture_plan.md:21-27, app/components/Game/GameContainer.tsx:49-65