luv

Workshop wiki

index.org

The luv workshop wiki

A workshop, not an authority #H7QK3M

This wiki is a place to develop an understanding of GPU programming, engine design, and implementation. Its first subject was the shape of WebGPU and the work hidden beneath that shape. The little block world now adds a second path: how a live Common Lisp game might understand worlds, materialized data, measurement, simulation, and presentation without prematurely becoming a framework.

Neither resemblance to WebGPU nor presence in the current luv implementation makes something correct. WebGPU is a landmark: we want to understand the problems its design addresses and the consequences of its answers. Luv may adopt, simplify, alter, or reject those answers. Likewise, current luv code is a live experiment. It can supply observations and case studies, but must not be used as ground truth to justify itself.

The pages try to keep three voices distinct:

Claims about intention deserve special care. The specification is good evidence for the contract and some rationale, but a historical claim about why the working group chose a design may require proposals, issues, meeting notes, or mailing-list archaeology. An attractive retrospective explanation is not automatically a historical fact.

Source-study pages use a parallel discipline: distinguish a mechanism observed in code, a claim made by its documentation, and our reading of what it might teach luv. The block-world synthesis pages distinguish those forms of evidence from tentative vocabularies and experiments still to be tried.

String figures #F2N8VX

An addressable piece of discourse is a figure. For now a figure is an Org heading with a stable six-character ID property. Files gather figures by subject; they do not provide their identities. A figure can move, acquire a better title, or be substantially revised while its identifier remains the same.

A plain mention such as #D3H7VK passes a figure into another passage. Org's standard [[id:D3H7VK]] form is also available when a clickable link is more useful than the light notation. We can derive lookup, outgoing links, backlinks, dangling references, and code-to-discourse links from these mentions; any such index should be disposable rather than another source of truth.

Common Lisp gives us an especially cheap future notation. A WIKI package could export figure symbols, allowing source to mention 'wiki:D3H7VK without a reader macro. We should first let real uses teach us whether a symbol means only a stable reference, a resolvable object, source metadata, or something else. Comments and docstrings containing #D3H7VK already participate in the discourse without changing Lisp semantics.

Work marks #W3K9MK

Some figures are also work marks: tiny roadmap entries that live in the same wiki page as the design they move forward. A work mark is an Org heading with:

The status words are deliberately small. NEXT is the current best small bet. TODO is committed enough to keep visible but not selected. WAIT needs outside information or another completed step. DONE records the evidence that closed the loop. IDEA is a tempting possibility that should not steer implementation yet.

Work marks should not duplicate code review, issues, or test output. They are the wiki's memory of why a step exists, what would count as progress, and what evidence changed its status. When implementation changes the plan, update the nearby work mark instead of appending a disconnected status page.

Paths into the initial material #S9D4KC

The following are starting paths rather than a table of settled doctrine.

Engineering the implementation #0L51TG

  • The shared Lisp application workbench records the application-neutral status line, M-x, metabar, lobby, capture, profiling, live-artifact, lifecycle, and language-agent boundaries now reused by Luvcraft and LUFT. It keeps game-specific semantics in thin adapters and makes direct retained GPU presentation the contract for application panels.
  • Technical debt that multiplies truths ranks the current architectural debt by the number of places that must agree. It names concrete deletion cuts, protocol extractions, and ownership boundaries rather than treating file size or unfinished experiments as debt by themselves.

GPU semantics and implementation #G4R8PU

  • The GPU API and its backend proofs is the current architectural map. It follows the portable command vocabulary through Vulkan and Metal, separates WebGPU influence from luv's actual contract, and names the concrete proofs for dependency capture, completion, destruction, frame pacing, synchronization, and host access.
  • Seeing a frame on the CPU separates instrumented CPU zones, drawable pacing, submission completion, and eventual GPU timestamps. It records the current luvcraft/Metal trace and the backend-neutral command seam exposed by that work.
  • Mathematical shaders as live Lisp objects records the typed expression language above the literal SPIR-V assembler, its deterministic CLOS lowering, and the McCLIM presentation browser connecting source to SSA.
  • Slug: Bézier outlines in the pixel shader reconstructs the exact quadratic root classification and two-ray coverage algorithm from its now-open references, records the 2026 data contracts, and carries one fixed contour through luv's shader DSL to an actual Metal image.
  • Objective-C as a foreign object system records declared message ABIs, direct message sends, explicit native ownership, opt-in trace events, and the diagnostic scope that turns native exceptions into Lisp conditions.
  • The native Metal 4 backend is the canonical implementation path: the SDL/CAMetalLayer frame path, direct MSL lowering, MTL4Compiler, argument tables, the live luvcraft pipeline, and its remaining backend-local work.

The little block world #B7W3LD

  • The little block world and its possible worlds is the game-shaped starting path: what exists now, what kind of world it might become, and an order of experiments intended to stay fun.
  • The luvcraft showcase gazetteer maps the executable capture system onto composed landscape and lighting scenes, world-native panes, player instruments, inhabitants, agents, physics, authored celebrations, and controlled reference plates.
  • A terminal in the little world joins libghostty-vt's terminal semantics and dirty render snapshots to luv's Slug text path and the existing world-overlay interaction seam. Its first slice draws one fixed terminal row directly in the scene before attaching a live PTY.
  • Field notes on four agent harnesses reads froth, sheaf, nxt and swash for what a luv agent surface should inherit: typed tool results with several renderings, size handled by the harness, short handles resolved by the store, history kept as data, and a runtime that can explain its silences.
  • Autolith: a primer on an agent that is a Lisp image reads the fifth harness in detail: a REPL as the prompt line, tools as fbound functions, request-local context with a budget, restarts as a tool argument, and a self-modification ladder from self.eval to replay-probed image commits.
  • An agent in the little world designs luv's own agent surface in CLIM terms: tools as commands with presentation-typed arguments, results as presentations read under a model view, cassettes drawn on the HUD and committed to a wall, and an agent with a body.
  • LUFT: packed sites, chains, and the atelier names every vertex, edge, face, and cell of a cubical world with one fixnum, treats a block world as a 3-chain whose boundary is its surface, and draws that surface by vertex shaders pulling the packed words directly from a storage buffer.
  • The bevel junction is an open problem preserves the sharp bevel's correct-by-construction structure, the mixed-vertex collapse, the rejected pinwheel transition, and the Blender Arc reference without pretending that the next representation has already been chosen.
  • The beveled surface is a sum over sites answers that page: every bevel vertex is an integer offset-line intersection, junctions are fans of one equilateral tile counted by turning, sharp miters leave a (3,1,1) fingerprint that the Arc policy removes, and the renderer becomes three instance streams — faces, bands, and fans — checked against Blender's Arc bevel as an executable oracle.
  • Temporal reconstruction in the Luft atelier follows a frozen jittered view through Vulkan colour and motion attachments, ping-pong history, YCoCg rejection, and lens presentation. It records the resource-ownership refactor TAA forced, the small MRT/format extension the HAL needed, and the backend boundary left for MetalFX.
  • Domains, bundles, and materialized worlds studies why CLOS and structure-of-arrays storage are compatible, and what chunking, level of detail, procedural generation, and streaming ask of the object model.
  • Voxel fields and chunk windows takes the working light and meshing systems as the first concrete domain/bundle clients. It separates local domain traversal, cross-chunk windows, semantic field products, provenance, and checked arithmetic kernels, then names the first extraction to perform.
  • Vocabularies as finite domains applies the domain and materialization vocabulary to naming rather than space: atlas tiles, block materials, and the tables that resolve a symbolic identity into an offset a hot loop can index. It takes a merge collision over one atlas tile number as its evidence and names the invalidation rules a live vocabulary needs.
  • Frontiers, memoization, and materialized worlds studies the small Haskell frontier repository as an operational account of worklist traversal: unfolding, result reservation, memoization, admission, scheduling, and commitment. It then distinguishes discover-once, monotone relaxation, and invalidation work across lighting, terminal walls, fluids, fire, signals, navigation, ecology, and chunk production.
  • Quantities, dimensions, and interpretation studies Moppe's mp-units practice and the Zig Étalon experiment, then follows the resulting semantic arithmetic into homogeneous vector components, heterogeneous packed GPU tuples, semantic projective maps, and compact SIMD-friendly representations. It records where the built system goes beyond its sources and the next production steps: declaring luvcraft's quantity character and sharing one checked computation between CPU and GPU.
  • The Moppe legacy reads the predecessor engine's lighting, post-processing, atmosphere, temporal reconstruction, and mesh shaders as source evidence and a tuning library. Backend architecture now lives on the Metal page.
  • Field notes on mp-units studies the abstractions beyond dimension in the live mp-units checkout: the point/absolute/delta model, two-axis quantity character, and logarithmic quantities as affine structure over a log domain.
  • Field notes on measures reads the 1992 Cunis dim-number package — the prime-ratio dimension encoding, the runtime-object fork in the road it documents, and the measure of everything a quantity system needs beyond dimension.
  • Physics data and SIMD execution identifies the seam for a Catto-inspired 3D physics experiment: CLOS at semantic boundaries, dense domains and columnar numerical state inside the step, and derived collision structures between bodies and the block world.
  • Sky, atmosphere, and voxel light for the little block world is the reviewed implementation path for a more capable mathematical shader language, an animated sky, height-independent skylight and blocklight, visible relighting on edits and residency changes, stable filtered sun shadows, and an eventual linear-HDR bloom path.
  • Field notes on Box3D's architecture follows the concrete identity, sparse/dense storage, solver-set, contact, constraint-coloring, determinism, and event mechanisms behind that landmark.
  • Field notes on sb-simd studies the generated SIMD vocabulary, scalar mirrors, and dispatch model, then records the new project invariant: luv's pinned SBCL supplies native SIMD on arm64/NEON and x86-64.

The wiki itself #2RRDHC

  • The wiki as a static site records how these pages become a browsable site: the Org subset the reader understands, why the build is an ASDF operation on org-file components, and the Spinneret rendering choices.

A useful first crossing is from the timeline distinction #T4V8QM to the ownership phases in #L8R2WF, then to Vulkan's logical/physical destruction split #D3H7VK and the frame slots that became pacing clients #M6P8XW. That path explains why “the Lisp object is no longer wanted,” “the API object is destroyed,” and “the backend may release the allocation” are not the same event.