@aethervtt/shard-grid 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @aethervtt/shard-grid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/grid.d.ts

@@ -0,0 +1,36 @@
+import { type AssetRef, type Entity, type World } from '@aethervtt/shard-core';
+export declare const GRID_KINDS: readonly ['square', 'hex'];
+export declare const HEX_ORIENTATIONS: readonly ['pointy', 'flat'];
+export declare const Grid: import("@aethervtt/shard-core").ComponentDef<{
+    readonly kind: import("@aethervtt/shard-core").FieldType<"hex" | "square", "u8">;
+    readonly orientation: import("@aethervtt/shard-core").FieldType<"flat" | "pointy", "u8">;
+    readonly size: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly opacity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly lineWidth: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly extent: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+}>;
+export declare const GridLines: import("@aethervtt/shard-render").MaterialType;
+export declare const GRID_SHADERS: Record<string, string>;
+/** The quad and material a Grid draws with. */
+export declare const GridQuad: import("@aethervtt/shard-core").ComponentDef<{
+    readonly grid: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+}>;
+interface GridRecord {
+    quad: Entity;
+    material: AssetRef<'Material'>;
+}
+export interface GridStateValue {
+    grids: Map<Entity, GridRecord>;
+    quad: AssetRef<'Mesh'> | undefined;
+    /** Grids removed since the last sync. */
+    removed: Entity[];
+}
+export declare const GridState: import("@aethervtt/shard-core").ResourceDef<GridStateValue>;
+/** Keeps each Grid's quad and material in step with it; drops them when the Grid goes. */
+export declare const syncGrids: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+}>;
+export declare function observeGridRemovals(world: World): void;
+export {};

package/dist/grid.js

@@ -0,0 +1,240 @@
+import {
+  ChildOf,
+  defineComponent,
+  defineResource,
+  defineSystem,
+  onRemove,
+  t
+} from "@aethervtt/shard-core";
+import { plane } from "@aethervtt/shard-mesh";
+import {
+  defineMaterial,
+  GpuAssetsResource,
+  GROUND_BANDS,
+  GroundLayer,
+  MaterialAsset,
+  Materials,
+  Mesh3d,
+  Meshes,
+  MeshMaterial,
+  NotShadowCaster
+} from "@aethervtt/shard-render";
+import { Transform } from "@aethervtt/shard-transform";
+const GRID_KINDS = ["square", "hex"];
+const HEX_ORIENTATIONS = ["pointy", "flat"];
+const Grid = defineComponent(
+  "grid/Grid",
+  {
+    kind: t.enum(GRID_KINDS, { description: "Square cells, or hexes." }),
+    orientation: t.enum(HEX_ORIENTATIONS, {
+      description: "Hex grids: pointy-top (rows of hexes) or flat-top (columns)."
+    }),
+    size: t.f32({
+      default: 1.5,
+      min: 1e-4,
+      unit: "m",
+      description: "Square: cell edge. Hex: distance between adjacent cell centres. Visual: a host converts it with its one fixed scale; game distance never sets it."
+    }),
+    offset: t.vec2({
+      description: "Where cell (0, 0) starts (square) or is centred (hex), world (x, z)."
+    }),
+    color: t.color({ default: [0, 0, 0, 1], description: "Line color (linear)." }),
+    opacity: t.f32({ default: 0.5, min: 0, max: 1, description: "Line opacity." }),
+    lineWidth: t.f32({
+      default: 1,
+      min: 0,
+      unit: "px",
+      description: "Line width in CSS pixels, at every zoom and display density."
+    }),
+    extent: t.vec2({
+      default: [100, 100],
+      description: "Size of the drawn area, (x, z) in world units, centred on the entity."
+    })
+  },
+  {
+    description: "A square or hex grid drawn as one quad in the grid band (20) at the entity's height. Game distance (per cell, unit, diagonal rule) isn't here: it measures (grid/math distance), it never draws.",
+    requires: [Transform]
+  }
+);
+const GridLines = defineMaterial("grid/GridLines", {
+  extends: "none",
+  blend: "premultiplied",
+  // Lines over the table, not a thing on it: picks reach the tiles and floor under them.
+  pickable: false,
+  fields: {
+    color: t.color({ default: [0, 0, 0, 1], description: "Line color (linear), alpha included." }),
+    lineWidth: t.f32({ default: 1, min: 0, description: "CSS pixels." }),
+    size: t.f32({ default: 1, min: 1e-4, description: "World units." }),
+    offset: t.vec2({ description: "World (x, z)." }),
+    mode: t.f32({ description: "0 square, 1 pointy hex, 2 flat hex." })
+  },
+  shader: "grid::lines",
+  description: "Analytic grid lines of constant CSS-pixel width (0057). One per Grid."
+});
+const GRID_SHADERS = {
+  "grid::lines": `
+import shard::pbr::types::VertexOutput;
+import shard::view::view;
+import material::grid_lines::GridLines;
+
+const SQRT3: f32 = 1.7320508;
+
+/** World distance to the nearest edge of a pointy-top hex tiling, and that edge's normal. */
+fn hex_edge(p: vec2f, s: f32) -> vec3f {
+  let r = (2.0 * p.y) / (SQRT3 * s);
+  let q = p.x / s - r / 2.0;
+  let x = q;
+  let z = r;
+  let y = -x - z;
+  var rx = round(x);
+  var ry = round(y);
+  var rz = round(z);
+  let dx = abs(rx - x);
+  let dy = abs(ry - y);
+  let dz = abs(rz - z);
+  if (dx > dy && dx > dz) { rx = -ry - rz; } else if (dy > dz) { ry = -rx - rz; } else { rz = -rx - ry; }
+  let c = vec2f(s * (rx + rz / 2.0), s * (SQRT3 / 2.0) * rz);
+  let d = p - c;
+  let a = abs(d);
+  let sg = select(vec2f(-1.0), vec2f(1.0), d >= vec2f(0.0));
+  // Edge normals of a pointy-top hex: 0\xB0 and \xB160\xB0 (inradius s / 2).
+  let slant = dot(a, vec2f(0.5, SQRT3 / 2.0));
+  if (a.x >= slant) { return vec3f(s * 0.5 - a.x, sg.x, 0.0); }
+  return vec3f(s * 0.5 - slant, sg.x * 0.5, sg.y * SQRT3 / 2.0);
+}
+
+/** Pixels from the line: the world distance over world units per pixel along the normal. */
+fn pixels(d: f32, n: vec2f, p: vec2f) -> f32 {
+  let g = vec2f(dot(dpdx(p), n), dot(dpdy(p), n));
+  return d / max(length(g), 1e-8);
+}
+
+override fn shade(in: VertexOutput) -> vec4f {
+  let p = in.world_position.xz - GridLines.offset;
+  let s = GridLines.size;
+  var d_px: f32;
+  var spacing: f32;
+  if (GridLines.mode < 0.5) {
+    let f = abs(fract(p / s + 0.5) - 0.5) * s;
+    let dx = pixels(f.x, vec2f(1.0, 0.0), p);
+    let dz = pixels(f.y, vec2f(0.0, 1.0), p);
+    d_px = min(dx, dz);
+    spacing = min(pixels(s, vec2f(1.0, 0.0), p), pixels(s, vec2f(0.0, 1.0), p));
+  } else {
+    // Flat-top hexes are pointy-top ones with x and z swapped.
+    let flat = GridLines.mode > 1.5;
+    let q = select(p, p.yx, flat);
+    let e = hex_edge(q, s);
+    let n = select(e.yz, e.zy, flat);
+    d_px = pixels(e.x, n, p);
+    spacing = pixels(s, n, p);
+  }
+  let width = GridLines.lineWidth * view.pixelScale.x;
+  var a = clamp(width * 0.5 + 0.5 - d_px, 0.0, 1.0);
+  a *= smoothstep(3.0, 6.0, spacing) * GridLines.color.a;
+  if (a <= 0.0) { discard; }
+  // Display-referred, like any overlay: the scene's exposure doesn't dim it.
+  return vec4f(GridLines.color.rgb * a / view.exposure, a);
+}`
+};
+const GridQuad = defineComponent(
+  "grid/GridQuad",
+  { grid: t.entity({ readonly: true, description: "The Grid this quad draws." }) },
+  {
+    description: "A Grid's quad: spawned and kept by the grid plugin.",
+    serialize: false,
+    save: false
+  }
+);
+const GridState = defineResource("grid/State", {
+  description: "Each Grid entity's quad and material.",
+  init: () => ({ grids: /* @__PURE__ */ new Map(), quad: void 0, removed: [] })
+});
+const MODES = { square: 0, pointy: 1, flat: 2 };
+function lineValues(v) {
+  return {
+    color: [v.color[0], v.color[1], v.color[2], v.color[3] * v.opacity],
+    lineWidth: v.lineWidth,
+    size: v.size,
+    offset: [v.offset[0], v.offset[1]],
+    mode: v.kind === "square" ? MODES.square : MODES[v.orientation]
+  };
+}
+const syncGrids = defineSystem({
+  name: "grid/sync",
+  description: "Keeps each Grid's quad (size, band) and line material in step with the Grid.",
+  setup: (world) => ({ q: world.query({ with: [Grid] }) }),
+  run: ({ q }, world, ctx) => {
+    const state = world.resource(GridState);
+    if (state.removed.length > 0) {
+      for (const e of state.removed) dropGrid(world, state, e);
+      state.removed.length = 0;
+    }
+    const since = ctx.lastRunTick;
+    for (const table of q.tables) {
+      const grounded = table.has(GroundLayer);
+      if (table.lastChanged(Grid) <= since && !(grounded && table.lastChanged(GroundLayer) > since))
+        continue;
+      const ticks = table.changedTicks(Grid);
+      const groundTicks = grounded ? table.changedTicks(GroundLayer) : void 0;
+      for (let row = 0; row < table.count; row++) {
+        if (ticks[row] <= since && !(groundTicks && groundTicks[row] > since)) continue;
+        updateGrid(world, state, table.entities[row]);
+      }
+    }
+  }
+});
+function updateGrid(world, state, e) {
+  const v = world.get(e, Grid);
+  const band = world.tryGet(e, GroundLayer) ?? { band: GROUND_BANDS.grid, order: 0 };
+  let rec = state.grids.get(e);
+  const materials = world.resource(Materials);
+  if (!rec) {
+    state.quad ??= world.resource(Meshes).add(plane({ size: 1 }), "grid:quad");
+    const material = materials.add(
+      new MaterialAsset(lineValues(v), GridLines),
+      `grid:lines/${e}`
+    );
+    const quad = world.spawn(
+      [Mesh3d, { mesh: state.quad }],
+      [MeshMaterial, { material }],
+      [GroundLayer, band],
+      [GridQuad, { grid: e }],
+      NotShadowCaster,
+      Transform,
+      [ChildOf, { parent: e }]
+    );
+    rec = { quad, material };
+    state.grids.set(e, rec);
+  } else {
+    materials.get(rec.material)?.set(lineValues(v));
+    world.set(rec.quad, GroundLayer, band);
+  }
+  world.set(rec.quad, Transform, { scale: [v.extent[0], 1, v.extent[1]] });
+}
+function dropGrid(world, state, e) {
+  const rec = state.grids.get(e);
+  if (!rec) return;
+  state.grids.delete(e);
+  if (world.isAlive(rec.quad)) world.despawn(rec.quad);
+  const materials = world.resource(Materials);
+  const material = materials.get(rec.material);
+  if (material) world.tryResource(GpuAssetsResource)?.releaseMaterial(material);
+  materials.delete(rec.material.guid);
+}
+function observeGridRemovals(world) {
+  world.observe(onRemove(Grid), ({ entity, world: w }) => {
+    w.tryResource(GridState)?.removed.push(entity);
+  });
+}
+export {
+  GRID_KINDS,
+  GRID_SHADERS,
+  Grid,
+  GridLines,
+  GridQuad,
+  GridState,
+  HEX_ORIENTATIONS,
+  observeGridRemovals,
+  syncGrids
+};

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GRID_KINDS, GRID_SHADERS, Grid, GridLines, GridQuad, GridState, type GridStateValue, HEX_ORIENTATIONS, syncGrids, } from './grid.js';
+export { axialToCube, type Cell, cellAt, cellCenter, cellPolygon, cubeToAxial, type DiagonalRule, distance, edgeMidpoints, type GridGeometry, type GridKind, gridVertex, type HexOrientation, hexDistance, neighbors, pathDistance, pointToAxial, roundAxial, tokenCenter, wallAnchor, } from './math.js';
+export { gridPlugin } from './plugin.js';

package/dist/index.js

@@ -0,0 +1,54 @@
+import {
+  GRID_KINDS,
+  GRID_SHADERS,
+  Grid,
+  GridLines,
+  GridQuad,
+  GridState,
+  HEX_ORIENTATIONS,
+  syncGrids
+} from "./grid.js";
+import {
+  axialToCube,
+  cellAt,
+  cellCenter,
+  cellPolygon,
+  cubeToAxial,
+  distance,
+  edgeMidpoints,
+  gridVertex,
+  hexDistance,
+  neighbors,
+  pathDistance,
+  pointToAxial,
+  roundAxial,
+  tokenCenter,
+  wallAnchor
+} from "./math.js";
+import { gridPlugin } from "./plugin.js";
+export {
+  GRID_KINDS,
+  GRID_SHADERS,
+  Grid,
+  GridLines,
+  GridQuad,
+  GridState,
+  HEX_ORIENTATIONS,
+  axialToCube,
+  cellAt,
+  cellCenter,
+  cellPolygon,
+  cubeToAxial,
+  distance,
+  edgeMidpoints,
+  gridPlugin,
+  gridVertex,
+  hexDistance,
+  neighbors,
+  pathDistance,
+  pointToAxial,
+  roundAxial,
+  syncGrids,
+  tokenCenter,
+  wallAnchor
+};

package/dist/math.d.ts

@@ -0,0 +1,61 @@
+export type GridKind = 'square' | 'hex';
+export type HexOrientation = 'pointy' | 'flat';
+/** Aether's diagonal rules: true length, every step one cell, or 1-2-1-2 alternating. */
+export type DiagonalRule = 'euclidean' | 'equal' | 'alternating';
+/** What cell math needs of a grid: its shape, cell size and origin, in world units. */
+export interface GridGeometry {
+    kind: GridKind;
+    orientation: HexOrientation;
+    /** Square: cell edge. Hex: distance between adjacent cell centres. */
+    size: number;
+    /** Where cell (0, 0) starts (square) or is centred (hex), as (x, z). */
+    offset: readonly [number, number];
+}
+/** A cell: (column, row) for square grids, axial (q, r) for hex grids. */
+export type Cell = [number, number];
+/** Axial hex coordinates to cube (x, y, z), with x + y + z = 0. */
+export declare function axialToCube(q: number, r: number): [number, number, number];
+/** Cube hex coordinates to axial (q, r). */
+export declare function cubeToAxial(x: number, _y: number, z: number): Cell;
+/** Rounds fractional axial coordinates to the nearest hex, through cube space. */
+export declare function roundAxial(q: number, r: number): Cell;
+/** Fractional axial coordinates of a world point. */
+export declare function pointToAxial(grid: GridGeometry, x: number, z: number): Cell;
+/** The cell containing a world point (x, z). */
+export declare function cellAt(grid: GridGeometry, x: number, z: number): Cell;
+/** A cell's centre, as world (x, z). */
+export declare function cellCenter(grid: GridGeometry, cell: readonly [number, number]): [number, number];
+/** A cell's outline: its corners as world (x, z), in order around it. */
+export declare function cellPolygon(grid: GridGeometry, cell: readonly [number, number]): [number, number][];
+/** A cell's neighbours: 8 for square grids (diagonals included), 6 for hex grids. */
+export declare function neighbors(grid: GridGeometry, cell: readonly [number, number]): Cell[];
+/** Hex steps between two axial cells (orientation doesn't matter). */
+export declare function hexDistance(a: readonly [number, number], b: readonly [number, number]): number;
+/**
+ * The distance from world point `a` to `b`, in cells, by Aether's rules: hex grids count hex
+ * steps; square grids measure the true length (`euclidean`), the longer axis (`equal`), or count
+ * diagonals 1, 2, 1, 2 (`alternating`, starting cheap).
+ */
+export declare function distance(grid: GridGeometry, a: readonly [number, number], b: readonly [number, number], diagonal: DiagonalRule): number;
+/**
+ * The distance along a path of world points, per leg and in total, in cells. With `alternating`,
+ * the 1-2-1-2 phase carries across waypoints; diagonal steps round to whole cells, straight
+ * movement stays fractional (Aether's `pathCells`).
+ */
+export declare function pathDistance(grid: GridGeometry, points: readonly (readonly [number, number])[], diagonal: DiagonalRule): {
+    legs: number[];
+    total: number;
+};
+type Point = [number, number];
+/** The grid corner nearest (x, z): a square's intersection, or a hex's vertex. */
+export declare function gridVertex(grid: GridGeometry, x: number, z: number): Point;
+/** The midpoints of the edges of the cell containing (x, z). */
+export declare function edgeMidpoints(grid: GridGeometry, x: number, z: number): Point[];
+/** Where a wall's end snaps: the nearest cell corner or edge midpoint. */
+export declare function wallAnchor(grid: GridGeometry, x: number, z: number): Point;
+/**
+ * Where a token's centre snaps: odd square footprints (in cells) to a cell centre, even ones to an
+ * intersection; hex tokens always to a cell centre.
+ */
+export declare function tokenCenter(grid: GridGeometry, x: number, z: number, footprint?: number): Point;
+export {};

package/dist/math.js

@@ -0,0 +1,225 @@
+const SQRT3 = Math.sqrt(3);
+function axialToCube(q, r) {
+  return [q, -q - r, r];
+}
+function cubeToAxial(x, _y, z) {
+  return [x, z];
+}
+function roundAxial(q, r) {
+  const x = q;
+  const z = r;
+  const y = -x - z;
+  let rx = Math.round(x);
+  let ry = Math.round(y);
+  let rz = Math.round(z);
+  const dx = Math.abs(rx - x);
+  const dy = Math.abs(ry - y);
+  const dz = Math.abs(rz - z);
+  if (dx > dy && dx > dz) rx = -ry - rz;
+  else if (dy > dz) ry = -rx - rz;
+  else rz = -rx - ry;
+  return [rx + 0, rz + 0];
+}
+function pointToAxial(grid, x, z) {
+  const px = x - grid.offset[0];
+  const pz = z - grid.offset[1];
+  if (grid.orientation === "flat") {
+    const q = 2 * px / (SQRT3 * grid.size);
+    return [q, pz / grid.size - q / 2];
+  }
+  const r = 2 * pz / (SQRT3 * grid.size);
+  return [px / grid.size - r / 2, r];
+}
+function cellAt(grid, x, z) {
+  if (grid.kind === "hex") {
+    const [q, r] = pointToAxial(grid, x, z);
+    return roundAxial(q, r);
+  }
+  return [
+    Math.floor((x - grid.offset[0]) / grid.size),
+    Math.floor((z - grid.offset[1]) / grid.size)
+  ];
+}
+function cellCenter(grid, cell) {
+  const [a, b] = cell;
+  if (grid.kind === "hex") {
+    if (grid.orientation === "flat") {
+      return [
+        grid.offset[0] + grid.size * (SQRT3 / 2) * a,
+        grid.offset[1] + grid.size * (b + a / 2)
+      ];
+    }
+    return [grid.offset[0] + grid.size * (a + b / 2), grid.offset[1] + grid.size * (SQRT3 / 2) * b];
+  }
+  return [grid.offset[0] + (a + 0.5) * grid.size, grid.offset[1] + (b + 0.5) * grid.size];
+}
+function cellPolygon(grid, cell) {
+  const [cx, cz] = cellCenter(grid, cell);
+  if (grid.kind === "square") {
+    const h = grid.size / 2;
+    return [
+      [cx - h, cz - h],
+      [cx + h, cz - h],
+      [cx + h, cz + h],
+      [cx - h, cz + h]
+    ];
+  }
+  const radius = grid.size / SQRT3;
+  const start = grid.orientation === "pointy" ? -30 : 0;
+  const out = [];
+  for (let i = 0; i < 6; i++) {
+    const a = (start + i * 60) * Math.PI / 180;
+    out.push([cx + radius * Math.cos(a), cz + radius * Math.sin(a)]);
+  }
+  return out;
+}
+const SQUARE_NEIGHBORS = [
+  [1, 0],
+  [1, 1],
+  [0, 1],
+  [-1, 1],
+  [-1, 0],
+  [-1, -1],
+  [0, -1],
+  [1, -1]
+];
+const HEX_NEIGHBORS = [
+  [1, 0],
+  [1, -1],
+  [0, -1],
+  [-1, 0],
+  [-1, 1],
+  [0, 1]
+];
+function neighbors(grid, cell) {
+  const list = grid.kind === "hex" ? HEX_NEIGHBORS : SQUARE_NEIGHBORS;
+  return list.map(([dx, dy]) => [cell[0] + dx, cell[1] + dy]);
+}
+function hexDistance(a, b) {
+  const dq = a[0] - b[0];
+  const dr = a[1] - b[1];
+  return (Math.abs(dq) + Math.abs(dr) + Math.abs(dq + dr)) / 2;
+}
+function distance(grid, a, b, diagonal) {
+  return pathDistance(grid, [a, b], diagonal).total;
+}
+function pathDistance(grid, points, diagonal) {
+  const legs = [];
+  let total = 0;
+  let expensiveNext = false;
+  for (let i = 0; i + 1 < points.length; i++) {
+    const a = points[i];
+    const b = points[i + 1];
+    let value;
+    if (grid.kind === "hex") {
+      value = hexDistance(cellAt(grid, a[0], a[1]), cellAt(grid, b[0], b[1]));
+    } else {
+      const dx = Math.abs(b[0] - a[0]) / grid.size;
+      const dz = Math.abs(b[1] - a[1]) / grid.size;
+      if (diagonal === "equal") value = Math.max(dx, dz);
+      else if (diagonal === "alternating") {
+        const diagonals = Math.round(Math.min(dx, dz));
+        const straight = Math.abs(dx - dz);
+        value = straight + Math.floor(diagonals / 2) * 3;
+        if (diagonals % 2 === 1) {
+          value += expensiveNext ? 2 : 1;
+          expensiveNext = !expensiveNext;
+        }
+      } else value = Math.sqrt(dx * dx + dz * dz);
+    }
+    legs.push(value);
+    total += value;
+  }
+  return { legs, total };
+}
+function hexCorners(grid, cx, cz, out) {
+  const radius = grid.size / SQRT3;
+  const start = grid.orientation === "pointy" ? -30 : 0;
+  for (let i = 0; i < 6; i++) {
+    const a = (start + i * 60) * Math.PI / 180;
+    out.push([cx + radius * Math.cos(a), cz + radius * Math.sin(a)]);
+  }
+}
+function nearbyHexes(grid, x, z) {
+  const cell = cellAt(grid, x, z);
+  return [cell, ...neighbors(grid, cell)].map((c) => cellCenter(grid, c));
+}
+function nearest(x, z, choices) {
+  let best = choices[0] ?? [x, z];
+  let d = Infinity;
+  for (const c of choices) {
+    const e = (c[0] - x) ** 2 + (c[1] - z) ** 2;
+    if (e < d) {
+      d = e;
+      best = c;
+    }
+  }
+  return [best[0], best[1]];
+}
+function gridVertex(grid, x, z) {
+  if (grid.kind === "square") {
+    return [
+      grid.offset[0] + Math.round((x - grid.offset[0]) / grid.size) * grid.size,
+      grid.offset[1] + Math.round((z - grid.offset[1]) / grid.size) * grid.size
+    ];
+  }
+  const corners = [];
+  for (const [cx, cz] of nearbyHexes(grid, x, z)) hexCorners(grid, cx, cz, corners);
+  return nearest(x, z, corners);
+}
+function edgeMidpoints(grid, x, z) {
+  const [cx, cz] = cellCenter(grid, cellAt(grid, x, z));
+  if (grid.kind === "square") {
+    const h = grid.size / 2;
+    return [
+      [cx, cz - h],
+      [cx + h, cz],
+      [cx, cz + h],
+      [cx - h, cz]
+    ];
+  }
+  const corners = [];
+  hexCorners(grid, cx, cz, corners);
+  return corners.map((a, i) => {
+    const b = corners[(i + 1) % 6];
+    return [(a[0] + b[0]) / 2, (a[1] + b[1]) / 2];
+  });
+}
+function wallAnchor(grid, x, z) {
+  if (grid.kind === "square")
+    return nearest(x, z, [gridVertex(grid, x, z), ...edgeMidpoints(grid, x, z)]);
+  const features = [];
+  for (const [cx, cz] of nearbyHexes(grid, x, z)) {
+    const corners = [];
+    hexCorners(grid, cx, cz, corners);
+    features.push(...corners);
+    for (let i = 0; i < 6; i++) {
+      const a = corners[i];
+      const b = corners[(i + 1) % 6];
+      features.push([(a[0] + b[0]) / 2, (a[1] + b[1]) / 2]);
+    }
+  }
+  return nearest(x, z, features);
+}
+function tokenCenter(grid, x, z, footprint = 1) {
+  if (grid.kind === "hex" || Math.max(1, Math.round(footprint)) % 2 === 1)
+    return cellCenter(grid, cellAt(grid, x, z));
+  return gridVertex(grid, x, z);
+}
+export {
+  axialToCube,
+  cellAt,
+  cellCenter,
+  cellPolygon,
+  cubeToAxial,
+  distance,
+  edgeMidpoints,
+  gridVertex,
+  hexDistance,
+  neighbors,
+  pathDistance,
+  pointToAxial,
+  roundAxial,
+  tokenCenter,
+  wallAnchor
+};

package/dist/plugin.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tabletop grids (0057): square and hex grids drawn analytically, one quad each, in the grid
+ * band. Needs `forwardPlugin` (render/forward).
+ */
+export declare const gridPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,29 @@
+import { PostUpdate } from "@aethervtt/shard-core";
+import { registerShaders, Shaders } from "@aethervtt/shard-render";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { TransformSystems } from "@aethervtt/shard-transform";
+import {
+  GRID_SHADERS,
+  Grid,
+  GridLines,
+  GridQuad,
+  GridState,
+  observeGridRemovals,
+  syncGrids
+} from "./grid.js";
+const gridPlugin = definePlugin({
+  name: "grid",
+  dependencies: ["render/forward", "core/transform"],
+  provides: [Grid, GridQuad, GridLines, GridState],
+  build(app) {
+    app.world.initResource(GridState);
+    observeGridRemovals(app.world);
+    app.addSystems(PostUpdate, syncGrids.before(TransformSystems));
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), GRID_SHADERS);
+  }
+});
+export {
+  gridPlugin
+};

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@aethervtt/shard-grid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./math": {
+      "types": "./dist/math.d.ts",
+      "default": "./dist/math.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@aethervtt/shard-core": "0.1.0",
+    "@aethervtt/shard-mesh": "0.1.0",
+    "@aethervtt/shard-render": "0.1.0",
+    "@aethervtt/shard-runtime": "0.1.0",
+    "@aethervtt/shard-transform": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/grid"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "8e14c9896f82a3554b156f1ffdd68f2cc3e7d78a"
+  }
+}