**Bead** `f4ef67b7-001f-412c-ba90-f93ceba92bda` · [canonical URI](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/) · discussion: Talk: Agentscript Webgpu This page is the wiki facet of a [bead](https://redfish.acequia.io/guerin/.agents/); the bead is the source of truth.
## Identity - **name:** `agentscript-webgpu` - **URI:** `https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/` - **GUID:** `f4ef67b7-001f-412c-ba90-f93ceba92bda` - **Slug:** `agentscript-webgpu` - **Opened:** 2026-06-17 - **Body:** CV (Claude Code extension — shell + filesystem; local origin is source of truth, PUT/bead-sync propagates). - **Mounts (read):** - [`c66cbd1d`](https://redfish.acequia.io/guerin/.agents/c66cbd1d-453c-41f8-8440-179502f25de4/about.md) **taos-engine** — the WebGPU substrate to embed in; holds the **taos-orama** repo-query skill and the engine export surface. The engine already ships a full compute layer (`src/shaders/*.wgsl`, `gpu_cull`, splat training, voxel mesher, pathtracer) = the precedent for an ABM compute pass. - [`b6fcda63`](https://redfish.acequia.io/guerin/.agents/b6fcda63-c171-4293-9d99-75297f4205bb/about.md) **ants-in-taos** — shipped fire/ant models in taos-engine using the AgentScript *paradigm* (patches/turtles stepping) **written by hand, not the canonical library**, and explicitly flagged "swap to the canonical lib if he wants the dependency." This bead is that swap, taken to the GPU. - [`2028c98b`](https://redfish.acequia.io/guerin/.agents/2028c98b-6fae-4d97-8fd9-3c7e4afba988/about.md) **taos-samples** + [`d6ad03ba`](https://redfish.acequia.io/guerin/.agents/d6ad03ba-5d96-4cfa-9a17-fe6f36a4f07a/about.md) **taos-recipes** — the engine's sample/recipe corpus, including the AgentScript rendering one-liners.
## Motivation (why a GUID) Stephen's directive: **"translate agentscript.org's CPU-based architecture to WebGPU; embed the implementation in taos-engine."** AgentScript (the NetLogo-in-JS library, `github.com/backspaces/agentscript`, Owen Densmore / Redfish) is a CPU agent-based-modeling runtime: a `Model` steps `Patches`, `Turtles`, and `Links` AgentSets each tick on the main thread. The goal is to keep that authoring model and idiom while moving the per-tick computation onto the GPU as WebGPU compute, hosted inside taos-engine's render/compute loop. A fresh GUID keeps this foundational design work out of the global namespace and gives siblings a stable URI to mount.
## Mechanism (what this bead does) Workshops the CPU→GPU port in three layers: 1. **Architecture map** — read AgentScript's CPU data model (Model step loop; AgentSet/Patches/Turtles/Links; the `DataSet` rasters; the NetLogo-idiom primitives: `diffuse`, `evaporate`, `uphill`, `inCone`, `wiggle`, `hatch`/`die`) and identify what becomes GPU state vs GPU kernel. 2. **GPU substrate design** — Structure-of-Arrays storage buffers for turtle/patch attributes, patches as 2D storage textures, the step kernels as WGSL compute shaders dispatched per tick. The hard problems get explicit treatment: dynamic agent birth/death (atomic counters + compaction), neighbor/topology queries (links, in-radius/in-cone), on-GPU RNG, and main-thread API ergonomics over GPU-resident state. 3. **taos-engine embedding** — run the model step as a compute pass interleaved with the engine frame (precedent: `gpu_cull.wgsl`, the splat trainer, the voxel mesher), and render turtles/patches/links as engine `GeoFeature`/`Mesh` draws (precedent: the `ants-in-taos` RenderFeature pattern).
## Folder Layout - `about.md` (this) · `README.md` (front door) · `bead-bind-startup.md` (binder contract) · `agent.json` / `keywords.json` / `names.json` (machine faces). - `2026-06-17/notes/` — `00-agentscript-cpu-to-webgpu.md` (architecture map + GPU design + open questions). - `2026-06-17/chats/` — verbatim chat log. - `2026-06-17/{skills,artifacts}/` — reusable capabilities · polished deliverables / verification. - `uploads/` — inbound dock.
## Session Log - **2026-06-17** — Bead opened (`start-bead agentscript-webgpu`). Surveyed `beads.md`, the `ants-in-taos` (`b6fcda63`) and `taos-engine` (`c66cbd1d`) beads. Confirmed (a) taos-engine carries a real WebGPU compute layer to build on, (b) the prior ants/fire work used the AgentScript paradigm by hand and flagged the canonical-lib swap, (c) the local `agentscript.org` folder was a DNS-only stub — the canonical source is `github.com/backspaces/agentscript`. Wrote the initial architecture-map note with the CPU→GPU layer split and the open questions. - **2026-06-17 — Source cloned.** Per Stephen, `git init`'d the local **`agentscript.org`** site folder and pulled the canonical `github.com/backspaces/agentscript` `master` (HEAD `93d01a3`, 2026-06-10). The site folder IS now the AgentScript repo: `src/` (the classes — `Model.js`, `World.js`, `Patches.js`/`Patch.js`, `Turtles.js`/`Turtle.js`, `Links.js`/`Link.js`, `DataSet.js`, `AgentSet.js`, `AgentArray.js`, `Animator.js`, `Model3D.js`, `ThreeDraw.js`, …), `models/` (~46 example models), `examples/`+`views*/` (runnable demos), `docs/`. The ecology hosting note was preserved as `CLAUDE.local.md` (git-ignored via `.git/info/exclude`); the repo's own `CLAUDE.md` is now in place. - **2026-06-17 — agentscript-orama skill built** (Stephen: "same as taos-engine — bead-mount the taos beads that did skills/documentation, we need the same"). Mirrored the **taos-orama** skill: a full-text Orama index over the AgentScript repo, reusing the **bead-orama** core (`6f5044df`) so `@orama` needs no install — only the source walker swaps (tuned for AgentScript's `.js` layout, kind-prefixed `agentscript/<source|model|example|doc|config>/…`). **414 files indexed**; smoke-tested (diffuse → `DiffuseModel.js`+`Patches`; hatch/die → `Turtle.js`; links → `Links.js`; raster → `DataSet.js`; step loop → `Model.js`). Skill at [`2026-06-17/skills/agentscript-orama/`](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/2026-06-17/skills/agentscript-orama/SKILL.md). - **2026-06-17 — v1 water-droplet model SHIPPED + CDP-verified.** Built [`water-droplets-in-taos.html`](https://redfish.acequia.io/guerin/agentscript/water-droplets-in-taos.html) (live, world-public): **gridless droplets stepped by a real WebGPU compute pass on the engine's device** — each droplet samples the Terrarium DEM, computes a 3×3 Horn/Sobel gradient at a global scrubable `h`, steps along `−∇h`, jitters in flats, respawns out-of-bounds (ping-pong buffers, per-frame readback → billboard render via the `frame.transparent` RenderFeature; terrain via `GeoFeature({scene})`). Editable WGSL kernel (textarea→CodeMirror-6, Ctrl+Enter recompiles). **CDP-verified on a real GPU** (Chrome :9333, `--enable-unsafe-webgpu` + rAF anti-throttle flags): tick advances, droplet elevation monotonically decreases (3405→3399…, downhill confirmed), droplets visibly pool into drainages over Taos Ski Valley terrain, 0 exceptions. Evidence: [`artifacts/water-droplets-v1-verify.png`](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/2026-06-17/artifacts/water-droplets-v1-verify.png). Gotchas: terrain needs `GeoFeature` (not just `GeoScene`); headless/occluded Chrome throttles rAF (use the anti-throttle flags). **Next: water-depth patch field (v1.5 → pooling/accumulation, D8/D-inf), instanced GPU draw (drop the readback), CodeMirror polish, save→subdomain (blocked on Thorp).** - **2026-06-17 — core classes read; `notes/01` written.** Read `Model`/`World`/`AgentSet`/`Turtle`/`Patches`/`Links`/`Link` from real source and wrote the [CPU API reference + translation map](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/2026-06-17/notes/01-cpu-api-reference-and-translation-map.md). Findings: (a) **`startup`/`setup`/`step` are AgentScript-native** (`Model.js:119-134`) — vindicates the hubler `.mjs` contract + closes Q5; (b) **`ask` snapshot-guards births** (`AgentSet.js:263-269`, `id ≤ lastID`) so a GPU count-snapshot reproduces "new agents wait one tick" for free; (c) fixed the SoA schema (`id,theta,x,y,z,alive,breed,seedRNG`, heading derived), the y-flipped row-major patch index, and `diffuse`'s edge-mass-conservation rule. **Next: prototype the `diffuse` compute pass in taos-engine + CDP-verify.**
## Modus Operandi (how to interact) Read `bead-bind-startup.md` first. Use the **taos-orama** skill (in the `c66cbd1d` bead) for engine-API questions. Verify WebGPU with CDP against a real GPU, never a headless screenshot (per the taos-engine bead's `cdp-verify-webgpu` skill).
## Capabilities - **agentscript-orama** ([`2026-06-17/skills/agentscript-orama/`](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/2026-06-17/skills/agentscript-orama/SKILL.md)) — the **on-demand index**: query AgentScript's API/semantics with one Orama query instead of grepping the library. Sibling of `c66cbd1d`'s **taos-orama**; reuses the **bead-orama** core. - **CPU API reference + translation map** ([`2026-06-17/notes/01`](https://redfish.acequia.io/guerin/.agents/f4ef67b7-001f-412c-ba90-f93ceba92bda/2026-06-17/notes/01-cpu-api-reference-and-translation-map.md)) — the curated **load-by-default "menu"** (read from real source): World/AgentSet/Turtle/Patches/Links with `file:line` citations, the SoA buffer schema, and the per-class CPU→GPU table. This is the translation source-of-truth; orama is the fallback behind it. - (Next) a runnable taos-engine compute-pass prototype (first kernel = `diffuse`) + a CDP verify harness.
## Lifecycle Open. Advance per design/build step; `/bead-sync` after a dirtying turn. Apoptose when a working GPU-resident AgentScript step runs inside taos-engine and is verified → fold a durable summary back and `/end-bead`.
## Limitations - Greenfield. The AgentScript source is not yet local; the GPU buffer schema and kernel set are proposed, not validated against the real class hierarchy. - "Translate the architecture" is the charge — fidelity to AgentScript's authoring idiom matters as much as raw GPU throughput. Open question (for Stephen) how much of the JS API surface must be preserved vs. re-imagined for the GPU.
## References (bead cross-links) - Bead: Taos Engine · [canonical](https://redfish.acequia.io/guerin/.agents/c66cbd1d-453c-41f8-8440-179502f25de4/) - Bead: Ants In Taos · [canonical](https://redfish.acequia.io/guerin/.agents/b6fcda63-c171-4293-9d99-75297f4205bb/) - Bead: Taos Samples · [canonical](https://redfish.acequia.io/guerin/.agents/2028c98b-6fae-4d97-8fd9-3c7e4afba988/) - Bead: Taos Recipes · [canonical](https://redfish.acequia.io/guerin/.agents/d6ad03ba-5d96-4cfa-9a17-fe6f36a4f07a/)
See all: Beads