@aethervtt/shard-transform 0.0.1

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

@@ -0,0 +1,3 @@
+# @aethervtt/shard-transform
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/components.d.ts

@@ -0,0 +1,10 @@
+import { type Infer } from '@aethervtt/shard-core';
+export declare const GlobalTransform: import("@aethervtt/shard-core").ComponentDef<{
+    readonly matrix: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number], "f32">;
+}>;
+export declare const Transform: import("@aethervtt/shard-core").ComponentDef<{
+    readonly translation: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly rotation: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Quat, "f32">;
+    readonly scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+}>;
+export type TransformValue = Infer<typeof Transform>;

package/dist/components.js

@@ -0,0 +1,30 @@
+import { defineComponent, t } from "@aethervtt/shard-core";
+const GlobalTransform = defineComponent(
+  "core/GlobalTransform",
+  {
+    matrix: t.affine3x4({
+      readonly: true,
+      description: "World matrix (top three rows, row by row), relative to the floating origin. Computed from Transform each frame."
+    })
+  },
+  {
+    description: "World-space transform relative to the floating origin (the world origin when there is none). Computed by core/transform-propagate; do not write.",
+    serialize: false
+  }
+);
+const Transform = defineComponent(
+  "core/Transform",
+  {
+    translation: t.vec3({ unit: "m", description: "Position relative to the parent (or world)." }),
+    rotation: t.quat({ description: "Rotation relative to the parent, as a unit quaternion." }),
+    scale: t.vec3({ default: [1, 1, 1], description: "Scale along local axes." })
+  },
+  {
+    description: "Local transform. Y is up, -Z is forward. In 2D, translation.z orders layers and rotation is around Z.",
+    requires: [GlobalTransform]
+  }
+);
+export {
+  GlobalTransform,
+  Transform
+};

package/dist/grid.d.ts

@@ -0,0 +1,124 @@
+import { type Entity, type Table, type World } from '@aethervtt/shard-core';
+/**
+ * Large-world coordinates (spec 0040). A position in a grid is `GridCell × cellSize + translation`:
+ * the cell is an exact integer, and the f32 translation stays small. `GlobalTransform` is relative
+ * to the `FloatingOrigin` entity's cell, so everything near the camera is precise.
+ */
+export declare const Grid: import("@aethervtt/shard-core").ComponentDef<{
+    readonly cellSize: import("@aethervtt/shard-core").FieldType<number, "f64">;
+    readonly hysteresis: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const GridCell: import("@aethervtt/shard-core").ComponentDef<{
+    readonly cell: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").IVec3, "i32">;
+}>;
+export declare const FloatingOrigin: import("@aethervtt/shard-core").TagDef;
+export interface OriginShiftData {
+    /** The origin grid after the shift (null for the root frame). */
+    grid: Entity | null;
+    /** oldCell − newCell, when the origin stayed in the same grid; zero when it changed grids. */
+    delta: [number, number, number];
+    /** Metres to add to a position in the old origin frame to get it in the new one. */
+    offset: [number, number, number];
+}
+/**
+ * Sent (and triggered for observers) when the origin frame moves: the origin entity changed cells or
+ * grids. Anything that keeps positions from `GlobalTransform` across frames adds `offset` to them.
+ */
+export declare const OriginShift: import("@aethervtt/shard-core").EventDef<OriginShiftData>;
+/**
+ * Each grid's frame relative to the origin: `origin = A · ((cell − ref) × cellSize + p)` for a point
+ * `p` in cell `cell`. `ref` is a cell near the origin, so the cell difference is exact integer math
+ * and `A`'s translation stays small. Slot 0 is the root frame (entities with no grid ancestor).
+ */
+export declare class GridFrames {
+    /** Grid entity per slot (ROOT for slot 0). */
+    entity: Entity[];
+    /** f64 affine per slot (12 each). */
+    a: Float64Array<ArrayBuffer>;
+    /** Reference cell per slot (3 each). */
+    ref: Int32Array<ArrayBuffer>;
+    cellSize: Float64Array<ArrayBuffer>;
+    /** The grid's own frame → origin, rounded to f32 (its GlobalTransform). */
+    frame32: Float32Array<ArrayBuffer>;
+    /** 1 when the slot's A or ref changed this frame: everything under it re-propagates. */
+    moved: Uint8Array<ArrayBuffer>;
+    /** Solve stamp per slot; a slot is current when it equals `stamp`. */
+    solved: Uint32Array<ArrayBuffer>;
+    /** Seen stamp per slot, to drop slots of despawned grids. */
+    seen: Uint32Array<ArrayBuffer>;
+    count: number;
+    stamp: number;
+    readonly slotOf: Map<number, number>;
+    /** Origin grid slot and cell. */
+    originSlot: number;
+    originCell: Int32Array<ArrayBuffer>;
+    originEntity: Entity;
+    /** Whether any grid or origin is active; false means the root frame is the identity. */
+    active: boolean;
+    /** True when slot 0 (root frame) is exactly the identity. */
+    rootIdentity: boolean;
+    /**
+     * Some grid sits under an ordinary entity, whose transform change detection can't see cheaply,
+     * so every frame solves in full.
+     */
+    indirect: boolean;
+    constructor();
+    slot(grid: Entity): number;
+    private grow;
+    /** Drops slots whose grid no longer exists. Rare: only when grids despawn. */
+    compact(): void;
+}
+/** The grid frames the propagation system solved this frame. Read by physics and the renderer. */
+export declare const GridFramesResource: import("@aethervtt/shard-core").ResourceDef<GridFrames>;
+/** Where an entity sits: the grid it's in (ROOT for none), its cell there, and the f64 affine
+ * from the entity's frame to `cell × cellSize` in that grid. */
+export interface Placement {
+    grid: Entity;
+    cell: Int32Array;
+    m: Float64Array;
+    /** How many entities' transforms were composed (1 for a direct child of the grid). */
+    depth: number;
+}
+export declare const createPlacement: () => Placement;
+export declare function isGrid(world: World, e: Entity): boolean;
+/**
+ * Walks up from `e` (including its own transform when `self` is true) to its nearest grid, composing
+ * transforms in f64. The direct child of that grid contributes its cell.
+ */
+export declare function placementOf(world: World, e: Entity, out: Placement, self?: boolean): Placement;
+/**
+ * Solves every grid's frame for this frame. `gridTables` are the tables holding grids (from the
+ * propagation system's query); `origin` is the FloatingOrigin entity or ROOT. Returns whether the
+ * origin frame shifted, with the shift written into `shift`. When nothing that affects the frames
+ * changed since `since` (pass -1 to force), it only checks the origin's cell.
+ */
+export declare function solveGrids(world: World, frames: GridFrames, gridTables: readonly Table[], origin: Entity, shift: OriginShiftData, since?: number): boolean;
+/** Back to "no grids": the root frame is the identity. Returns whether anything changed. */
+export declare function resetGrids(frames: GridFrames): boolean;
+/**
+ * The f64 affine from `e`'s own frame to the origin frame (its exact GlobalTransform). Solves grids
+ * fresh, so it's valid right after spawning or moving things. Cold path.
+ */
+export declare function originMatrix64(world: World, e: Entity, out: Float64Array): Float64Array;
+/**
+ * Position of `e` in `frame`'s coordinates (default: the origin frame), exact to f64. With a grid
+ * as `frame`, the result is `cell × cellSize + offset` in that grid.
+ */
+export declare function worldPosition64(world: World, e: Entity, out: Float64Array, frame?: Entity): Float64Array;
+/**
+ * Distance between two entities, exact at any distance from the origin: entities in the same grid
+ * subtract cells as integers first.
+ */
+export declare function distance64(world: World, a: Entity, b: Entity): number;
+/**
+ * Puts `e` at `position` (f64, in `grid`'s frame) as a direct child of `grid`: sets its cell,
+ * translation, and parent.
+ */
+export declare function placeInGrid(world: World, e: Entity, grid: Entity, position: ArrayLike<number>): void;
+/**
+ * Moves `e` into `grid` (as a direct child) keeping its pose in the origin frame, e.g. a ship
+ * entering a planet's rotating grid. Computes the new cell and transform in f64.
+ */
+export declare function reparentToGrid(world: World, e: Entity, grid: Entity): void;
+/** The grid `e` is directly in (its parent, when that's a Grid), or undefined. */
+export declare function gridOf(world: World, e: Entity): Entity | undefined;