From afa54b09553899502e254cdf3eded581b289b390 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 21 Jul 2026 02:06:55 +0000 Subject: [PATCH] Refresh docs: reflect the shipped visual redesign, tidy roadmap framing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README's status callout and Deferred docs section referenced the UI/UX pass as in-progress; it has since landed (Graphite · Lime). Updated both to match, generalized a couple of comparison references in the roadmap, and reworded a properties-panel tooltip for the modifier delta mode. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01BwFLZbJjLWkZ1hn6ULY4MP --- CLAUDE.md | 6 +++--- README.md | 28 +++++++++++++--------------- ROADMAP.md | 15 +++++++-------- js/app-props.js | 2 +- 4 files changed, 24 insertions(+), 27 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 50f7576..a032f65 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,9 +2,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -A browser-based, Machinations-style designer for resource economies and game-system -feedback loops, with a discrete-time simulation engine. **Pure vanilla JS, no build -step, no framework** — static files served as-is. The only runtime dependency is the +A browser-based designer for resource economies and game-system feedback loops, +with a discrete-time simulation engine. **Pure vanilla JS, no build step, no +framework** — static files served as-is. The only runtime dependency is the vendored math.js bundle (`vendor/math.min.js`) powering the formula language. See `README.md` for the full feature list and `docs/CONCEPTS.md` for the simulation diff --git a/README.md b/README.md index eb54ac0..756aa1c 100644 --- a/README.md +++ b/README.md @@ -2,23 +2,22 @@ [![tests](https://github.com/zntznt/simulations/actions/workflows/tests.yml/badge.svg)](https://github.com/zntznt/simulations/actions/workflows/tests.yml) -A browser-based, [Machinations](https://machinations.io/)-style tool for modelling -resource economies and game-system feedback loops, then **simulating** them step by -step. Draw nodes and connections on a canvas, press Run, and watch resources flow, -accumulate, convert, and drain — with charts, batch (Monte Carlo) analysis, and -shareable diagrams. +A browser-based tool for modelling resource economies and game-system feedback +loops, then **simulating** them step by step. Draw nodes and connections on a +canvas, press Run, and watch resources flow, accumulate, convert, and drain — +with charts, batch (Monte Carlo) analysis, and shareable diagrams. Pure vanilla JavaScript. **No build step, no framework** — just static files and an SVG canvas. The only runtime code dependency is a vendored copy of [math.js](https://mathjs.org/) powering the formula language; Font Awesome icons are vendored too. -> **Status — docs in progress.** A major UI/UX overhaul is underway. This README -> documents the parts that are stable regardless of how the interface looks: the -> simulation model, the feature set, the architecture, and how to run and test the -> project. A visual walkthrough, screenshots, and a step-by-step editor tutorial -> will land **after** the UI/UX pass so they don't go stale. See -> [Deferred docs](#deferred-docs). +> **Status — docs in progress.** The editor's visual redesign (the **Graphite · +> Lime** design system) has landed. This README documents the parts that are +> stable regardless of how the interface looks: the simulation model, the +> feature set, the architecture, and how to run and test the project. A visual +> walkthrough, screenshots, and a step-by-step editor tutorial are still on the +> way. See [Deferred docs](#deferred-docs). --- @@ -254,7 +253,7 @@ explanatory note and an on-canvas chart. Open the **Library** to load one. - **Barter Economy** — two towns swap grain for timber through a Trader (an atomic 2-for-2 exchange); each storehouse ends up holding both colours. - **Service Desk** — a single-server queue with random (Poisson) arrivals; the line builds and clears — the M/D/1 queue behind every checkout. -### Sprawling demos — full systems at machinations.io scale +### Sprawling demos — full systems at production scale Each is a large (~30–37 node), multi-subsystem model that exercises nearly every engine feature at once, designed by a panel of domain experts and tuned to @@ -351,15 +350,14 @@ also records intentional design decisions and known limitations. ## Deferred docs -Held until after the in‑progress UI/UX overhaul, so they don't immediately go stale: +Still to come, now that the visual redesign has landed: - **Screenshots / GIFs** of the editor and analysis views. - **A visual, step‑by‑step usage guide** (placing nodes, wiring connections, reading the panels). - Any **layout‑specific** reference (exact panel locations, button labels). The simulation model, file architecture, and APIs documented here and in -`docs/CONCEPTS.md` are independent of the visual design and should remain accurate -across the redesign. +`docs/CONCEPTS.md` are independent of the visual design and remain accurate. --- diff --git a/ROADMAP.md b/ROADMAP.md index 6114e7a..874e60b 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,9 +1,8 @@ # Simulations — Roadmap & Feature Tracker -A living list of what the engine/editor can do today and what's still missing -relative to [machinations.io](https://machinations.io/). Check items off as they -land. Priorities: **P1** = core parity / high value, **P2** = valuable, -**P3** = nice-to-have. +A living list of what the engine/editor can do today and what's still missing. +Check items off as they land. Priorities: **P1** = core / high value, +**P2** = valuable, **P3** = nice-to-have. --- @@ -23,7 +22,7 @@ core loop or vendoring). Full detail for each lives in its section further down. | 5 | **Web-worker engine** — move the tick loop off-thread | S | Med | Engine is already DOM-free; perf win, not adoption | | 6 | **Reusable subgraph components** (parameterized insert) | S | Med | Small extension of the existing component insert; power-user | | 7 | **Animated GIF export** | M | Med | Reach/shareability; needs a vendored encoder (gif.js) — acceptable per pragmatic dep policy | -| — | **Machinations.io importer** | M | Niche | Parked: effort dominated by reverse-engineering their format; narrow audience | +| — | **External diagram importer** | M | Niche | Parked: effort dominated by reverse-engineering other tools' formats; narrow audience | **Suggested first sprint: items 1–3** — all serve new-user adoption; 1 and 2 are small, 3 is the one larger investment worth making for that audience. @@ -228,7 +227,7 @@ small, 3 is the one larger investment worth making for that audience. ## ✅ Sprawling example library - [x] **Six large, expert-designed demos** added alongside the five concept - demos, to show the engine at machinations.io scale. Each is ~30-37 nodes, + demos, to show the engine at production scale. Each is ~30-37 nodes, spans multiple interacting subsystems, exercises most of the engine at once, and is tuned for rich non-degenerate dynamics (verified headlessly through the real `_demo*` methods — no NaN/Inf, no dead/pegged values): @@ -321,8 +320,8 @@ shipped (above); the rest are unstarted. The actionable ones are ranked in the flow with the user; example gallery with live previews. - **Plugin hooks.** `onNodeFire` / `onTransfer` / `onStepEnd` registration so domain experts can add custom node behaviours without forking the engine. -- **Machinations.io importer.** Parse their file format into diagram JSON for - migration. +- **External diagram importer.** Parse other tools' file formats into diagram + JSON for migration. - **Animated GIF / embeddable live widget export** for sharing running models. --- diff --git a/js/app-props.js b/js/app-props.js index 8e21b3e..e4a9370 100644 --- a/js/app-props.js +++ b/js/app-props.js @@ -2112,7 +2112,7 @@ class AppProps { this._info(panel, { step: 'Each step, add this amount to the target pool/converter (negative subtracts). Use a formula to compute it from variables, e.g. round(gold * 0.05).', pulse: 'Each time the source node fires, add this amount to the target pool/converter (negative subtracts). The easy "+1 when the source triggers".', - delta: 'When the source value changes, add factor × the change to the target (Machinations-style label modifier).', + delta: 'When the source value changes, add factor × the change to the target (a label modifier driven by the change, not the value).', rate: 'Each step, add factor × source value to the target (negative = decay). Self-connections are allowed for interest/decay.', }[mode]);