Skip to content

Commit 7968d67

Browse files
CopilotbedaHovorkaclaude
authored
Add user documentation for simulation speed control (#493)
* docs: add simulation speed control guide Agent-Logs-Url: https://github.com/bedaHovorka/interlockSim/sessions/06ab94aa-10ea-4267-b773-aa9b4d7157dc Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com> * docs: align speed guide with current branch Agent-Logs-Url: https://github.com/bedaHovorka/interlockSim/sessions/f8072f68-bc35-48ef-94b6-020de0a6b1dc Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com> * docs: restore stacked speed control documentation Agent-Logs-Url: https://github.com/bedaHovorka/interlockSim/sessions/943bd48f-c5aa-4ff9-9008-4338e3578772 Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com> * docs: clarify speeds above 50x Agent-Logs-Url: https://github.com/bedaHovorka/interlockSim/sessions/943bd48f-c5aa-4ff9-9008-4338e3578772 Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com> * docs: polish speed guide wording Agent-Logs-Url: https://github.com/bedaHovorka/interlockSim/sessions/943bd48f-c5aa-4ff9-9008-4338e3578772 Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com> * docs: remove internal jargon and improve Limitations/Troubleshooting - Drop "Goal 7" from the user-facing intro - Remove Goal 8 integration-point note from keyboard shortcuts - Reorder Limitations to lead with control ranges before the 100x cap - Collapse two CPU-bound sentences into one - Add actionable fix to the Space-key troubleshooting entry Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: bedaHovorka <5263405+bedaHovorka@users.noreply.github.com> Co-authored-by: Bedrich Hovorka <bedrich.hovorka@gmail.com> Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 31ddfc9 commit 7968d67

4 files changed

Lines changed: 155 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,13 +52,38 @@ This project uses Gradle with Kotlin DSL. Java 21 LTS is required.
5252
./gradlew runEditor # Launch editor GUI
5353
./gradlew runExampleGui # Animated GUI simulation (Issue #268, milestone complete 2026-02-04)
5454

55+
# Goal 7 speed-control shortcuts (simulation mode only)
56+
# 1-5 -> 0.5x, 1x, 2x, 5x, 10x
57+
# +/- -> multiply or divide speed by 1.5
58+
# Space -> pause/resume toggle (Goal 8 integration point)
59+
5560
# Other tasks
5661
./gradlew javadoc # Generate documentation
5762
./gradlew dependencies # Show dependency tree
5863
```
5964

6065
For complete build system documentation including dependency management, GitHub Packages authentication, manual JAR execution, and Gradle configuration files, see **[docs/KOTLIN_STYLE_GUIDE.md](docs/KOTLIN_STYLE_GUIDE.md)** under "Build & Development Environment".
6166

67+
### Running Simulation with Speed Control
68+
69+
Use the animated GUI when you need live speed changes:
70+
71+
```bash
72+
# Built-in animated example with speed controls
73+
./gradlew runExampleGui
74+
75+
# Equivalent manual JAR launch
76+
java -jar build/libs/interlockSim.jar exampleGui shuntingLoop 300
77+
```
78+
79+
For XML files loaded from the desktop UI, use **Simulation → Start...** and then adjust speed with:
80+
81+
- the speed slider (`0.1x` to `10.0x`)
82+
- preset buttons/menu items (`0.1x`, `0.5x`, `1x`, `2x`, `5x`, `10x`, `50x`)
83+
- global keyboard shortcuts (`1`-`5`, `+`, `-`, `Space`)
84+
85+
The status bar shows `Speed: X.Xx` whenever the speed differs from `1.0x`.
86+
6287
### Directory Structure
6388

6489
- `core/` - KMP `:core` subproject (domain model, simulation engine, XML)
@@ -170,6 +195,12 @@ For complete navigation services architecture, Koin DI integration patterns, and
170195
- AnimatedSim: Real-time animated GUI simulation (Issue #268, milestone complete 2026-02-04)
171196
- Physics-accurate rendering with velocity/acceleration visualization
172197
- Visual train movement with smooth interpolation
198+
- Goal 7 speed control is built around `SimulationRunner`, which applies wall-clock throttling without changing event semantics
199+
- `SimulationController` owns lifecycle, persists the selected speed, and reapplies it on the next simulation start
200+
- `SimulationControlPanel` provides a `0.1x`-`10.0x` slider plus preset buttons up to `50x`
201+
- `StatusBar.updateSpeedIndicator()` shows the live multiplier whenever speed is not `1.0x`
202+
- `SimulationKeyBindings` installs global shortcuts (`1`-`5`, `+`, `-`, `Space`) while the frame is in simulation mode
203+
- `Space` currently toggles `SimulationRunner.isPaused` directly as Goal 8 pause-feature groundwork
173204
- See `docs/ANIMATION_ARCHITECTURE.md` for technical details
174205

175206
**XML Configuration:**

‎docs/SIMULATION_SPEED_CONTROL.md‎

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Simulation Speed Control
2+
3+
The animated simulation GUI supports live wall-clock speed control.
4+
5+
The control changes how fast events are presented to the user. It does **not** change simulation semantics, event ordering, or physics calculations.
6+
7+
## Overview
8+
9+
Use speed control when you want to:
10+
11+
- slow the model down for teaching or demos
12+
- run near real time while watching train movement
13+
- fast-forward through long scenarios
14+
- pause temporarily while preparing for deeper Goal 8 debugging workflows
15+
16+
Supported range:
17+
18+
- **0.1x** minimum speed
19+
- **50x** highest one-click preset
20+
- **100x** absolute runner limit
21+
22+
## Quick Start
23+
24+
Start the animated GUI:
25+
26+
```bash
27+
./gradlew runExampleGui
28+
```
29+
30+
Or run the JAR directly after building:
31+
32+
```bash
33+
java -jar build/libs/interlockSim.jar exampleGui shuntingLoop 300
34+
```
35+
36+
For your own XML file, open the desktop UI and use **Simulation → Start...**.
37+
38+
When simulation mode is active, the GUI shows:
39+
40+
- the animated control panel (`Time`, `Status`, `Stop`)
41+
- the speed control panel (`Speed` slider, presets, live speed label)
42+
- the status bar speed indicator when speed is not `1.0x`
43+
44+
## GUI Controls
45+
46+
### Speed slider
47+
48+
- Range: **0.1x to 10.0x**
49+
- Step: **0.1x**
50+
- Best for fine adjustment while the simulation is already running
51+
52+
### Preset buttons
53+
54+
The panel and **Simulation → Speed** menu provide these presets:
55+
56+
- `0.1x`
57+
- `0.5x`
58+
- `1x`
59+
- `2x`
60+
- `5x`
61+
- `10x`
62+
- `50x`
63+
64+
`50x` is intentionally above the slider range. The slider stays clamped at its maximum visual position while the runner continues at `50x`.
65+
66+
### Status indicator
67+
68+
The status bar shows `Speed: X.Xx` whenever the current speed differs from `1.0x`. At the default speed the indicator is hidden to keep the bar uncluttered.
69+
70+
![Simulation speed control panel](images/simulation-speed-control-panel.png)
71+
72+
![Simulation speed status indicator](images/simulation-speed-status-indicator.png)
73+
74+
## Keyboard Shortcuts
75+
76+
Shortcuts are active in **simulation mode** while the application window has focus.
77+
78+
| Shortcut | Action |
79+
| --- | --- |
80+
| `1` | Set speed to `0.5x` |
81+
| `2` | Set speed to `1x` |
82+
| `3` | Set speed to `2x` |
83+
| `4` | Set speed to `5x` |
84+
| `5` | Set speed to `10x` |
85+
| `+` | Increase speed by `×1.5` |
86+
| `-` | Decrease speed by `÷1.5` |
87+
| `Space` | Pause or resume the active simulation |
88+
89+
Notes:
90+
91+
- On many keyboards, `+` requires **Shift+`=`**.
92+
- Numpad `+` and `-` are also supported.
93+
94+
## Common Use Cases
95+
96+
- **Educational demo:** start at `0.5x` or `1x`, then drop to `0.1x` before a switch or semaphore change.
97+
- **Normal observation:** keep the model at `1x` or `2x` and watch the event timeline.
98+
- **Long scenario review:** jump to `10x` or `50x` to move through uneventful periods quickly.
99+
- **Pre-debug pause workflow:** press `Space`, inspect the current state, then resume.
100+
101+
## Technical Details
102+
103+
- Speed control is implemented by `SimulationRunner`.
104+
- The runner wraps `SimulationContext.run()` on a dedicated simulation thread.
105+
- Wall-clock throttling uses `sleep(simDelta / speedMultiplier)`.
106+
- `SimulationController` owns lifecycle, remembers the desired speed, and reapplies it on the next run.
107+
- Swing updates stay on the EDT; simulation execution stays off the EDT.
108+
- Pause blocks the simulation thread without advancing simulation time.
109+
110+
## Limitations
111+
112+
- The slider covers **0.1x to 10x**; preset buttons and the **Simulation → Speed** menu extend this to **50x**.
113+
- To reach values above `50x`, press `+` repeatedly — the runner caps at **100x**.
114+
- Speeds above roughly **10x** are useful for throughput, but animation becomes progressively harder to follow visually.
115+
- At **50x** and above, small simulation deltas often round down to **0 ms sleep**, so execution becomes effectively CPU-bound — expect higher CPU usage and less smooth animation than at `1x`.
116+
- Console-mode runs do not expose the GUI speed controls.
117+
118+
## Troubleshooting
119+
120+
- **I cannot see the controls:** make sure you started the animated GUI, not the console example.
121+
- **The speed indicator disappeared:** that is expected at `1.0x`.
122+
- **`Space` does nothing:** a simulation must be running and the window must have keyboard focus. Click anywhere in the window to regain focus, then try again.
123+
- **The simulation feels too fast to follow:** use a preset such as `1x`, `0.5x`, or `0.1x`.
124+
- **CPU usage is high at very high speeds:** reduce speed to re-enable more wall-clock throttling.

‎docs/images/simulation-speed-control-panel.png‎

3.87 KB
Loading

‎docs/images/simulation-speed-status-indicator.png‎

2.11 KB
Loading

0 commit comments

Comments
 (0)