luvcraft/light.lisp
-X, +X, -Y, +Y, -Z, +Z, indexed like content boundary revisions.
One chunk's derived sky and blocklight levels, revised independently from block content. STATE is :UNLIT before any solve, :STABLE when every boundary was known, and :PROVISIONAL when an unknown residency boundary contributed to the result.
Make an unlit resident field whose columns are bound to domain.
What a missing resident neighbor means is a world/source decision. The solver never equates :ABSENT with open sky on its own.
How light should treat the absent neighbor of chunk-key in direction.
Return :OPEN-SKY for a boundary known to see the sky, :CLOSED for a boundary known to be outside the world, or :UNKNOWN for terrain which merely is not resident.
The little generated world declares open sky above its known vertical extent and a closed floor beneath it. Lateral terrain is generatable but simply not resident, which is exactly :UNKNOWN.
Palette-indexed light tables: one generic dispatch per palette entry, then dense u8 lookups in every hot loop.
The finite block-state sites addressed by palette code.
Project block-kind's semantic slot metadata into a storage declaration.
Materialize propagation loss and emission over palette's entry domain.
A captured region: every resident chunk's dense content beside fresh work arrays. The reference solver reads and writes only this capture, then publishes complete fields in one pass.
Frozen regions carry the source's answer for every absent boundary so a producer never consults the live world while solving a captured batch.
A from-scratch capture enumerates its entries eagerly. An incremental candidate instead materializes entries on first touch, initialized from the chunk's current published field, so propagation may wander into any resident chunk without precomputing the affected set.
Materialize chunk's dense capture in region and return the new entry.
Capture every resident chunk of world for a from-scratch relight.
With immutable-p, copy content indices and capture absent-boundary semantics;
the returned region may then be solved without reading the live world.
A lazily populated region whose entries start from current fields.
Resolve scalar world components to ENTRY, OFFSET, and availability.
Resolve a WORLD-COORDINATE to (VALUES ENTRY OFFSET) or NIL when absent.
Whether chunk key currently borders any :UNKNOWN residency boundary.
Call function with OFFSET and borrowed LOCAL for one face of entry.
LOCAL has dynamic extent and must be copied before function retains it.
Solve captured region with the explicitly implemented voxel-light solver.
There is deliberately no default method: unsupported solver names signal instead of silently selecting another implementation.
Publication compares complete candidate arrays against the chunk's current field and advances light revisions only: content revisions and the world revision are authored-data facts this derived domain must not touch.
Install every changed candidate field; return the changed chunks.
Solve and publish voxel light from scratch for world's resident chunks.
Returns the chunks whose published light changed. The selected production
solver must have an explicit solve-light-region-using method.
Sparse light accessors, for inspectors and tests. Dense consumers (the mesher's snapshot halo) read the field arrays directly.
Return (VALUES SKY BLOCK STATE) at one LOCAL-COORDINATE in chunk.
Scalar convenience wrapper around chunk-light-levels-at-coordinate.
Return sparse SKY, BLOCK, and STATE readings at world site X,Y,Z.
This is the inspector-scale light counterpart to world-block-at. Dense light
consumers should bind a chunk field once rather than resolving every site.
Work counters, exposed so performance claims come from measurements.
Accumulated lighting dirtiness for one world, owned by its session.
Content edits and residency transitions feed this object through the
world's hooks; reconcile-lighting settles the queues and publishes.
Subscribe a fresh lighting state to world's content and residency hooks.
Chunks already resident at attachment are treated as arrivals, so the first reconcile lights a caller-built world without a separate protocol.
Whether state includes chunk arrivals or departures.
Settle state's queues over a candidate and publish once.
Returns the chunks whose published light changed. Work runs on the calling owner thread; the counters record its actual cost so any move to captured producer batches is justified by measurement rather than guesswork.
Settle state's dirty cells, departures, and arrivals over candidate
region with the explicitly implemented incremental relighter named by solver.
There is deliberately no default method: unsupported names signal rather than
falling back to a different algorithm. #K3WRD3
Return (VALUES SKY BLOCK STATE) at coordinate, or zeros when absent.
Scalar convenience wrapper around world-light-at-coordinate.
One chunk's derived sky and blocklight levels, revised independently from block content. STATE is :UNLIT before any solve, :STABLE when every boundary was known, and :PROVISIONAL when an unknown residency boundary contributed to the result.
(name-and-options &body lane-descriptions)Define fixed columnar storage whose exact extent comes from one DOMAIN. Each lane has the same syntax as DEFINE-COLUMNAR-BUFFER. The generated MAKE-NAME constructor takes DOMAIN first, asks DOMAIN-CARDINALITY for its exact extent, checks the row declaration once, and allocates one specialized array per lane. The…
(representation)Return the finite site domain bound to REPRESENTATION.
(row lane-name)(materialization field-name)Return the definition object retained by MATERIALIZATION for FIELD-NAME.
(materialization field-name)Return MATERIALIZATION's retained representation for FIELD-NAME.
(domain)(field direction)(direction)(source world chunk-key direction)How light should treat the absent neighbor of CHUNK-KEY in DIRECTION. Return :OPEN-SKY for a boundary known to see the sky, :CLOSED for a boundary known to be outside the world, or :UNKNOWN for terrain which merely is not resident.
(x y z)The finite block-state sites addressed by palette code.
(scheme)(domain)Return the exact number of sites in finite DOMAIN. This deliberately says nothing about coordinate or offset representation. Those mappings belong to concrete domain protocols and are added only when a client needs to traverse them.
(slot-name)(record slot-name)(&key representation-type quantity-specification quantity-layout source-form)(declaration)Return DECLARATION's backend or Common Lisp representation type, or NIL.
(declaration)Return DECLARATION's homogeneous quantity specification, or NIL.
(declaration)Return the source form which established DECLARATION.
(palette)((bindings materialization materialization-type) &body body)Borrow a fixed materialization's domain, extent, row, and raw lane arrays. BINDINGS is (DOMAIN EXTENT ROW-DECLARATION (ARRAY LANE-NAME) ...). The materialization is evaluated once and each array receives its precise specialized array type.
The minimum of compatible quantities.
The maximum of compatible quantities.
Logical disjunction of tests and raw truth values.
Multiplication and scalar scaling.
(entry)(region chunk &key from-field-p copy-content-p)((domain palette indices) chunk &body body)Logical conjunction of tests and raw truth values.
(key direction)(world &key immutable-p)Capture every resident chunk of WORLD for a from-scratch relight. With IMMUTABLE-P, copy content indices and capture absent-boundary semantics; the returned region may then be solved without reading the live world.
(world)(coordinate direction)(world)(world coordinate)(region x y z)(space x y z)Decompose a world site into chunk and local scalar components. Return CHUNK-X, CHUNK-Y, CHUNK-Z, LOCAL-X, LOCAL-Y, and LOCAL-Z without constructing coordinate objects. Euclidean division keeps every local component non-negative, including for negative world coordinates. This is the dense traversal counterpart of…
(x y z)(domain x y z)(region coordinate)(window x y z)Resolve world site X,Y,Z through WINDOW. Return (VALUES MATERIALIZATION OFFSET AVAILABILITY). AVAILABILITY is :AVAILABLE or :UNAVAILABLE; field and subsystem policy must interpret that fact rather than making the spatial protocol call absence air, solid, zero, or open sky. Implementations keep their existing…
(entry offset)(region coordinate direction)(region key direction)(region key)Logical negation of one test or raw truth value.
(entry direction function)Call FUNCTION with OFFSET and borrowed LOCAL for one face of ENTRY. LOCAL has dynamic extent and must be copied before FUNCTION retains it.
((offset local domain direction &optional result) &body body)Execute BODY for every site on DIRECTION's boundary face in DOMAIN. LOCAL is a DYNAMIC-EXTENT LOCAL-COORDINATE and must not be retained after BODY returns.
The voxel-light program selected for production solves. Only :COMPILED is implemented by the runtime. The legacy implementation is loaded explicitly by the LUVCRAFT/LIGHT-REFERENCE system as a differential test oracle; unsupported names signal through the closed EQL dispatch. #X7Q90E #PJY6E1 #K3WRD3
(solver region &key &allow-other-keys)Solve captured REGION with the explicitly implemented voxel-light SOLVER. There is deliberately no default method: unsupported solver names signal instead of silently selecting another implementation.
(domain old-levels new-levels direction)(region)(world)Solve and publish voxel light from scratch for WORLD's resident chunks. Returns the chunks whose published light changed. The selected production solver must have an explicit SOLVE-LIGHT-REGION-USING method.
(chunk local)(domain local)(chunk x y z)(x y z)(world x y z)Return sparse SKY, BLOCK, and STATE readings at world site X,Y,Z. This is the inspector-scale light counterpart to WORLD-BLOCK-AT. Dense light consumers should bind a chunk field once rather than resolving every site.
(world x y z)Return one site as BLOCK and :RESIDENT, or NIL and :ABSENT. This sparse world-coordinate accessor constructs coordinate descriptors and a chunk lookup key. It is appropriate for inspectors, ray hits, collision probes, and sparse interaction. Algorithms over many cells should select a chunk/domain once and use…
Accumulated lighting dirtiness for one world, owned by its session. Content edits and residency transitions feed this object through the world's hooks; RECONCILE-LIGHTING settles the queues and publishes.
A standard class whose annotated slots retain quantity declarations. Slot access and instance representation remain ordinary CLOS. The metaclass only makes definition-time meaning inspectable and inheritable. #OXBSAY
(state)Settle STATE's queues over a candidate and publish once. Returns the chunks whose published light changed. Work runs on the calling owner thread; the counters record its actual cost so any move to captured producer batches is justified by measurement rather than guesswork.
(world)Subscribe a fresh lighting state to WORLD's content and residency hooks. Chunks already resident at attachment are treated as arrivals, so the first reconcile lights a caller-built world without a separate protocol.
(x y z)(state)(solver state region)Settle STATE's dirty cells, departures, and arrivals over candidate REGION with the explicitly implemented incremental relighter named by SOLVER. There is deliberately no default method: unsupported names signal rather than falling back to a different algorithm. #K3WRD3
Division of two represented quantities.
Subtraction or unary negation.
(world coordinate)(space coordinate)Decompose COORDINATE by Euclidean division in SPACE. The local result is always non-negative, including for negative world coordinates.
(world x y z)This page takes an affirmative position: frontier-shaped computation is a real organizing principle for luvcraft, and Common Lisp gives us unusually good means to make that principle executable. The intention is not merely to extract a queue utility from lighting. It is to grow a small frontier language in which a…
Intent: turn the manually staged frontier-light proof into the smallest real compiler path described by #53Q1II. Reify the local transfer, join, admission, and priority arithmetic with checked field meanings; make the program definition drive a scalar execution plan; and emit one closed Lisp loop over bound raw…
Intent: state removal and incremental reconsideration in the same compiled vocabulary after the monotone kernel establishes its source and lowering boundary. Evidence: #ZEENY3. voxel-light-removal is an :invalidation program whose compiled drain reads like unlight-light-region but is emitted from the family and the…
The voxel light field: a derived domain beside block content.
Each resident chunk may own a
chunk-light-field: dense sky and blocklight levels with their own revision and boundary revisions, so relighting never impersonates a content edit. The semantic objects live at the chunk boundary; the 4096-site columns inside are plain (unsigned-byte 8) arrays, and the solver dispatches block light behavior once per palette entry rather than per cell.This file owns capture, publication, and the closed production solver protocol. The compiled frontier programs live in FRONTIER-LIGHT.LISP; the deliberately simple differential oracle is loaded only by the LUVCRAFT/LIGHT-REFERENCE system.