docs: add gol-simulation OpenSpec change
Plan Game of Life mechanics: Conway rules, pause/resume, stepping, speed control, and paused-only cell editing with drag painting.
This commit is contained in:
@@ -0,0 +1,2 @@
|
|||||||
|
schema: spec-driven
|
||||||
|
created: 2026-11-08
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
# Design
|
||||||
|
|
||||||
|
## Context
|
||||||
|
|
||||||
|
Input, placement, HiDPI, and grid are implemented. Simulation state (`sim_paused`, `ACTION_PAUSE`, `ACTION_STEP`, speed actions) exists but is unused. See proposal.md.
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
|
||||||
|
**Goals:**
|
||||||
|
- Conway tick loop with adjustable interval.
|
||||||
|
- Pause/resume, stepping, speed control.
|
||||||
|
- Paused-only cell editing via mouse, including drag painting.
|
||||||
|
|
||||||
|
**Non-Goals:**
|
||||||
|
- Pattern detection or statistics.
|
||||||
|
- Undo/redo.
|
||||||
|
- Multi-threading.
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
### D1: Tick timing
|
||||||
|
- Use monotonic clock in the frame loop; accumulate elapsed time; when >= interval, compute next generation and reset accumulator.
|
||||||
|
|
||||||
|
### D2: Next generation buffer
|
||||||
|
- Allocate a second grid buffer; compute into it, then swap pointers (or copy). Prefer swap of `cells` pointers with size unchanged.
|
||||||
|
|
||||||
|
### D3: Editing while paused
|
||||||
|
- Pointer button handler sets/clears cells if `sim_paused`; drag paints using motion events while button held.
|
||||||
|
|
||||||
|
### D4: Speed bounds
|
||||||
|
- Interval range 0.05s..1.0s (20 tps..1 tps), step factor 2.
|
||||||
|
|
||||||
|
### D5: Default bindings
|
||||||
|
- Add `p`, `n`, `+`/`-` to default config (merge).
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
|
||||||
|
- [Tick cost on large grids] -> grid is small (50x50), fine.
|
||||||
|
- [Editing during tick race] -> editing only while paused avoids races.
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
None.
|
||||||
@@ -0,0 +1,29 @@
|
|||||||
|
# Proposal
|
||||||
|
|
||||||
|
## Why
|
||||||
|
|
||||||
|
The application now supports input, pattern placement, and HiDPI rendering, but has no Game of Life dynamics. This change adds the actual automaton: Conway's rules, pause/resume, single stepping, speed control, and mouse editing of cells, so the tool becomes usable for exploring patterns.
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
- Add Conway's Game of Life simulation that updates the cell grid on a timer.
|
||||||
|
- Start paused by default; allow pause/resume, single-step, and speed changes.
|
||||||
|
- Allow mouse editing of cells (left click sets alive, right click sets dead) only while paused, including drag painting.
|
||||||
|
- Add default key bindings for pause (`p`), step (`n`), and speed (`+`/`-`).
|
||||||
|
- Render simulation state and reflect pause/editing in the UI (via stdout status).
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
|
||||||
|
- `gol-simulation`: Conway rules, tick timing, pause/resume, stepping, speed control, and paused-only editing.
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
- Affected code: `wlgol.c`, `grid.c/h` (read during ticks), possibly new `simulation.c/h`.
|
||||||
|
- Reuses existing input/config infrastructure; no new dependencies.
|
||||||
|
- Config defaults updated with simulation keys.
|
||||||
@@ -0,0 +1,86 @@
|
|||||||
|
# Spec Delta
|
||||||
|
|
||||||
|
## Purpose
|
||||||
|
|
||||||
|
Defines Conway's Game of Life simulation behavior, including ticking, pause/resume, stepping, speed control, and paused-only cell editing.
|
||||||
|
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: Simulation applies Conway's rules
|
||||||
|
The system SHALL advance the grid by one generation per tick using Conway's rules with wall boundaries.
|
||||||
|
|
||||||
|
#### Scenario: Tick advances grid
|
||||||
|
- **WHEN** a tick occurs
|
||||||
|
- **THEN** each cell's next state follows Conway's rules based on its eight neighbors
|
||||||
|
|
||||||
|
### Requirement: Simulation starts paused
|
||||||
|
The system SHALL start with the simulation paused.
|
||||||
|
|
||||||
|
#### Scenario: Initial state
|
||||||
|
- **WHEN** the application starts
|
||||||
|
- **THEN** the simulation is paused
|
||||||
|
|
||||||
|
### Requirement: Pause can be toggled
|
||||||
|
The system SHALL toggle between paused and running when the pause action is triggered.
|
||||||
|
|
||||||
|
#### Scenario: Toggle pause
|
||||||
|
- **WHEN** the user triggers the pause action
|
||||||
|
- **THEN** the simulation switches between paused and running
|
||||||
|
|
||||||
|
### Requirement: Single step advances one generation
|
||||||
|
The system SHALL advance exactly one generation when the step action is triggered while paused.
|
||||||
|
|
||||||
|
#### Scenario: Step while paused
|
||||||
|
- **WHEN** the simulation is paused and the user triggers step
|
||||||
|
- **THEN** the grid advances by one generation
|
||||||
|
- **AND** the simulation remains paused
|
||||||
|
|
||||||
|
### Requirement: Step is ignored while running
|
||||||
|
The system SHALL ignore the step action while the simulation is running.
|
||||||
|
|
||||||
|
#### Scenario: Step while running
|
||||||
|
- **WHEN** the simulation is running and the user triggers step
|
||||||
|
- **THEN** no extra generation is applied
|
||||||
|
|
||||||
|
### Requirement: Speed is adjustable
|
||||||
|
The system SHALL change the tick interval when speed_up or speed_down is triggered, within supported bounds.
|
||||||
|
|
||||||
|
#### Scenario: Speed up
|
||||||
|
- **WHEN** the user triggers speed_up
|
||||||
|
- **THEN** the tick interval decreases (simulation runs faster)
|
||||||
|
|
||||||
|
#### Scenario: Speed down
|
||||||
|
- **WHEN** the user triggers speed_down
|
||||||
|
- **THEN** the tick interval increases (simulation runs slower)
|
||||||
|
|
||||||
|
### Requirement: Cell editing only while paused
|
||||||
|
The system SHALL allow editing cells only while the simulation is paused.
|
||||||
|
|
||||||
|
#### Scenario: Edit while paused
|
||||||
|
- **WHEN** the simulation is paused and the user clicks a cell
|
||||||
|
- **THEN** the cell state changes according to the mouse button
|
||||||
|
|
||||||
|
#### Scenario: No edit while running
|
||||||
|
- **WHEN** the simulation is running and the user clicks a cell
|
||||||
|
- **THEN** the grid is not modified by the click
|
||||||
|
|
||||||
|
### Requirement: Left click sets cell alive
|
||||||
|
The system SHALL set the clicked cell to alive when the left mouse button is pressed while paused.
|
||||||
|
|
||||||
|
#### Scenario: Set alive
|
||||||
|
- **WHEN** the simulation is paused and the user left-clicks a cell
|
||||||
|
- **THEN** that cell becomes alive
|
||||||
|
|
||||||
|
### Requirement: Right click sets cell dead
|
||||||
|
The system SHALL set the clicked cell to dead when the right mouse button is pressed while paused.
|
||||||
|
|
||||||
|
#### Scenario: Set dead
|
||||||
|
- **WHEN** the simulation is paused and the user right-clicks a cell
|
||||||
|
- **THEN** that cell becomes dead
|
||||||
|
|
||||||
|
### Requirement: Drag paints cells
|
||||||
|
The system SHALL paint cells while dragging with the left button (alive) or right button (dead) while paused.
|
||||||
|
|
||||||
|
#### Scenario: Drag paint
|
||||||
|
- **WHEN** the simulation is paused and the user drags with left button held
|
||||||
|
- **THEN** cells under the cursor become alive
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
# Tasks
|
||||||
|
|
||||||
|
## 1. Simulation core
|
||||||
|
|
||||||
|
- [ ] 1.1 Implement Conway tick using a second grid buffer and swap, verifying a known pattern (blinker) oscillates.
|
||||||
|
- [ ] 1.2 Add tick timing in the frame loop with adjustable interval, verifying ticks occur at configured rate.
|
||||||
|
|
||||||
|
## 2. Controls
|
||||||
|
|
||||||
|
- [ ] 2.1 Wire pause/step/speed actions to simulation state, verifying pause stops ticks and step advances one generation.
|
||||||
|
- [ ] 2.2 Add default key bindings for p/n/+/- and verify config tests pass.
|
||||||
|
|
||||||
|
## 3. Editing
|
||||||
|
|
||||||
|
- [ ] 3.1 Implement paused-only cell editing on left/right click, verifying clicks change cell state only when paused.
|
||||||
|
- [ ] 3.2 Implement drag painting while paused, verifying drag sets/clears cells.
|
||||||
|
|
||||||
|
## 4. Verification
|
||||||
|
|
||||||
|
- [ ] 4.1 Build and run ctest, verifying all tests pass.
|
||||||
|
- [ ] 4.2 Manual run: verify pause, step, speed, editing, and Esc.
|
||||||
Reference in New Issue
Block a user