From 00a2b6b03e3ef9597d0c0e68906ae60d32a49e05 Mon Sep 17 00:00:00 2001 From: Arek Date: Sun, 8 Nov 2026 15:39:25 +0100 Subject: [PATCH] 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. --- .../changes/gol-simulation/.openspec.yaml | 2 + openspec/changes/gol-simulation/design.md | 43 ++++++++++ openspec/changes/gol-simulation/proposal.md | 29 +++++++ .../specs/gol-simulation/spec.md | 86 +++++++++++++++++++ openspec/changes/gol-simulation/tasks.md | 21 +++++ 5 files changed, 181 insertions(+) create mode 100644 openspec/changes/gol-simulation/.openspec.yaml create mode 100644 openspec/changes/gol-simulation/design.md create mode 100644 openspec/changes/gol-simulation/proposal.md create mode 100644 openspec/changes/gol-simulation/specs/gol-simulation/spec.md create mode 100644 openspec/changes/gol-simulation/tasks.md diff --git a/openspec/changes/gol-simulation/.openspec.yaml b/openspec/changes/gol-simulation/.openspec.yaml new file mode 100644 index 0000000..c0ad5ed --- /dev/null +++ b/openspec/changes/gol-simulation/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-11-08 diff --git a/openspec/changes/gol-simulation/design.md b/openspec/changes/gol-simulation/design.md new file mode 100644 index 0000000..45d5c36 --- /dev/null +++ b/openspec/changes/gol-simulation/design.md @@ -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. \ No newline at end of file diff --git a/openspec/changes/gol-simulation/proposal.md b/openspec/changes/gol-simulation/proposal.md new file mode 100644 index 0000000..bbffca7 --- /dev/null +++ b/openspec/changes/gol-simulation/proposal.md @@ -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. \ No newline at end of file diff --git a/openspec/changes/gol-simulation/specs/gol-simulation/spec.md b/openspec/changes/gol-simulation/specs/gol-simulation/spec.md new file mode 100644 index 0000000..57ae4ed --- /dev/null +++ b/openspec/changes/gol-simulation/specs/gol-simulation/spec.md @@ -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 \ No newline at end of file diff --git a/openspec/changes/gol-simulation/tasks.md b/openspec/changes/gol-simulation/tasks.md new file mode 100644 index 0000000..f42b3a8 --- /dev/null +++ b/openspec/changes/gol-simulation/tasks.md @@ -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. \ No newline at end of file