Skip to content

Commit 94be4a7

Browse files
gcclinuxgcclinux
committed
controles dialog startup
1 parent 1b11427 commit 94be4a7

1 file changed

Lines changed: 131 additions & 0 deletions

File tree

‎specs/controls-dialog-startup.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Controls Dialog on Startup Feature
2+
3+
## Overview
4+
Automatically display the controls dialog when the game starts, allowing players to familiarize themselves with the game controls before playing.
5+
6+
## User Request
7+
Display the controls menu automatically when the game starts (like a splash screen). Players can read the controls and press ESC to close the dialog and begin playing.
8+
9+
## Implementation Summary
10+
11+
### Changes Made
12+
13+
#### 1. GameMenu.java
14+
- Added `hasShownControlsOnStartup` flag to track if controls have been shown in current session
15+
- Added `shouldShowControlsOnStartup` flag to mark that controls should be displayed
16+
- Added `startupFrameCounter` to count frames before showing the dialog
17+
- Created `showControlsOnStartup()` method to mark controls for display
18+
- Created `checkStartupControlsDisplay()` method to handle delayed display logic
19+
- Modified `update()` method to check for startup controls display
20+
21+
#### 2. MyGdxGame.java
22+
- Added call to `gameMenu.showControlsOnStartup()` in the `create()` method after player position is loaded
23+
24+
### Key Features
25+
- Controls dialog appears automatically every time the game launches
26+
- Dialog appears after a 3-frame delay to ensure proper world loading
27+
- Players can press ESC to close the dialog and start playing
28+
- Existing ESC key functionality remains unchanged (open/close menu during gameplay)
29+
30+
## Problem Encountered
31+
32+
### Initial Issue
33+
When the controls dialog was shown immediately on startup, the background world appeared different. After closing the dialog, the world would "change" to show different trees and terrain.
34+
35+
### Root Cause Analysis
36+
37+
**Initialization Sequence:**
38+
1. Game starts with camera at position (0, 0)
39+
2. `gameMenu.loadPlayerPosition()` loads saved player position (e.g., 500, 300)
40+
3. Controls dialog shows immediately (before any rendering)
41+
4. First render frame generates world around camera at (0, 0)
42+
5. When dialog closes, `player.update()` runs and camera moves to saved position (500, 300)
43+
6. World regenerates for new camera view, showing different trees/terrain
44+
45+
**Why This Happened:**
46+
- World generation in this game is **procedural and view-based**
47+
- Trees and objects are generated dynamically based on camera position during rendering
48+
- The `generateTreeAt()` method is called in the render loop for tiles in the camera view
49+
- When camera position changes, different world coordinates are rendered, generating different objects
50+
51+
### The Solution
52+
53+
Implemented a **delayed display mechanism** with a 3-frame wait:
54+
55+
```java
56+
private boolean shouldShowControlsOnStartup = false;
57+
private int startupFrameCounter = 0;
58+
59+
private void checkStartupControlsDisplay() {
60+
if (shouldShowControlsOnStartup) {
61+
startupFrameCounter++;
62+
// Wait 3 frames before showing controls to allow world to load
63+
if (startupFrameCounter >= 3) {
64+
controlsDialog.show();
65+
hasShownControlsOnStartup = true;
66+
shouldShowControlsOnStartup = false;
67+
}
68+
}
69+
}
70+
```
71+
72+
**Why 3 Frames:**
73+
1. **Frame 1**: Camera initializes, player position loads
74+
2. **Frame 2**: Player update runs, camera moves to loaded position
75+
3. **Frame 3**: World generates at correct camera position
76+
4. **Frame 4+**: Controls dialog shows with stable world rendering
77+
78+
This delay is imperceptible to players (< 50ms at 60 FPS) but ensures:
79+
- Camera is positioned at the correct loaded player position
80+
- World has generated around the correct location
81+
- Rendering is stable before the dialog appears
82+
- No visual "jump" or world change when closing the dialog
83+
84+
## Technical Details
85+
86+
### World Generation System
87+
The game uses procedural generation with these characteristics:
88+
- **View-based**: Only generates objects visible in camera view
89+
- **Deterministic**: Uses world seed for consistent generation
90+
- **Dynamic**: Generates on-the-fly during rendering loop
91+
- **Grid-aligned**: Objects spawn on 64px grid coordinates
92+
93+
### Camera and Player Relationship
94+
- Camera follows player position
95+
- Player position can be loaded from save file
96+
- Camera update happens during `player.update()` in render loop
97+
- Initial camera position (0, 0) differs from loaded player position
98+
99+
### Dialog System Integration
100+
- Controls dialog is part of the GameMenu system
101+
- Handled in the dialog priority chain (checked before main menu)
102+
- Uses existing ESC key handling from ControlsDialog class
103+
- No interference with other menu/dialog functionality
104+
105+
## Testing Recommendations
106+
107+
1. **First Launch**: Start game with no save file - controls should appear at spawn (0, 0)
108+
2. **Subsequent Launches**: Start game with existing save - controls should appear at saved position
109+
3. **World Consistency**: Verify world doesn't change when closing controls dialog
110+
4. **ESC Functionality**: Confirm ESC closes controls and normal menu still works
111+
5. **Multiplayer**: Test that controls appear correctly in both singleplayer and multiplayer modes
112+
113+
## Future Enhancements (Optional)
114+
115+
- Add a "Don't show this again" checkbox for experienced players
116+
- Save preference to player config file
117+
- Add animation/fade-in effect for smoother appearance
118+
- Display game tips or hints alongside controls
119+
- Localization support (already implemented via LocalizationManager)
120+
121+
## Files Modified
122+
123+
- `src/main/java/wagemaker/uk/ui/GameMenu.java`
124+
- `src/main/java/wagemaker/uk/gdx/MyGdxGame.java`
125+
126+
## Related Systems
127+
128+
- ControlsDialog: Displays the actual controls information
129+
- LocalizationManager: Provides translated control text
130+
- GameMenu: Manages all menu and dialog states
131+
- Player: Handles position loading and camera following

0 commit comments

Comments
 (0)