# core.adjacency (procNode) Answer a neighbour relation over a geometry as a table of offsets and items: the points around a point, the primitives that use a point, the primitives across an edge, the edges and points of a primitive, and the rest of eight relations. Relations (`<owner>_<listed>`): `point_points`, `point_faces`, `point_edges`, `face_points`, `face_edges`, `face_faces`, `edge_points`, `edge_faces`. Built from `core.owner`, `core.edges`, the `expand` kernel (a side or an end per edge; the two faces of each edge that has two are laid out over the live total of those pairs, which one read-back states), `sort` of the owner keys, `scatter` for each owner's count, `scan` for the offsets and `gather`. Outputs: `offsets` (where each owner's list starts in `items`), `counts` (the length of each list) and `items`. The relation's owners are numbered as its first word says: points, primitives or edges. ## Inputs - `geometry` (Geometry). The geometry whose neighbours are listed. - `relation` (one of point_points, point_faces, point_edges, face_points, face_edges, face_faces, edge_points, edge_faces). Default `"point_points"`. Which relation: the owner's kind, then the listed kind. "point_faces" lists, for each point, the primitives that use it. ## Outputs - `offsets`: where each owner's list starts in `items`. - `counts`: the length of each owner's list. - `items`: the listed elements, owner after owner.

# core.arclength (procNode) The length along every curve: each point's distance from the start of its curve as `s`, and each curve's total as `length`. Built from `core.owner`, `attribute.promote` (positions to vertices), `gather` of each vertex's next position, `math.length`, a segmented `scan` for the distance so far and a segmented `reduce` for the total. A closed curve counts its closing segment in `length`; an open curve has none. Written as `s` on the point class and `length` on the primitive class. ## Inputs - `curve` (Curves). The curves measured. ## Outputs - `curve`: the curves with `s` (distance along the curve) on the point class and `length` (the curve total) on the primitive class.

# core.boundary (procNode) The open edges of a geometry and the rings (or chains) they form, each ordered along its walk. Built from `core.edges`, `compact` of the open edges, the `loops` kernel (the edge that follows each one), `jump` rounds (the smallest edge in reach, then the distance to the end of each list; the rounds are `ceil(log2(edges))`), `loops_cut` and `loops_place`, and `scan` of the ring lengths (`segments = 0`). ## Inputs - `geometry` (Geometry). The geometry whose boundary is walked. ## Outputs - `edges`: Record `a`, `b`, `from`, `to`, `source`, `count` of the open edges. - `rings`: Record `ring`, `position`, `order`, `starts`, `count` of the rings.

# core.column (procNode) Make a column from a list of numbers, one element each: the values a graph computed one by one gathered into a run the device can read, such as the births of each source before a scan. Built from `op.transfer.upload`. ## Inputs - `values` (List<Number>). The numbers, in order. - `type` (one of Int, Float). Default `"Int"`. Whether the elements are whole numbers or floats. ## Outputs - `column`: the Column of the numbers.

# core.concat (procNode) Join several geometries into one: points, vertices and primitives end to end, links renumbered, every column any geometry holds. Built from the `concat` kernel, one run per column any geometry holds in each class (the `concat` module lists them, the structure columns and stored numbers such as `id`, `N` and `uv` included). `core.join` answers where each part starts. The `concat` module in this node's folder decides every column of a class in one call: the type it takes (the type the first part with elements holds it as; a part that holds it at another width is refused by name, one that holds it as another type of the same width is cast by value), the part that decides it, its description words, and whether the parts bind as they stand. A column every part holds as that type, with elements, in a run of its own, costs two dispatches whatever the number of parts: the typed destination and the join. Any other column first casts each part by value to the joined type, and the elements of a part that holds no such column stand at zero for it. The link columns shift by what comes before: `vertex.pt` by the points of earlier parts, `primitive.vstart` by their vertices. A column of a type the device cannot hold (text, a record) is laid end to end by the `concat` module in this node's folder, as a column of values; a part that holds no such column leaves its elements without a value. ## Ids The point `id` of each part moves past the ids of the parts before it, so every id of the result is unique. A part spans the larger of its next id and its point count. A part without an `id` column is numbered in order after them. A column carries no statement of what its values mean, so the join keeps a list of the point columns that hold the `id` of another point, in the `concat` module of this node: `parent`. Where some part holds ids, each part's `parent` values move by the amount its ids move, a negative value (no parent) stays, and a part without a `parent` column parents nothing (-1). Where no part holds ids, `parent` values refer to nothing the join renumbers and join as they are. A hierarchy built in two parts, each numbered from 0, keeps its parenting through the join. ## Inputs - `geometries` (List<Geometry>). The geometries joined, in order. ## Outputs - `geometry`: the joined geometry.

# core.corners (procNode) For every vertex, the vertex after it and the vertex before it in its primitive (a cycle), and the primitive it belongs to. Built from `core.owner` and the `gather` kernel. A primitive's run of `vcount` vertices starting at `vstart` is read as a cycle: the vertex after the last is the first. Outputs `owner`, `next` and `previous`, vertex indices. ## Inputs - `geometry` (Geometry). The geometry whose vertices are read. ## Outputs - `owner`: the primitive of each vertex. - `next`: the vertex after it in its primitive. - `previous`: the vertex before it.

# core.edges (procNode) The edge table of a geometry: every distinct side of its primitives as a point pair (a < b), the primitives along each side, whether the side is open (one primitive) or manifold (at most two), and the edge each vertex slot's side belongs to. Built from the `edges` kernel (the sides of every primitive), two stable `sort` passes (by the higher point, then the lower), `gather`, the `edges_runs` kernel (run heads, then the table), `compact` of the heads, an inclusive `scan` of the heads (the edge of each sorted place) and `scatter` through the slot order to give `sideEdge`, the edge id of every vertex slot. ## Inputs - `geometry` (Geometry). The geometry whose sides are listed. - `faces` (Bool). Default `true`. True for a geometry of faces, whose primitives wrap from their last vertex to their first; false for curves, which wrap only where their `closed` attribute says. ## Outputs - `edges`: Record `a`, `b`, `faceStart`, `faceCount`, `faces`, `open`, `manifold`, `reversed`, `sideEdge` (the edge each vertex slot's side belongs to, -1 for a slot with no side) and `count`.

# core.entity.read (procNode) Read live entities as columns, one element per entity, with the number read as `count`. Built from `io.engine` with `readEntities`, then `op.transfer.upload` of the columns it answers. The result is one Record: a column for each field read, and `count`; `core.points` makes points of it. The query names the entities by `ids` (a list of entity ids), `name` (a Name or glob), `component`, or `colliders` (with `sensors`); `fields` is `{ pose = true, space = "world" }` for `P`, `orient` and `scale`, or a list of `position`, `rotation`, `scale`, `id`, `shapeType`, `params` and `Component.field` names. ## Inputs - `query` (Record). Which entities: `ids` (entity ids), `name` (a Name or a glob), `component`, or `colliders = true` with `sensors`. - `fields` (Record, optional). What to read: `{ pose = true, space = "world" | "local" }`, or a list of `position`, `rotation`, `scale`, `id`, `shapeType`, `params`, or `Component.field`. - `space` (one of world, local). Default `"world"`. The space the pose fields of a list are read in. ## Outputs - `read`: Record of one column per field read, and `count`.

# core.interpolate (procNode) Carry a geometry's attributes to sample points: point and vertex values blended by the barycentric weights, primitive values taken from the sample's primitive, values that cannot blend taken from the nearest corner. Built from `gather` at the sample's corners and `math` operators for the blend, over the names `geometry.names[class]` lists for each class. A column of floats blends by `bary`; a column of integers takes the corner with the largest weight. ## Inputs - `geometry` (Geometry). The geometry sampled. - `samples` (Points). The samples: points with `prim`, `ia`, `ib`, `ic` (corner vertices) and `bary` (their weights), as `core.sample.surface` and `core.sample_curve` make them. ## Outputs - `points`: the samples with the geometry's attributes.

# core.islands (procNode) Label every primitive with the connected island it belongs to: primitives that share a point are in the same island. Answers the island of each primitive and the number of islands. Built from `core.edges`, `jump` in label mode folded until no label changes (`g:fold` with `stop = "changed"`), `gather`, `scatter` and `compact`. Every point takes the smallest point number of the points joined to it by an edge; a primitive's island is the label of its first point, renumbered 0 to count - 1 in order of first appearance by label. Outputs `islands` (one number per primitive) and `count`. ## Inputs - `geometry` (Geometry). The geometry whose primitives are labelled. ## Outputs - `islands`: the island number of each primitive. - `count`: how many islands.

# core.join (procNode) The numbers a join of several geometries needs: where each part starts in every class, the description words the `concat` kernel reads for one attribute, and each class's counts and starts as lists. `core.concat` and `core.realize` call it. Built from `op.transfer.readback` of each part's counts and the Luau node over `join.module`, which sits in this node's folder. ## Inputs - `what` (one of layout, words, sources). Default `"layout"`. Which numbers are answered. - `geometries` (List<Geometry>, optional). For "layout": the geometries joined, in order. - `layout` (Record, optional). For "words" and "sources": what "layout" answered. - `class` (one of point, vertex, primitive). Default `"point"`. For "words": the class of the attribute. - `name` (String). Default `""`. For "words": the attribute's name. ## Outputs - `value`: for "layout" the Record `starts`, `counts`, `parts` and a total per class; for "words" the List of description words; for "sources" the Record of per-class `counts` and `starts` lists.

# core.make (procNode) Make geometry on the device from a count for each owner and a shape. Every owner makes its own piece and the pieces sit end to end with their links already offset. The `make` kernel's `sizes` pass, a prefix sum of the sizes, and the `make` kernel's `fill` pass; the columns are set into an empty geometry. The totals the fill pass is sized by come from the counts when every owner makes `count` (a row of points needs one multiplication, the other shapes one call of the `make` module); a count the graph states is a number already and the cook does not wait on the device for it, and a count left on the device is read back. When `counts` gives each owner its own, the totals are read back from the prefix sum. ## Inputs - `shape` (one of points, strip, fan, grid, ring). Default `"points"`. What each owner makes: a row of points, a zigzag of triangles, triangles round a centre, a lattice of quads, or one closed primitive round a circle. - `counts` (Column<Int>). One count for each owner: the points along its main axis. Left out, every owner makes `count`. - `count` (Number). Default `0`. The points along the main axis of each owner when `counts` is left out. - `owners` (Number). Default `1`. How many owners make a piece when `counts` is left out. - `across` (Number). Default `2`. For the grid: how many points it holds along its second axis. ## Outputs - `geometry`: the geometry with `P` on its points (the unit square or the unit circle), `pt` on its vertices and `vstart` and `vcount` on its primitives; a ring also carries `closed`.

# core.names (procNode) The names of every column a class of a geometry holds, sorted. A class holds its structure columns (`P` and `id` on points, `pt` on vertices, `vstart` and `vcount` on primitives, `closed` on curves) and the attributes written on it. `attribute.carry` and `core.concat` move and join a class by walking this list, one column at a time. ## Inputs - `geometry` (Geometry). The geometry whose columns are listed. - `class` ("point", "vertex" or "primitive"). The class whose columns are listed. - `links` (Bool). Default `true`. Whether the columns that tie the classes together (`pt`, `vstart`, `vcount`, `closed`, `curve`) are listed; `false` lists the other columns of the class. ## Outputs - `names`: the sorted list of column names.

# core.neighbours (procNode) What stands near each point: how many points lie within a radius (optionally inside a cone), the nearest one, their centroid, the mean of an attribute over them, or the push away from them. Built from `core.pairs` (the points within the radius of each point), the `hash_nearest` kernel over `core.spatial`, `gather`, `math` operators for the cone and the push, and `scatter` folds back to the points. `mode` "measure" writes `neighbors` (count), `nearest` (distance to the nearest), `centroid`, and `neighbor_<name>` for `mean`; "nearest" writes `nearest_index` (the source point nearest each point, -1 where none lies within `radius` when it is above 0) and `nearest`; "repel" writes `push`, the average direction away from the neighbours within `radius`, each weighted by how close it stands. `direction`, `cone` and `mean` are plain values chosen when the graph is built. Without `sources` a point's neighbours are the other points of `points`. ## Inputs - `points` (Geometry). The points that look around. - `sources` (Geometry, optional). The points looked at. Left empty, each point looks at the others of `points`. - `radius` (Number). Default `1.0`. How far a point looks. 0 looks without limit in "nearest" mode. - `mode` (one of measure, nearest, repel). Default `"measure"`. What is answered: counts and centroids, the nearest source, or the push away. - `direction` (String). Default `""`. A Vec3 point attribute each point looks along; given, only neighbours inside the cone count. - `cone` (Number). Default `360.0`. The full angle in degrees of the cone around `direction`; 360 counts every side. - `mean` (String). Default `""`. A numeric point attribute whose neighbours' average each point takes as `neighbor_<name>`. ## Outputs - `points`: the points with the answers as attributes.

# core.normals.corner (procNode) A normal for every vertex that smooths across the primitives around its point where they meet at less than a crease angle, and keeps an edge hard where they meet at more. Built from `core.normals.face`, `core.adjacency` (the primitives around each point), `core.owner`, the `expand` kernel (one slot per primitive around the vertex's point), `gather`, `math.dot`, `math.where` and `scatter` with an add fold, then `math.normalize`. A vertex takes the sum of the normals of the primitives around its point whose normal is within `angle` degrees of its own primitive's, each weighted by area or equally. Written as `N` on the vertex class. ## Inputs - `geometry` (Geometry). The geometry whose vertices get normals. - `angle` (Number). Default `60`. The crease angle: primitives around a point whose normals differ from a vertex's own by no more than this are smoothed into it. - `weighting` (one of area, uniform). Default `"area"`. How each primitive counts in the average: by its size or equally. - `name` (String). Default `"N"`. The attribute the normals are written under on the vertex class. ## Outputs - `geometry`: the geometry with a normal on every vertex.

# core.normals.face (procNode) Give every primitive its normal: the direction its vertices wind around, written as `N` on the primitive class. `scaled` is the same direction scaled by twice the primitive's area. Built from `core.corners`, `attribute.promote` (point to vertex), `gather` of the next corner, `math.cross` and a segmented `reduce` over each primitive's run (`segments = primitive.count`). ## Inputs - `geometry` (Geometry). The geometry whose primitives get normals. - `name` (String). Default `"N"`. The attribute the normals are written under on the primitive class. ## Outputs - `geometry`: the geometry with a normal on every primitive. - `scaled`: the same direction scaled by twice the primitive's area, a Vec3 column per primitive.

# core.normals.point (procNode) The normal of the surface at every point: the normals of the primitives that use the point, summed with each weighted by its area, by the angle it spans at the point, or equally, and normalized, written as `N` on the point class. Built from `core.normals.face`, `attribute.promote` (primitive to point, sum) for "area" and "uniform"; for "angle" the corner angle `math.acos` of the dot product of the two unit edges at each vertex, the face normal gathered to the vertex by its owner, scaled by that angle and scattered to the point. ## Inputs - `geometry` (Geometry). The geometry whose points get normals. - `weighting` (one of area, angle, uniform). Default `"area"`. How the primitives around a point count: "area" weights each by its size, "angle" by the angle it spans at the point, "uniform" counts each equally. - `name` (String). Default `"N"`. The attribute the normals are written under on the point class. ## Outputs - `geometry`: the geometry with a normal on every point.

# core.owner (procNode) The primitive each vertex belongs to, and the vertex's place within that primitive. Built from the `expand` kernel over the primitives' runs: primitive `i` owns the `vcount` vertices that start at `vstart`. Outputs `owner` (the primitive id of each vertex) and `local_index` (the vertex's position in its primitive's run). The building block under every promotion between vertices and primitives. ## Inputs - `geometry` (Geometry). The geometry whose vertices are owned. ## Outputs - `owner`: the primitive of each vertex. - `local_index`: the vertex's place in its primitive's run.

# core.pairs (procNode) Every pair of points within a radius: for each query point, the source points that stand within the radius of it, as a list of owners and items. Built from `core.spatial` over the sources, the `hash_count` and `hash_gather` kernels, `scan` of the counts and `expand` of each query's list into one row per pair. Outputs: `owner` (the query point of each pair), `items` (the source point of each pair), `counts` and `offsets` (each query's list in `items`) and `total`. A point is not its own neighbour when the queries are the sources. ## Inputs - `points` (Geometry). The query points. - `sources` (Geometry, optional). The points looked at. Left empty, the query points look at each other. - `radius` (Number). Default `1.0`. How far a query point reaches. ## Outputs - `owner`: the query point of each pair. - `items`: the source point of each pair. - `counts`: the length of each query's list. - `offsets`: where each query's list starts in `items`. - `total`: the number of pairs. - `spatial`: the `core.spatial` record the sources were indexed by.

# core.points (procNode) Points made from columns: a count of points, each attribute given as a column, a field or a constant. Built from the `make` kernel (`SHAPE = "points"`) for the elements and a point-class write for every entry of `columns`. The call is `g.core.points({ columns = { P = positions, mass = 1.0 }, count = 64 })`; `count` is how many points there are. ## Inputs - `columns` (Record, optional). The attributes, by name: each a column of the point count, a field evaluated over the points, or a constant. `P` places the points; the other names are carried as point attributes. - `count` (Number). Default `0`. How many points. ## Outputs - `points`: the points.

# core.raster.add_layer (procNode) Add a named layer to a raster, every cell zero; a layer already there is left as it is. Built from `g.has` over the raster's layers and a point-class column write. ## Inputs - `raster` (Raster). The raster extended. - `name` (String). Default `""`. The layer's name. ## Outputs - `raster`: the raster with the layer.

# core.raster.blend (procNode) Blend a value into one layer of a raster, cell by cell, by a weight, over every cell the tiles hold (the cells of the field, the cells of a border tile past it and the ring around the tiles): replace, add, take the greater or lesser, or multiply. Built from `g.field.substitute` (the cell position into `value` and `weight`, each held cell at its own position) and the `grid` kernel in write mode over the raster's tile layout (`MODE = write`, `BLEND = mode`), the patch window starting `apron` cells before the field's first cell and spanning `heldX` by `heldZ`. Every tile that holds a cell, as core or as apron, receives it, so the aprons agree. The weight scales how much of the value is blended in: 0 leaves the cell alone and 1 applies the mode in full. ## Inputs - `raster` (Raster). The raster written. - `layer` (String). Default `"height"`. The layer written. - `value` (Value). Default `0.0`. What is blended in, per cell: a number, a column over the held cells (`core.raster.read` with `held`) or a field of the cell's position. - `weight` (Value). Default `1.0`. How much of the value applies per cell, 0 to 1. - `mode` (one of replace, add, max, min, multiply). Default `"replace"`. How the value meets the cell: replaces it, is added to it, or the greater, the lesser or the product of the two is kept. ## Outputs - `raster`: the raster with the layer written.

# core.raster.cells (procNode) Name the cells of a raster as a flat run, x fastest then z: the position of each cell's centre, and the place in a layer's tiled storage that holds it, optionally at an offset of whole cells. Built from `g.element.id` and `math` operators over the raster's layout members. Every node that reads or writes a layer cell by cell calls it. ## Inputs - `raster` (Raster). The raster whose cells are named. - `dx` (Number). Default `0`. Cells along x the stored place is offset by; the read is held to the edge of the field. - `dz` (Number). Default `0`. Cells along z the stored place is offset by. - `held` (Bool). Default `false`. Name every cell the tiles hold rather than the cells of the field: `heldX` cells across and `heldZ` down, the run starting `apron` cells before the field's first cell. An offset is then held to the edge of what the tiles hold. ## Outputs - `count`: the cells of the field, `cellsX` times `cellsZ`; with `held`, `heldX` times `heldZ`. - `position`: a Vec3 field: the world position of each cell's centre (a cell past the field has the position it has in the field's grid). - `index`: an Int field: the place in a layer's stored column that holds each cell, offset by `dx`, `dz` and held to the field (or to what the tiles hold, with `held`). A cell past the field is addressed in the border tile beside it.

# core.raster.column (procNode) A layer of a raster as its stored column: the cells of every tile, apron included, tile after tile, each tile `stride` by `stride` cells with x fastest. What a kernel that works tile by tile binds. ## Inputs - `raster` (Raster). The raster read. - `layer` (String). Default `"height"`. The layer read. ## Outputs - `column`: the layer's stored column.

# core.raster.new (procNode) Open a rect of ground as a Raster: a grid of cells, cut into tiles of 256 cells a side that each store a ring of 8 neighbour cells (stride 272), with named layers of one number per cell, all zero. The tiles store more than the rect: the cells of a border tile past the rect and the ring around the tiles are stored like the rest, and a write reaches them. The Raster is a Record. Layout members: `cellsX`, `cellsZ`, `resolution`, `min`, `size`, `origin` (Vec3, the `y` lane 0), the same as numbers `minX`, `minZ`, `sizeX`, `sizeZ`, `originX`, `originZ`, `core` (256), `apron` (8), `stride` (272), `tilesX`, `tilesZ`, `tiles` (also `tileCount`), `heldX` and `heldZ` (the cells the tiles hold across and down: the tiles' cores, `tilesX * core` by `tilesZ * core`, and the ring of `apron` cells around them), `layerNames` (the list of layer names) and `layers`, a Geometry whose point class holds the stored cells of every tile, one column per layer. The `grid` kernel and `core.raster.cells` read that layout. ## Inputs - `origin` (Vec2). Default `{ x = 0, z = 0 }`. The world centre of the rect, in metres. - `size` (Vec2). The extent of the rect along x and z, in metres, as `{ x, z }`. - `resolution` (Float). Metres per cell. - `layers` (List<String>, optional). The layers the raster opens with. ## Outputs - `raster`: the Raster.

# core.raster.read (procNode) Read a layer of a raster as a column over the field's cells, x fastest then z, each cell optionally taken from a neighbour a whole number of cells away; a read past the edge answers the edge cell. Built from `core.raster.cells` and the `gather` kernel. ## Inputs - `raster` (Raster). The raster read. - `layer` (String). Default `"height"`. The layer read. - `dx` (Number). Default `0`. Cells along x the read is offset by. - `dz` (Number). Default `0`. Cells along z the read is offset by. - `held` (Bool). Default `false`. Read every cell the tiles hold, the cells past the field included, rather than the cells of the field. ## Outputs - `value`: a Float column over the field's cells, or over the held cells. - `count`: the cells read.

# core.raster.reduce (procNode) Fold a layer of a raster to one number: the sum, mean, least or greatest of its cells. Built from `core.raster.read` and `core.reduce`. ## Inputs - `raster` (Raster). The raster folded. - `layer` (String). Default `"height"`. The layer folded. - `op` (one of sum, mean, min, max). Default `"sum"`. How the cells fold. ## Outputs - `value`: the folded number.

# core.raster.remove_layer (procNode) Remove a named layer from a raster. Built from a point-class column removal on the raster's layers. ## Inputs - `raster` (Raster). The raster shortened. - `name` (String). Default `""`. The layer removed. ## Outputs - `raster`: the raster without the layer.

# core.raster.resolve (procNode) Fold a layer of fixed-point changes into the layer they change: every cell of `delta` holds a whole number of 1/`fixed` units, added to `layer`; `delta` is then zero. Built from the `gather` kernel reading `delta`'s words as 32-bit integers, `math.to_float`, and a `core.raster.blend` pass that adds them, so every tile that holds a cell takes the result; `delta` is then written zero in every place it is stored. Every cell the tiles hold, the cells past the field included, takes its own change. ## Inputs - `raster` (Raster). The raster resolved. - `layer` (String). Default `"height"`. The layer the changes are added to. - `delta` (String). Default `""`. The layer holding the changes as 32-bit integers. - `fixed` (Number). Default `65536`. How many integer units make one unit of the layer. ## Outputs - `raster`: the raster with the changes added and `delta` zero.

# core.raster.sample (procNode) Sample a layer at world positions with a bilinear blend of the four cells around each, reading the cells the raster holds past the field for a position beside it, and holding the last cell past everything the tiles hold. Built from `core.raster.read` (held), `g.field.gather` and `math.lerp`, as a field over whatever elements the positions come from. ## Inputs - `raster` (Raster). The raster sampled. - `layer` (String). Default `"height"`. The layer sampled. - `at` (Value). The positions sampled: a Vec3 field or column, read by x and z. ## Outputs - `value`: a Float field of the blended layer value at each position. - `count`: the cells of the field.

# core.raster.stencil (procNode) Measure the shape of a layer around every cell: its slope in degrees or its curvature (the laplacian over x and z). Built from the `grid` kernel in stencil mode over every stored cell, then `gather` through `core.raster.cells` to a column over the field's cells. ## Inputs - `raster` (Raster). The raster measured. - `layer` (String). Default `"height"`. The layer measured. - `kind` (one of slope, curvature). Default `"slope"`. What is measured: the slope in degrees, or the curvature. - `held` (Bool). Default `false`. Answer a column over every cell the tiles hold rather than over the cells of the field. A cell's neighbours are the cells its tile stores around it, so a cell at the edge of the field is measured against the cells the raster holds beyond it. ## Outputs - `value`: a Float column over the field's cells, or over the held cells. - `count`: the cells measured.

# core.realize (procNode) Copy source geometries onto points: every point stands a copy of its source (one source for all, or the one its `variant` names), the copy placed by the point's position, orientation and scale. Built from `core.concat` (the sources as one catalog), `core.join` (each source's counts and starts), `scan` of the per-point element counts, the `expand` kernel (one row per copied element), `gather` of the catalog's columns, `math` operators for the placement, and `gather` to renumber `vertex.pt` and `primitive.vstart` into the copies. Every attribute of an instance point, `orient`, `scale` and `variant` included, stands on each point of its copy. ## Inputs - `points` (Points). The instance points. - `sources` (List<Geometry>). The geometries copied, in the order `variant` counts them. - `variant` (String). Default `""`. The point attribute that picks a source by number, 0 for the first; empty gives every point the first source. - `orient` (String). Default `"orient"`. The point attribute holding each point's rotation as a quaternion; empty places without rotation. - `scale` (String). Default `"scale"`. The point attribute holding each point's scale; empty places at full size. ## Outputs - `geometry`: the copies as one geometry.

# core.reduce (procNode) Fold a column to one value, or to one value per segment: sum, mean, least, greatest, count or the place of the least or greatest. One `reduce` kernel run. `fold` names the fold. `starts` holds where each segment starts; the kernel then gets `segments = starts.count`, and without `starts` it folds the whole column with `segments = 0`. ## Inputs - `values` (Column). The column folded. - `fold` (one of add, mean, min, max, count, argmin, argmax). Default `"add"`. How the elements fold: added up, averaged, the least, the greatest, how many, or the index of the least or the greatest. - `starts` (Column<Int>, optional). Where each segment starts in the column; the fold is then one value per segment. ## Outputs - `value`: the first folded element. - `values`: one element per segment (a single element without `starts`). - `picked`: for argmin and argmax, the chosen element's index.

# core.resample.curve (procNode) Redistribute the points of every curve evenly by arc length: a fixed number per curve, or as many as fit a spacing. Built from `core.arclength`, `core.points` (one row per new point, from the `expand` kernel over the per-curve counts), `core.sample_curve`, `core.interpolate`, and an exclusive `scan` for the new curves' starts. The result is curves again: `vertex.pt` runs through the new points in order and `primitive.vstart`, `vcount` and `closed` describe each curve; a curve's own attributes carry over. ## Inputs - `curve` (Curves). The curves resampled. - `count` (Number). Default `16`. Points per curve when `spacing` is 0. - `spacing` (Number). Default `0.0`. The distance between points; each curve takes as many as fit. 0 uses `count`. ## Outputs - `curve`: the resampled curves.

# core.sample.surface (procNode) Choose points on a surface, area-weighted and deterministic: the face and the barycentric place of each, as samples. Built from `core.owner`, `core.normals.face`, the `expand` kernel (each primitive fanned into triangles), `gather`, `math` operators for the triangle areas, an inclusive `scan` of the areas, `field.random` draws, the `search` kernel (the triangle each draw falls in) and `core.points`. The result is Points with `P`, `prim` (the primitive), `ia`, `ib`, `ic` (the three vertices of the triangle), `bary` (the weights of those vertices) and `N` (the primitive's normal). `core.interpolate` carries a geometry's attributes to such samples. ## Inputs - `geometry` (Geometry). The surface sampled. - `count` (Number). Default `256`. How many samples. - `seed` (Number). Default `1`. Which of the possible layouts this is. - `graphId` (String). Default `""`. The graph the draws are keyed to, so two graphs with one seed draw different places. - `nodeId` (String). Default `""`. The node the draws are keyed to. ## Outputs - `samples`: points with `P`, `N`, `bary`, `prim`, `ia`, `ib`, `ic`.

# core.sample_curve (procNode) Find the places along curves that arc-length positions name: for each row, the segment of its curve and the weights of the segment's two ends. Built from `core.arclength`, `core.owner`, an exclusive `scan` of the curves' lengths (each curve's start in one ascending run of distances), the `search` kernel over that run, `gather` and `math` operators. The result is the rows with `prim` (the curve), `ia`, `ib`, `ic` (the segment's start vertex, its end vertex, the end again), `bary` (weights 1 - w, w, 0), `P` (the position there), `tangent` and `t`. `core.interpolate` carries the curve's attributes to them. ## Inputs - `curve` (Curves). The curves sampled. - `owner` (Value). Default `0`. For each row, the curve it samples: a primitive number. - `t` (Value). Default `0.0`. For each row, how far along its curve: 0 at the start, 1 at the end. - `rows` (Points). The points that become the samples: one per row. ## Outputs - `samples`: the rows standing on the curves, with `P`, `tangent`, `t`, `prim`, `ia`, `ib`, `ic`, `bary`.

# core.scatter (procNode) Fold a column into the places an index names: every element sends its value to the element its index names, and each receiver folds what reached it. Three `scatter` kernel runs (`init`, `fold`, `finish`) over columns of the result's type. The same answer every run for the folds that do not depend on arrival order. ## Inputs - `values` (Column). The column sent. - `index` (Column<Int>). For each element, the place it is sent to; an index outside the result sends nowhere. - `size` (Number). Default `0`. How many places there are. - `fold` (one of add, mean, min, max, set). Default `"add"`. How values that meet fold: added up, averaged, the least, the greatest, or the one from the greatest source index. - `fill` (Value). What a place nothing reached holds; zero when left out. With a `fill` the answer is a Field over the places. ## Outputs - `value`: the folded column, `size` elements of the type of `values`.

# core.scratch (procNode) A run of one whole number, zero, for a binding a kernel mode does not read. A dispatch binds each buffer at one slot only, so every binding a mode leaves unread (the `starts` of an unsegmented scan or reduce, the `la` and `lb` of a jump that does not label pairs) takes a run of its own. Each call answers a new run. ## Inputs None. ## Outputs - `run`: a column of one Int, 0.

# core.select (procNode) Keep the elements of a geometry a mask picks and drop the rest, renumbering the links between points, vertices and primitives. Built from `math.ne` over the mask, `compact` (the kept elements and the inverse map), `core.owner`, `gather`, a segmented `reduce` (`segments = primitive.count`), `scatter`, `attribute.carry` for every class and `scan` for the new run starts. Keeping points drops every primitive that loses a vertex; keeping primitives keeps their vertices and, by default, the points those vertices read; `points` set to "all" keeps every point. ## Inputs - `geometry` (Geometry). The geometry to filter. - `class` (one of point, primitive). Default `"point"`. Which elements the mask is over. - `points` (one of used, all). Default `"used"`. For class "primitive": which points stay, the points the kept primitives use or every point. - `mask` (Value). Default `1`. A column or field over the class's elements: an element is kept where the value is not 0. ## Outputs - `geometry`: the kept elements with the links renumbered.

# core.spatial (procNode) A spatial index over a set of points: the bucket order and spans every neighbour query reads. Built from the `hash` kernel (the bucket of each point's cell), `sort` of those buckets and the `hash_starts` kernel (where each bucket's points lie in the sorted order). The point count is read back once; the bucket count is the least power of two at least the count and at least 16, worked out with `math.log` and `math.ceil`. Outputs `order`, `range`, `buckets` and `invCell`, which `hash_count`, `hash_gather` and `hash_nearest` read. ## Inputs - `points` (Geometry). The points indexed, by their `P`. - `cell` (Number). Default `1.0`. The side of a grid cell: queries reach about this far in one step, so a radius near it answers fastest. ## Outputs - `order`: the points ordered by bucket. - `range`: each bucket's span in `order`. - `buckets`: the bucket count. - `invCell`: one over the cell side.

# core.stitch (procNode) Join consecutive rings of points with quads, and optionally close the ends with caps: the surface of a tube, a sweep or a loft. Built from `attribute.carry` (the geometry's vertices and primitives followed by the new ones, which read index -1 and so carry zeros, sized by `size`), `math` operators for the quad and cap layout, and `gather` of the ring points. `rings` holds every ring end to end, `size` points each; a quad runs ring `r` point `j`, point `j + 1`, then the same two points of ring `r + 1`. With `closed`, the last point of a ring joins the first. A cap is one primitive running round a whole end ring: the first ring wound the other way, the last ring in its own order. The ring count is read back from `rings.count`. ## Inputs - `geometry` (Geometry). The geometry holding the ring points; the quads and caps are added to it. - `rings` (Column<Int>). The point numbers of every ring, one ring after another, `size` points each. - `size` (Number). Default `3`. How many points each ring holds. - `closed` (Bool). Default `true`. Whether each ring is a loop: the last point joins the first, so a ring of k points makes k quads to the next ring instead of k - 1. - `caps` (one of none, start, end, both). Default `"none"`. Which ends are closed by a primitive running round the end ring. ## Outputs - `geometry`: the geometry with the quads and caps added.

# core.weld (procNode) Merge the points of a geometry that stand within a distance of each other, joining the primitives that used them. Built from `core.pairs` (the points within the distance), `jump` in label mode folded until no label changes (every point takes the smallest point number of the points joined to it), `compact`, `scatter` with a mean fold for the merged positions (with `place` "first" the carried position stands), `attribute.carry` for every other attribute (a merged point takes the values of the lowest-numbered point of its group) and `gather` to renumber `vertex.pt`. With `match` set to \"position+normal\" two points merge only when their `N` normals differ by no more than `angle` degrees. Every pair within the distance ends in one group, so a chain of points each within the distance of the next merges whole. ## Inputs - `geometry` (Geometry). The geometry welded. - `distance` (Number). Default `0.0001`. Points closer than this merge. - `match` (one of position, position+normal). Default `"position"`. What has to agree: position alone, or position and the `N` point normal. - `angle` (Number). Default `1.0`. For "position+normal": how far apart two normals may be and still merge. - `place` (one of mean, first). Default `"mean"`. Where a merged point stands: at the mean of its group, or at the position of the lowest-numbered point of the group (the point `attribute.carry` takes the other attributes from). ## Outputs - `geometry`: the welded geometry.

# Nodebox (asset type) A nodebox is a namespace folder that groups related `.procNode/` children, the way a toolbox groups `.tool/` children. A node's name is its folder name inside its box: `points.nodebox/disc.procNode` is called `points.disc`, and nothing inside the node states that name. Moving or renaming a node is a VFS move that keeps its guid. ## Where it lives - Source: `<anywhere>/<family>.nodebox/`, usually inside a `.package`, an effect or a world's content. - Identity: `<family>` (the `.nodebox` suffix strips). - Folder shape (open child set): - `README.md`: what the family is for. Required. - `.metadata`: description and tags. Required. - `<node>.procNode/`: any number of nodes. ## How a graph reaches a node `g.<family>.<node>(args)` resolves the node by its asset identity: the box and the folder name together (`g.points.disc`), a path (`g["/zero/source/fx/ring.procNode"]`), `~` (the nearest enclosing package, effect or world root: `g["~/ring"]`) or a short name the asset system resolves (`g.disc`). A name that matches two nodes is an error naming both; a name that matches none is an error naming the closest nodes. Each call is recorded in the graph's reference table by the node's guid. ## How to create one ```luau asset.create("nodebox", "points", { folder = "fx" }) local box = asset.resolve("points.nodebox") asset.create("procNode", "disc", { into = box }) ``` ## Discovery - `asset.list("nodebox")`: every box. - `asset.inspect("points")`: the nodes in it and what each does. - `asset.list("procNode")`: every node, in or out of a box. ## In the Inspector Nodes: how many nodes the box holds, each node's full name and what it does, and a link to each.

# procNode: one reusable step of procedural generation A `.procNode` is a node authored as content: a folder whose `init.luau` is the node. It returns `proc.define(function(g) ... end)`, the same function-of-`g` form a `.procGraph` is written in, so a node is a small graph that other graphs call. Its `g:describe` text says what it makes and when to use it, its `g:input` declarations are what a call passes, and what it returns (or declares with `g:output`) is what the call gives back. ``` MyNode.procNode/ init.luau -- the node README.md -- what it produces, its inputs, its outputs .metadata -- description and tags ``` ## What a node states - **`g:describe(text)`**: what the node produces and when to use it. It is the text search, the node catalogue and the Inspector show. - **`g:input(name, default, opts)`**: one input of the node. The default types it (`Float`, `String`, `Bool`, `Vec3`, `Color`, `List<T>`, `Record`); `opts` adds `type` (for a default that does not state one, or none), `description`, `options`, `min`, `max` and `optional`. A call names inputs in a table, or passes them in declaration order. - **Outputs**: the returned table names them (`return { geometry = geometry }`), and `g:output(name, value)` declares one as the node builds. A node with one output answers that value to its caller; a node with several answers a record by output name; a node with none answers nothing. - **Written as literals.** What a node takes and gives is read from its source without running it, the way search and description read it here and the way ZeroMind reads it, so each declaration states its values as written: `g:describe` and each `g:input` once, at the top level of the function, with a literal name, default and options (a file constant holding a literal, or `asset.resolve("<identity>", "<type>")`, reads as one); outputs named by the table the function returns, or by `g:output`, the same names on every branch of a condition and never inside a loop. `asset.interface(node)` answers what the source declares, with each part it cannot read as a problem, and a push refuses a node with such a problem (`interface.unreadable`). - **The body** is the node's work: calls to other nodes, arithmetic over sockets, `for`, folds, steps and state, as the builder README (`proc.module/builder.module/README.md`) describes. A node that uses another node is recorded in the graph that calls it, so a node can be built from nodes. ## How a graph calls a node A node inside a `<family>.nodebox` is called by its box and folder name: `points.nodebox/disc.procNode` is `g.points.disc({ ... })`, and nothing inside the node states that name. A node is also reached by: - its path (`g["/zero/source/fx/ring.procNode"]`), - `~`, the nearest enclosing package, effect or world root (`g["~/ring"]`), - its guid, - a short name only one node answers to (`g.disc`). A name that matches two nodes and a name that matches none are errors that name the candidates. Each call is recorded in the calling graph by the node's guid, so the node travels with every graph that uses it, and a rename or a move keeps the reference. A `.procGraph` is called the same way and answers what it returns. ## Nodeboxes A nodebox is the family a node lives in: a namespace folder grouping related nodes (`points`, `mesh`, `field`, `terrain`). `nodebox.assetType` describes it. A node placed in a box takes the box's name as its prefix; a node outside any box is reached by path, `~` or guid. `asset.create("nodebox", family)` makes a box and `asset.create("procNode", name, { into = box })` makes a node in it. ## Finding nodes `asset.list("procNode")` lists every node. The `procgen` toolbox's `searchNodes` finds them by keyword and by meaning and lists them grouped by family, and its `describeNode` answers one node's inputs, their types and defaults, and its outputs. Both read what each node's source declares and run no node. The type's `indexing` recipe embeds a node's README and its source, so a search by meaning finds it by its description and by its inputs. ## Registration Every node the asset index lists is known to the procgen registry by what its source declares, read when it is asked for and read again when the source changes; nothing runs a node to list it. Its code loads the first time a build runs it. After that, the lifecycle hooks keep it current: `onChange` loads it again and hot-reloads on an edit, `onDelete` removes it. Editing `init.luau` cooks again every graph that reaches the node, and only the nodes downstream of the change do work. `init.luau` is compiled from its current source on each load, so a module it pulls in uses an absolute require (`require("@builtin::systems.procgen.proc")`). A graph that references a node which is not registered errors at load, naming the missing guid. A graph that reaches itself, directly or through other nodes, errors at cook. ## Content requirements `README.md` carries real text: what the node produces, its inputs and its outputs. `.metadata` carries a `description` (what the node computes and the value type it answers) and `tags` (the family, so search finds it). ## In the Inspector Operation: the node's id and what it does, its cost and caching when it declares them, and its inputs and outputs, from the procgen registry's schema for it. A node that did not register says so.

# assetType (asset type) The `assetType` is the **type of types** — the meta-type that every `<typename>.assetType/` folder is an instance of, including itself. A `<typename>.assetType/` folder declares a new asset type called `<typename>`: its on-disk shape, its identity rule, and the structural contract instances of the type must satisfy. This type is self-hosting. `assetType.assetType/` conforms to its own schema — a `type.yaml` plus a `README.md` — so the type system is defined in terms of itself rather than a hidden engine special-case (the same way a C compiler is written in C). Every asset in the engine, including each `.assetType` definition, now resolves to a registered assetType: a `.material` resolves to `material.assetType`, and `material.assetType` resolves to `assetType.assetType`, which resolves to itself. ## Why it exists Assets used to be mapped to their type *implicitly*, by matching the folder suffix against a name-keyed registry. That match carried no stored link: nothing on a `Foo.material` recorded *which* `material.assetType` it was written against, so two worlds shipping a same-named type could silently disagree. Making `assetType` a real, resolvable asset closes that gap — the link from an asset to its type is now an explicit reference pinned in the asset's `.refs` sidecar (`via: "asset_type"`), exactly like every other dependency. ## Where it lives - Source: `/zero/source/.../<typename>.assetType/` - Identity: `<typename>` (the `.assetType` suffix strips from the identity; the folder retains the suffix on disk). - Folder shape: - `type.yaml` — the structural spec the validator reads. **Required.** - `README.md` — type-level documentation. **Required.** - `about.yaml` — three short plain-language texts saying what the type is for (see "Say what your type is for" below). Every built-in type ships one. - `behavior.luau` — optional behavior/scaffolding module. - `template/` — optional canonical placeholder body the templater copies into a new asset of the type. - `<name>.module/` — optional shared code the type ships to **every instance** of it, conventionally `shared.module/` (see below). ## Shared code its instances reach (`asset.containing` + `.modules`) A type ships code every instance of it uses by declaring the modules in its own `behavior.luau`, as a map of tracked `require`s: ```luau -- inside <typename>.assetType/behavior.luau M.modules = { shared = require(".shared") } -- the sibling shared.module/ ``` An instance reaches it with one location-independent line: ```luau -- inside any foo.<typename>/init.luau local api = asset.containing(__FILE__).modules.shared ``` `__FILE__` is the chunk's own VFS path; `asset.containing` resolves the calling asset, and `.modules.<name>` follows the instance's pinned `typeRef` (the type's **guid**, recorded in the instance's `.refs` as `via = "asset_type"`) to the module its type declares. Because resolution follows that link rather than a category name, the same line in an instance of a different type resolves to that type's module, and identically-named modules in two types never collide. `asset.typeRef(target)` reads that guid for any target; `asset.resolve(asset.typeRef(target))` gives the full `AssetRef<assetType>`. See `assetTypes/README.md` § "Shared code: type-owned modules" for the full mechanism. ## How to create one Authoring a new asset type is just creating a `<typename>.assetType/` folder under `/zero/source/`. The engine registers `<typename>` as a category **the moment the folder is written** — no engine restart, no Rust change, and it works for built-in (`@builtin/assetTypes/`) and user-defined types identically. Once `<typename>` is registered, `<name>.<typename>/` folders are recognised as assets of that type and resolve their `asset_type` link back to this definition. Creating a `<name>.<typename>/` folder *before* its `<typename>.assetType/` exists fails fast: the suffix has no registered type, so the folder can't be a valid asset. Author the type first. ## Say what your type is for (`about.yaml`) Every type carries a small `about.yaml` beside its `type.yaml`, and the README you write for the type documents how to author an asset of it. Both are required, and both are meant to be written as you make the type, while you know what it is for. `about.yaml` answers three questions in plain words, one key each: ```yaml intent: "Sets the typeface of the text in your game: UI, labels, signs and 3D lettering." function: "A font, from a TTF, OTF or WOFF file, made available to all of Zero's text, including 3D text." usage: "You choose it by name for your UI or your text, and the text appears in that typeface." ``` - **`intent`** is what the type is for in someone's game. Name the whole range of things it covers, in the words a game maker would use for them. - **`function`** is how it works today: what an asset of the type is made of and what the engine does with it. - **`usage`** is what a person or an agent does with one: how they pick it, place it, call it, or hand it to something else. A few habits keep it useful. Write about the type as a whole, so the text holds for every asset of it, and leave out any one asset's name. Say what the type does right now. Stay with words a game maker would say, and mention a file name or a call only where a game maker would know it. The limits are in bytes: `intent` 800, `function` 1500, `usage` 1200. Each is generous, and a few sentences usually say it. Why bother: agents working in a world read these three texts to learn what your type is for, so they reach for it when it fits and use it the way you meant. People searching find the type by what they want to make, and the three texts let them tell at a glance whether it is the one they need. `asset.create("assetType", name)` scaffolds the file with all three keys, and a README whose first paragraph is a `[[describe]]` note. Each value starts with `[[describe]]` followed by a note on what to write; replace the whole value with your own words. A value or a README line that still starts with `[[describe]]` counts as not written yet, which the push's check of each asset it carries against its type reports, naming the file. A type you leave as it was is not asked, so older types stand. Many types at once, or one you would rather not write by hand: `services describe` lists the types that lack these texts and what filling them costs, and `{ mode = "all" }` writes them into the same files, where you edit them like anything else you wrote. Where the texts show up: `asset.inspect("<typename>", "assetType")` returns them as `detail.about`, `assetTypeRef:getAbout()` returns them as a table with the keys `intent`, `function` and `usage`, the type's `types/<typename>` guide page ends with an "About this type" section holding them, and the Inspector's Type section lists them at the top. The guide page is this README plus that section, so a README that explains the type well and an `about.yaml` that says what it is for read well together. ## Ask your assets to say what they are A type can ask each of its assets to carry a description: a file, written by the author or generated, that says what that asset is and what it is for. The people and agents who find an asset read it to decide whether it fits, and the author knows what it is for at the moment of making it. **1. Declare the file with a `described` check.** This is the whole requirement: ```yaml files: required: - path: "README.md" # any file name works kind: "file" content: - { check: "described", message: "Say what this widget is for and where it goes." } ``` With that in place: - An asset whose file is missing, empty, or still has a line starting with `[[describe]]` does not meet the type's requirements. `asset.validate` names it, `zm status` and `world.publishBlockers()` list it, and a push that carries it is refused with `message`. - `services describe` finds it (`mode = "find"` lists it and the price) and can write the description for it (`mode = "all"`). It writes only this file. For a YAML file that holds several texts, name the keys and their limits in bytes, the way this type does for `about.yaml`: ```yaml content: - check: "described" keys: - { key: "intent", max_bytes: 800 } - { key: "usage", max_bytes: 1200 } message: "Write intent and usage." ``` `headings` names sections a Markdown file must have. `assetTypes/README.md` has the full check. **2. Optionally, steer what gets generated with a `describe:` block:** ```yaml describe: guidance: "Say what the widget shows, what input it reacts to, and where it fits in a UI." examples: - "<identity of an asset of this type whose description reads well>" ``` `guidance` says what a description of your type covers, and `examples` names assets whose descriptions show the shape you want. Without the block, generation still works from the general describing guide and the check's `message`. An example is an asset of your type in the library whose description is a true, written one, never a scaffold's placeholder, and never the asset being described. When the library has none, leave `examples` empty rather than name one that is not. A type whose assets the model cannot perceive (a sound it cannot hear, a motion it cannot see) says so in `guidance`: the description comes only from what the asset's own files state, such as its name and the `.metadata` where a generation service records the prompt that made it, and when they state nothing the model answers `cannot` with that reason. `services describe` then fails that one asset with the reason and leaves its file as it was. **3. Start the file unwritten in your template.** Put a heading and one line that starts with `[[describe]]` and a short note on what to write, in `template/<file>`, so a new asset starts unwritten rather than with text that only looks written. Do not put example content in it: every new asset carries the template verbatim, and the same text on many assets makes them impossible to tell apart in search. Types whose assets say what they are through their own content (a mesh, a texture, a sound) leave this out: declare nothing and nothing is asked. ## The `behavior.luau` contract `behavior.luau` is the type's code. It returns ONE table, and the keys below are the ones the framework reads off it for EVERY type — the surface you get by declaring them. Anything else on the table is your own: reachable by name through `require("@builtin::assetTypes.assetType.shared.ref").loadTypeModule("<typename>")` for a system that knows your type (`computeShader` publishes `dispatchKey` that way), and never called by the framework. ```luau local M = {} M.ref = { ... } -- methods on every AssetRef of this type M.modules = { ... } -- shared code the instances reach M.global = {} -- reserved key; ship the empty table function M.onCreate(name, opts) ... end return M ``` ### The tables | Key | Shape | What the engine does with it | |-----|-------|------------------------------| | `M.ref` | `{ [name] = function(self, ...) }` | Every function becomes a method on every `AssetRef` of this type: `ref:name(...)`, with `self` the ref. This is how a type gives its instances an API. Two names in here are contracted — see below. | | `M.modules` | `{ [name] = require(".sibling") }` | Shared code the type's instances reach through `asset.containing(__FILE__).modules.<name>`, resolved by the instance's pinned `typeRef` guid. See the section above. | | `M.refShapes` | `{ [method] = "TypeName" }` | Declares the result type of a `M.ref` method so the LSP can check what a call site does with it. See the `M.refShapes` section below. | | `M.events` | an events schema | The events an ASSET of this type fires, declared the way a component declares its own. Readers subscribe through `ref.events.<name>:connect(...)`; firing authority stays with the type. Keyed by the asset's guid, so every resolver of the same asset shares the signals and a re-resolved ref re-attaches to subscriptions already there. | | `M.namePattern` | a Lua pattern string | The name shape `asset.create` enforces for instances of this type, replacing the default `^[A-Za-z][A-Za-z0-9_]*$`. | | `M.global` | `{}` | Reserved. Ship the empty table. | ### The lifecycle hooks Each is optional; a type that omits one costs nothing. The engine calls them: | Hook | Signature | When it fires | |------|-----------|---------------| | `M.onCreate` | `(name, opts) -> { [filename] = contents }` | On `asset.create("<type>", name, opts)`. Returns the files that scaffold the new instance, as a map of relative path to contents; the framework writes them. The `opts` type annotation is the schema `asset.create` validates the caller's arguments against, so annotate it. | | `M.onReplace` | `(dest, files) -> { [filename] = contents }` | On an `asset.create` that writes over an asset already at `dest`, after `onCreate`. Receives the files `onCreate` produced and returns the files to write, so a type that re-derives its content (a rig re-imported from its source file) can carry what an author added to the asset it replaces. Optional. | | `M.onRegister` | `(self)` | Once per instance, the first time it registers: on `engine.onWorldLoaded` for instances already in the world, immediately on a live `asset.create`, and when an instance arrives after that sweep (installed, pulled, or synced from a peer). Guarded by the instance's path, so a double trigger never double-registers. An instance that leaves the runtime releases the guard, so one arriving at the same path again registers. This is what makes "write an asset into the world and it takes effect live" work for content that registers into a runtime registry. The `@builtin` library is excluded from the sweep. | | `M.onChange` | `(ref, change)` | On every VFS write to a file INSIDE one of this type's instances. `change` is `{ path, asset, type, kind, origin }`: `kind` is `"edited"` or `"seeded"`, `origin` is `"local"` or `"remote"` (an importer runs on the originator only). **Filter on `change.path`**: the hook fires for any file under the folder, so act on the one you care about. It runs as its own task and may wait on what it reads: a `vfs.read` of bytes only the blob store holds (a binary file on the web build) fetches them. The writes to one asset reach the hook in the order they were made, each once the hook before it has finished. A re-entrancy guard suppresses writes back into the same asset routed inline from the hook, and a write the hook makes is routed on a later frame like any other, so the hook must be convergent on its own: diff the meaningful state and short-circuit while your own regeneration is in flight. | | `M.onDelete` | `(ref)` | When an instance of this type leaves the runtime: it is deleted, or the engine swaps away from the world binding that held it. Its files are gone from `/zero/source` by then. A removal routed while the instance's `onChange` is waiting reaches `onDelete` once that hook, and every write queued behind it, has finished. On a swap the instance still exists in the world it belongs to, and a VFS write the hook makes reaches the world now bound. | | `M.validate` | `(assetRef) -> { { code, message, severity? } }` | On `asset.validate`, after the structural `type.yaml` check, for the type's own SEMANTIC validation. `severity` defaults to `"error"`; error-severity problems flip `ok` to false, warnings do not. A hook that raises or returns a non-table is itself reported as a `validate.hook_failed` error. `world.push` runs this per user asset, so declaring it enforces your type's rules at publish time with no further wiring. | ### The two contracted `M.ref` names Most `M.ref` methods are your type's own surface: name them what you like, return what you like. Two are read by the engine and mean the same thing for every type, so their shape is fixed: - **`instantiate(self, target?, opts?) -> (root, idMap)`** — makes an instance part of the scene. Defining it is the whole opt-in: `ref:canInstantiate()` is true exactly when it exists. Its **return is a contract** — see the next section. - **`inspect(self) -> detail`** — the type-specific half of `asset.inspect`. See its section below. ### Names a type cannot shadow Some keys resolve on every `AssetRef` before per-type dispatch, so an `M.ref` entry of the same name is never reached: `canInstantiate`, `getSource` / `getBytes` / `getText`, `exists`, `deps`, `meta`, `runtime`, `events`, `modules`, `typeRef`, and the residency flags `has_backing_asset`, `has_runtime_changes`, `cpu_resident`, `gpu_resident`. These are the behaviours every asset must expose identically, which is why they win. ### Reloading A `behavior.luau` edit ripples to existing refs with no restart: dispatch reads `mod.ref` fresh each time and `require`'s cache is re-run in place. A type whose folder appears at runtime is picked up on the next dispatch — negative results are not cached either. ## The names your type's assets hold (`references:`) An asset that names another asset by a string depends on it: the named asset travels with it into a pack or a pull, and a name nothing answers to is an unresolved dependency `worldValidation` reports and the push gate refuses. The engine reads `require(...)` and the asset lookups on its own; a name your type's format or API carries anywhere else is one you declare, in `type.yaml`: ```yaml references: # A top-level key of this type's own files that holds a name (or a table of them). keys: - { key: "shader", type: "shader" } # A call's argument, counting from 1, wherever the call is written. args: - { call: "g:node", position: 2, type: "procNode" } # A field of the options table a call takes. fields: - { call: "fx.beam", field: "material", type: "material" } ``` `type` is the category the name resolves in, one of `asset.categories()`. An argument declared once per category, at the same `call` and `position`, takes the name from whichever category answers. A key or a field holds one category: declared again with another `type`, it takes the later one. The block is declared as the type registers, when the library or the world holding it is laid into the VFS, so every reference table reads it whatever script has or has not run. `asset.declareReferenceKey`, `asset.declareReferenceArg` and `asset.declareReferenceField` declare the same things from a script, for a surface that is no type's. ## What search does with your type (`indexing:`) A type declares what search embeds for its instances. **This is not optional and there is no useful default**: ZeroMind runs your declaration and adds nothing of its own, so anything you do not point at is absent from the index — silently, and for every instance of the type forever. Twenty types once shipped with no `indexing:` block and every instance of them was unfindable. A type whose instances are never searchable (a run record, a log) says so with `indexing: none`; every other type declares a recipe. A type without an `about.yaml` beside its `type.yaml` refuses every push that carries it, whether or not the push edited the type. Texts in it that are not written yet follow the rule every `described` file follows: they refuse the push that edits, stages or commits the type. Two words carry the whole thing, and they are the same two the search tool exposes: - **`identity`** — what an instance IS. For anything you can look at, that is the picture (`content:` + `modality: image`, matched directly by a text query). For everything else it is the authored text that says what it is. - **`capability`** — what it DOES and how it is made. Code, settings, the model-written summary of them. A type with no behaviour has no `capability` entry. A type with nothing to look at has no image. Leaving a slot empty is a statement; filling it with whatever happens to be lying around is not. The one you have to decide when authoring a type is: *for an instance of this, what is the thing a person would recognise it by, and what is the thing it does?* A texture answers "the image" and "its compression settings". A module answers "its README" and "its code". Write those two answers into `indexing:` and the rest follows. Three specifics worth knowing before you write one: - **`derive` is instructed by this type's own `README.md`.** A model reads an instance's source and writes a description; what it embeds is the description, not the source. It follows your README to know what it is looking at, so a type whose README says what its instances are gets good derivations for free. There is no prompt to name. - **`derive` loses detail.** It keeps the main technique and drops secondary ones. If the source is code you want searchable by its own vocabulary, declare the same files a second time as `capability` with `extractor: verbatim`. Two entries, same role, different failure modes. - **Never `source: { field: name }`.** A filename is one or two words with no usable embedding, and a corpus indexed that way answers "language runtime" with `say_runtime_2.soundClip`. `facets:` is the second stage: a `file:` embedded whole (`.metadata`, so keys nobody declared still get indexed) plus computed keys that state a value for every instance including `false` — the raw file can imply "not rigged" and can never say it. The full schema, every extractor and the facet sources are in [`assetTypes/README.md`](../README.md); the scaffolded block with inline guidance is in [`template/type.yaml`](template/type.yaml). ## A container whose contents work together (`system: true`) A type that is a container can say its contents are one working whole by declaring `system: true` at the top level of its `type.yaml`. `package` declares it: the components, modules, scenes and tools a package ships are parts of one system. The declaration is plain data, read from the decoded `type.yaml` (`require("@builtin::assetTypes.assetType.shared.declaration").of("package").system`), and a type that leaves it out is an ordinary type. ## What your type looks like (`preview:`) A type declares how its instances are pictured, and the engine makes the picture when something needs it: staging an instance whose `preview.png` is missing or pictures content it no longer holds queues a render, a view that shows the instance asks for one, and `ref:preview()` renders one on demand. An edit renders nothing on its own. Each `preview.png` records the content it pictured, which is how a stale one is told from a current one. The preview studio owns the light, the backdrop, the framing and the camera, and nothing in the world reaches it, so an instance pictures the same in every world. Declare one of four recipes: | `kind` | The picture is | Your type provides | |---|---|---| | `instantiate` | the asset stood in the studio through its own `instantiate` | `ref.instantiate` | | `image` | a file the instance holds, fitted to the frame, nothing rendered | `source.files`, the candidate files in order | | `surface` | the asset painted on a builtin mesh | `mesh`, and `ref.previewMaterial(self) -> { material }` | | `custom` | whatever `ref.preview(self, opts)` returns | `ref.preview` | ```yaml preview: kind: surface mesh: sphere ``` A scene-instantiable type that declares nothing still answers `ref:preview()` through its `instantiate`, but persists no picture: the declaration is what makes the engine keep one. List `preview.png` among the type's files so an instance may hold it. The picture is findable only when `indexing.content` names it. The two are separate statements, and neither is derived from the other: ```yaml indexing: content: - role: identity modality: image source: { file: "preview.png" } ``` `@builtin::assetTypes.assetType.shared.previewRecipe` reads the declaration; the scaffolded block with inline guidance is in [`template/type.yaml`](template/type.yaml). ## Typing a result from the instance (`M.refShapes`) Every method on `M.ref` is checked against the type its `--!return` names, and every asset of the type gets the same one. That is right for most methods and wrong for the ones whose result is shaped by the ASSET: a method answering one entry per child folder, per row of a config, per binding an input map declares. The widest true annotation for those is `{ [string]: Thing }`, and an indexer accepts every key — so a caller's typo reads as valid and nothing reports. `M.refShapes` lets the type state the result per instance. Each entry is `function(self) -> (typeExpression, source?)`: a Luau type expression for THIS asset, and the module whose type vocabulary the expression uses. Read the asset; never run it — stating a type must not take effect. ```lua -- inputMap.assetType/behavior.luau — the shipped example. -- `activate()` hands back one handle per control the map declares. M.refShapes = { activate = function(self): (string, string) local names = {} for _, control in ipairs(M.ref.controls(self)) do table.insert(names, control.name .. ": Handle") end if #names == 0 then return "", "" end return "{ " .. table.concat(names, ", ") .. " }", "@builtin::modules.zinput.scheme" end, } ``` With it, `map.jump:onPressed(fn)` resolves and `map.noexisting` is reported with the map's real controls. Without it, both pass silently. ### What the call site has to say A per-instance type is matched by the asset's IDENTITY, so it applies only where the reference the method is called on says WHICH asset. Two spellings do: ```lua -- a component field, whose declared default names the asset public = { map = Field.assetRef("inputMap", "@builtin::inputMaps.default", Sync) } local controls = public.map:activate() -- typed for THAT map -- an annotation, naming category and identity local m: AssetRef<"inputMap", "@builtin::inputMaps.default"> ``` `asset.resolve("<identity>", "<category>")` carries the CATEGORY, so the methods the category defines are checked on the result — but not which asset it found, so a per-instance result keeps the category's declared return. A reference that names no asset (`asset.resolve(someVariable)`, a value passed in as a parameter) carries neither, and calls on it are unchecked. That is the same rule everywhere: the checker states what the code states, and a name computed at runtime states nothing. ### The result is a value, not a binding The type belongs to the expression, so it travels the way any inferred type travels. Indexing the call's result is checked; stashing it in a module local and indexing it from another function is not, because the local's declared type is what carries across — and `any` (or no annotation) carries nothing: ```lua -- checked: `d.greting` is reported function awake() local d = public.dialogue:lines() d.greeting:say() end -- NOT checked: `lines` is a module local typed `any` local lines: any = nil function awake() lines = public.dialogue:lines() end function start() lines.greting:say() end ``` Bind what you need at the call site and the names stay checked in both places — the asset-derived type at the boundary, ordinary scoping after it: ```lua local lineGreeting = nil function awake() local d = public.dialogue:lines() lineGreeting = d.greeting -- `d.greting` is reported here end function start() lineGreeting:say() end ``` ### When nothing is reported and you expected something From a call site, a type that is correct and a type that was never published look the same: no diagnostic either way. `require("@builtin::assetTypes.assetType.shared.refShapes").published()` answers which it is. It returns two maps — the category surfaces, and the per-asset results keyed by identity and then by method: ```lua local shapes = require("@builtin::assetTypes.assetType.shared.refShapes").published() shapes.categories.dialogue --> "{ lines: () -> any, lineNames: () -> { string } }" shapes.returns.Shopkeeper.lines --> "{ browsing: Line, farewell: Line, greeting: Line, wares: Line }" ``` An identity absent from `returns` was never published for, which is a different thing from published-and-correct — and the reason to look here rather than at the call site. The answers are recomputed when an instance is written, so a control added to a map reaches the checker with no restart. Only types that declare `refShapes` are read per instance, and at most 64 assets of one type are — past that the type keeps its declared return and the engine log names what was dropped. ## The instantiate hook (`M.ref.instantiate`) — a contracted return A type opts into becoming part of the scene by defining `instantiate` on its `ref` table. That is the whole opt-in: `ref:canInstantiate()` is true exactly when the hook exists, so consumers offer a scene path — an `Asset.source` field, a viewport drop, a tool argument — by CAPABILITY rather than by a list of type names. Unlike `inspect`, this hook's **return is a contract**. A caller writes one piece of code against every instantiable type, so what comes back cannot vary by type: ```lua -- behavior.luau local Instantiable = require("@builtin::assetTypes.assetType.shared.instantiable") local M = {} M.ref = { instantiate = function(self, target, opts) local root = Instantiable.root(self, target, opts) -- IN: the base opts -- ... compose whatever this type is, under `root`, NOW ... return Instantiable.result(self, root, idMap) -- OUT: the contract end, } return M ``` **IN.** `target` is an owning entity ref: the instance lands under (or, for a hierarchy type, onto) that owner. With no target the type spawns a fresh root. `position`, `rotation`, `scale`, `name` and `temporary` mean the same for every type — `Instantiable.root` applies them to a root you mint, `Instantiable.place` to one you adopt, so you never re-read the spec. Honour more opts of your own if your type needs them, and document them in the hook's `--!arg` docs. **OUT.** Return `(root, idMap)` through `Instantiable.result`: - **`root`** — the composed root, as an `EntityRef`. Composition is **synchronous**: everything your type builds is live when you return, so the caller can parent to it and read its components in the same statement. Do not defer the work to a component's `awake` and return an empty shell — a root that is not live is refused. - **`idMap`** — the `originalId -> runtimeId` map naming what you spawned, or nil for a type with no addressable children (`result` normalises it to `{}`). **A caller never receives nil.** A component that re-composes your asset on every load keeps this map and passes it back in, which is how a cross-entity reference into the composition survives a reload. `AssetRef` runs every `instantiate` through `result` on the way out whether or not your type called it, so returning something else fails at your own call rather than handing a caller a nil root. Calling it yourself is still how you say what you return, and running it twice changes nothing. `@builtin::assetTypes.assetType.shared.instantiable`'s README is the full reference for both halves. ## The inspect hook (`M.ref.inspect`) `asset.inspect(ref)` resolves `ref`, builds a common envelope shared by every asset (`identity`, `name`, `guid`, `source`, `typeName`, `typeDefinitionPath`, `scope`, `origin`, `description`, `tags`), then calls the resolved type's own inspect hook — `M.ref.inspect(self)` on `behavior.luau` — for the type-specific `detail`. The hook returns *only* `detail`; the framework fills in everything else: ```lua -- behavior.luau local M = {} M.ref = { inspect = function(self) -- self.path is the asset's own folder. Parse the asset's OWN -- files — source text, a native payload header, its `.metadata` -- — never runtime state (a live component instance, a GPU -- upload, a compiled schema): inspect must work on an asset that -- hasn't been compiled, uploaded, or registered yet. return { -- type-specific fields, whatever this type wants to surface } end, } return M ``` A type that omits `M.ref.inspect` yields the generic record: the envelope alone, `detail = nil`. That's a valid, working state — not an error — but it means agents calling `asset.inspect` / `tools.use("assets","describe", ...)` on an instance of the type see only identity and scope, none of what makes an instance of it meaningful. Declaring the hook is what makes a type's instances inspectable for what they actually are. A hook that raises leaves `detail = nil` and sets `record.warning` to the error text — `asset.inspect` itself never raises for a resolved ref. ## Discovery - `asset.list("assetType")` — every registered asset type. - `asset.inspect("<typename>")` — the type's identity, source path, and this README, plus its `about.yaml` texts as `detail.about`. - `asset.resolve("<typename>", "assetType")` — the `<typename>.assetType` asset itself (used by the validator to find the type's `type.yaml`). ## Related - `assetTypes/README.md` — the full `type.yaml` schema and validator rules. - `@builtin::assetTypes.assetType.shared.instantiable` — the instantiation contract's shared implementation, both halves. - Every other `*.assetType/` here — the concrete types built on this meta-type. ## The Inspector a type ships Every type names the file its Inspector sections come from with `inspector: { type: "inspector.luau" }` in its type.yaml. `asset.create("assetType", name)` scaffolds the block and an `inspector.luau` whose Contents section lists an asset's files, built from `ctx.parts`. `asset.validate` on a type that names none reports `assetType.inspector_required` (an error for a `@builtin` type the engine's library authors; a warning for a world's own, and for one the library carries by reference, which the world that published it answers for), and one whose file does not load `assetType.inspector_invalid`. ## In the Inspector Type: what the type.yaml declares (suffix, container, primary files, the settings and inspector blocks), whether the type ships a behavior, how many instances it has, and **Open** for its files. Schema: the settings every instance carries, as read-only typed controls at their defaults (a type whose schema is per instance says where it is declared). Instances: a link to each of the first 20 assets of the type, and how many there are when there are more.

# gather Builds a column from another column and a run of indices: element `i` of the result is element `index[i]` of `src`. An index below 0 or past the end of `src` gives zeros. The element type is the `T` specialization (`f32`, `i32`, and two to four lanes of either); a three-lane column is read and written tightly packed, twelve bytes an element. Dispatch over `n`, the number of indices. Exact: each result element has one writer. Over a live count (`COUNT=device`, see the abi README) `n` is the capacity and the first `domain_count` slots are live: a slot at or past it holds zeros. It binds 4 storage buffers (3 in the plain variant), and `dst` holds `n` elements.

# field.index The element number, counted from 0. Unwired it is an Int field over whatever reads it (`fieldc.leaves.elementId`: the number of the element being written). With a `domain` it is an Int column of 0 to n - 1, one per element of the domain.

# math.where (procNode) Choose between two values by a condition: `a` where `cond` is not 0, `b` where it is. The `where` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.

# sort A stable radix sort of a column's keys into a permutation: place `s` of `perm` holds the index of the element that sorts `s`-th, so a gather by `perm` puts any column in key order. | Specialize | Options | Meaning | |------------|---------|---------| | `KEY` | `f32`, `i32` | the scalar a key holds | Elements with equal keys keep their run order, in both directions (`params.descending` 1 sorts from the greatest key down), and `-0` and `+0` are one key. The sort works 4 bits of the key at a time from the least significant up, and a pass whose digit is the same in every key is skipped, so a run of keys inside a narrow range takes fewer passes. `work` is the sort's second permutation; its contents after a dispatch are not an answer. The dispatch size `n` is the number of keys. One workgroup of 128 works the whole run; the other workgroups of a larger dispatch return. Exact: the sort is a function of the keys and their order, so the same keys give the same permutation on every dispatch. Over a live count (`COUNT=device`, see the abi README) `n` is the capacity and the first `domain_count` keys are live: they are sorted, and a slot at or past the live count holds its own index in `perm`. A live count of 0 sorts nothing and `perm` is the identity. It binds 4 storage buffers (3 in the plain variant).

# expand Turns a count per element into runs. Element `j` takes `counts[j]` slots, in element order; slot `s` of the result holds `owner[s]`, the element it belongs to, and `local_index[s]`, its place within that element's run. `offsets` is the exclusive prefix sum of `counts` (what the `scan` kernel makes of it), so every slot finds its element by a binary search and has one writer. `owner` is an appended output: its live count is the sum of the counts, up to the capacity the dispatch was given. Slots at and past the live count hold -1. An element with a count of zero has no slot; a column of all zeros gives a live count of zero. Dispatch over `n`, the capacity of the result. Exact. Over a live count (`COUNT=device`, see the abi README) the elements are the first `domain_count` of `counts` and `offsets`, so they can be held in runs larger than their live count, and the counter of `owner` states the sum of their counts as it is, above the capacity too: the first `n` slots are written and the sum minus `n` is how many did not fit. A node that states `n` as a bound checks the count against it. The plain variant clamps the count to `n`. It binds 6 storage buffers (5 in the plain variant).

# scan The prefix fold of a run of elements, whole or per segment: running sums, running least and greatest, running products. (The running product of 4x4 matrices is `scan_mat4`.) | Specialize | Options | Meaning | |------------|---------|---------| | `T` | `f32`, `i32`, `vec2` to `vec4` of either | the element; a vector scans lane by lane | | `OP` | `add`, `min`, `max`, `mul` | the operator | `params.exclusive` picks the fold of the elements before each one or the fold up to and including it. The first element of a group has nothing before it: an exclusive scan holds 0 there for `add`, 1 for `mul`, and the element itself for `min` and `max`. `total` holds the fold of each group, 0 for an empty group. A segmented scan (`params.segments` above 0, the number of segments) restarts at each start in `starts`; an unsegmented one binds any one-word run there. One workgroup scans one group at a time, a tile of 128 elements at a time, with the fold of everything before a tile carried into the next. The dispatch size `n` is the number of elements; any workgroup count from 1 up scans every group. Exact: the order of combination is fixed, so the same run gives the same bits on every dispatch, and an integer scan is the exact integer answer. Over a live count (`COUNT=device`, see the abi README) `n` is the capacity and the first `domain_count` elements are the run. Every slot of `dst` at or past it holds the total of the last group (the whole run, or the last segment; 0 for an empty one), which is the scan of the run padded with the operator's identity. An `i32` scan's `total` is a count another kernel takes as its domain (`{ count = total, capacity = ... }`). It binds 5 storage buffers (4 in the plain variant).

# proc Code-authored, graph-backed procedural generation for the Zero engine. A graph is one function of `g`: `proc.define(function(g) ... end)`. Nodes are called by family and name (`g.<family>.<name>({ ... })`), inputs are declared with `g:input(name, default, opts)`, the returned table is the graph's outputs, and `io.output` is how the graph stands in the world. `builder.module/README.md` holds every rule of that form. This module owns the whole procedural model: the graph builder + data model, the operation registry, the type system, the lazy cached evaluator, deterministic scoped hashing, and the node-family op implementations. Authored `.procGraph` graphs are persisted via `procGraph.assetType`; the `procgen.preview` / `procgen.spawn` operations live in `procgen.toolbox` and are invoked as tools: `use_tool` from an agent, or `tools.use("procgen", "preview", args)` from a script. Generated meshes/materials/textures/bundles are persisted through their own `.assetType`. An op family can also come from outside this package: a `.procPack` asset registers its ops in the same registry, called as `g.op.<id>(...)` exactly like the ones shipped here (`proc.registerPack(name, ops)` is what it registers through, and what a test or a tool calls to hold a family for the life of one VM). `terrain.*` is one such pack, shipped in `terrainSystem.package/procPacks/` and covering a whole landscape; `guides { path = "systems/terrainSystem/documentation/terrain" }` is its guide. To find out what the registry holds, use the `procgen` toolbox: `searchNodes` searches it and `describeNode` describes one node or op. `proc.search_ops(query)` and `proc.schema(id)` are the same answers in-process, for a graph builder looking something up while it runs.

# math.min (procNode) The lesser of two values, element by element. The `min` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.

# math.length (procNode) The length of a vector: a number per element, from the vector's components. The `length` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.

# reduce Folds a run of elements to one element per group: the sum, least, greatest, mean, count, or the index of the least or greatest, of the whole run or of each segment of it. | Specialize | Options | Meaning | |------------|---------|---------| | `T` | `f32`, `i32`, `vec2` to `vec4` of either | the element; a vector folds lane by lane | | `FOLD` | `add`, `min`, `max`, `mean`, `count`, `argmin`, `argmax` | the fold | The dispatch size `n` is the number of elements. One workgroup folds one group at a time, so a segmented fold runs its segments side by side and an unsegmented one is a single group; any workgroup count from 1 up folds every group. `params.segments` above 0 makes `starts` partition the run into that many segments: it holds where each segment begins (a segment ends where the next begins, the last at `n`), and `dst` holds one element per segment. With `segments` 0 the whole run is one group, `starts` is any one-word run, and `dst` holds one element. An empty group answers 0 for every fold. `argmin` and `argmax` write the lowest index among equal elements to `picked` (for a vector element, the element that beats the best before it in every lane); every other fold writes -1 there. The mean of an integer run is the integer quotient. The bounds of a run are its `min` and its `max`. Exact: every group folds its elements in a fixed order and combines the 256 partial results in a fixed tree, so the same run gives the same bits on every dispatch, and an integer fold is the exact integer answer.

# attribute.promote Move a named attribute from one class of elements to another: point, vertex, primitive, detail or edge, folding the values that meet with sum, mean, min or max. Built from the `gather`, `scatter` and `reduce` kernels and `core.owner`; only the route `from` to `to` names cooks: - point to vertex: gather at `vertex.pt`. - vertex to point: scatter fold at `vertex.pt`. - vertex to primitive: reduce over each primitive's run, `segments = primitive.count`. - primitive to vertex: gather at the vertex's owner. - point to primitive and primitive to point: through the vertices. - detail to a class: gather of the one value; a class to detail: reduce of the whole column (`segments = 0`). - point to edge: the fold of the two end points over `core.edges`. - edge to point: the edge class's column scattered to both end points of every edge and folded there; a point no edge reaches holds 0. The same class is the attribute unchanged. A route that does not exist refuses the build by name. ## Inputs - `geometry` (Geometry). The geometry holding the attribute. - `name` (String). Default `""`. The attribute to promote. - `from` (one of point, vertex, primitive, detail, edge). Default `"point"`. The class the attribute lives on. - `to` (one of point, vertex, primitive, detail, edge). The class the attribute is moved to; every caller states it. - `op` (one of sum, mean, min, max). Default `"mean"`. How values that meet on one element combine: added up, averaged, the least or the greatest. - `as` (String). Default `""`. The name written on the target class; empty keeps `name`. ## Outputs - `geometry`: the geometry with the promoted column written on the target class under `as` (or `name`).

# loops_cut Finds where each ring and chain of linked edges starts and ends. Stage 0 marks the first edge of every list (a chain's head, a ring's smallest edge); stage 1 makes the edge before each first edge the end of its list. The lists that result are what `jump` ranks. See `loops` for the whole sequence. Over a live count (`COUNT=device`, see the abi README) the edges are the first `domain_count` slots of a capacity `n`, and the `n` param is not read. A slot past the live edges is no head (`head` 0) and ends its own list (`cut` is the slot itself). It binds 7 storage buffers (6 in the plain variant).

# jump One round of pointer jumping over a run of links, three ways: - `rank` (MODE rank): list ranking. Repeated rounds give each element its root and its distance to it, for chains and trees. Both live in the double-buffered `parent`/`parent_out` and `value`/`value_out` pairs; the caller swaps them between rounds. - `min` (MODE min): doubling of the smallest label within reach. After ceil(log2 n) rounds, every element on a cycle holds the cycle's smallest label. - `label` (MODE label): label propagation over pairs, in place. Iterated to `changed` = 0 it labels each connected set of elements with its smallest label. `changed` counts what the round altered; the caller zeroes it before a round and reads it after, so iteration with a stop is one dispatch and one count per round. Integers are 32-bit words and every mode is exact: the final labels do not depend on the order invocations ran in. Over a live count (`COUNT=device`, see the abi README) the elements (rank, min) or the pairs (label) are the first `domain_count` slots of a capacity `n`, and the `n` param is not read. In rank and min mode a slot at or past the live count links to itself with the value 0. It binds 8 storage buffers (7 in the plain variant).

# compact Turns a keep mask into the indices of the kept elements, and the map back from every element to the place it holds among them. `indices` lists the elements whose mask word is not 0 (a float mask of 0.0 and 1.0 reads the same way), in run order; its live count is the number kept. `inverse` holds, for every element, its place among the kept ones, or -1 for an element that is not kept, so a column carried to the kept elements (a gather by `indices`) and a column of per-kept values carried back (a read through `inverse`) agree on which element is which. The dispatch size `n` is the number of elements. One workgroup of 256 works the whole run, a tile of 256 elements at a time; the other workgroups of a larger dispatch return. Exact: the order is the run's own, so the same mask gives the same answer on every dispatch. Over a live count (`COUNT=device`, see the abi README) `n` is the capacity and the first `domain_count` mask words are the elements: words past it are not read, a slot of `inverse` at or past it holds -1, and the slots of `indices` past the kept ones hold -1. `indices` has room for `n` and its counter is the live count the next kernel takes as its domain. It binds 5 storage buffers (4 in the plain variant).

# math.ceil (procNode) The least whole number not below the value, element by element. The `ceil` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.

# math.max (procNode) The greater of two values, element by element. The `max` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.

# loops Orders directed edges into rings and chains. This kernel links each edge to the edge that follows it (`next`) and marks the edges a chain starts with (`head`); the `jump` and `loops_cut` and `loops_place` kernels do the rest. For the boundary of a mesh, the directed edges are its open edges run the way their one face runs them (`tail` is `a` when `rev` is 0, else `b`). The whole sequence over `m` edges and `npts` points: 1. `loops` (`STAGE` clear, claim, link): `next`, `head`. 2. `jump` (`MODE` min), ceil(log2 m) rounds, starting from `parent` = `next` and `value` = the edge index: every edge holds the smallest index within reach, and `parent` holds the edge 2^k steps ahead. 3. `loops_cut` (`STAGE` head, cut): a ring (a cycle) starts at its smallest edge; a chain starts at its head. The edge before each start becomes the end of its list. 4. `jump` (`MODE` rank) over the cut lists, starting with `value` 1 on every non-end edge: each edge's end and its distance to it. 5. `loops_place` (`STAGE` claim, place): each edge's ring (the first edge of its list) and its position along the ring. A compaction of the first edges numbers the rings, and a prefix sum of ring lengths (`rank` of the first edge plus 1) gives the ring starts; an edge's place in the ordered listing is its ring's start plus its position. Over a live count (`COUNT=device`, see the abi README) the stages claim and link run over a capacity of edges whose live count is `domain_count`, and the `n` and `npts` params are not read. Stage clear runs over the capacity of points and writes the cleared value into every slot, which is the value a slot past the live points holds. In stage link a slot past the live edges links to itself and is no head. It binds 7 storage buffers (6 in the plain variant).

# math.log (procNode) The natural logarithm of a value, element by element. A value at or below 0 answers 0. The `log` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.

# loops_place Gives every edge its ring and its position along it, from the ranked lists `loops_cut` and `jump` produced. `ring` is the first edge of the edge's list, so two edges are on one ring exactly when their `ring` values are equal; `pos` counts along the ring from that first edge. See `loops` for the whole sequence. Over a live count (`COUNT=device`, see the abi README) the edges are the first `domain_count` slots of a capacity `n`, and the `n` param is not read. A slot past the live edges has the ring -1 and the position 0. It binds 7 storage buffers (6 in the plain variant).

# math.to_int (procNode) A value truncated to a whole number held as an integer. The `to_int` operation of the authoring surface, called through the Luau node on `proc.fieldc.operators`. Operands are numbers, vectors, Columns or Fields. When every operand is a plain number or vector the answer is the plain result, folded where the node cooks; otherwise the answer is a Field: a template over its operands that whatever reads it evaluates in one dispatch together with the chain around it. Nothing dispatches for this node alone.