@aethervtt/shard-render 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-render
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/assets.d.ts

@@ -0,0 +1,104 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type Infer, type SchemaContext, ShardError } from '@aethervtt/shard-core';
+import { type Mesh } from '@aethervtt/shard-mesh';
+import { type MaterialType } from './materials.js';
+import { STANDARD_FIELDS, TEXTURE_SLOTS, TextureSlot } from './standard-fields.js';
+import type { RenderTarget } from './target.js';
+export { STANDARD_FIELDS, TEXTURE_SLOTS, TextureSlot };
+export declare const StandardMaterial: import("@aethervtt/shard-core").ComponentDef<{
+    baseColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    metallic: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    roughness: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    emissive: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    emissiveLuminance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    doubleSided: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    alphaMode: import("@aethervtt/shard-core").FieldType<"additive" | "alpha" | "mask" | "opaque" | "premultiplied", "u8">;
+    alphaCutoff: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    normalScale: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    occlusionStrength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    baseColorTexture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        uv: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        wrap: import("@aethervtt/shard-core").FieldType<"clamp" | "mirror" | "repeat", "u8">;
+        filter: import("@aethervtt/shard-core").FieldType<"linear" | "nearest", "u8">;
+    }>, "object">;
+    metallicRoughnessTexture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        uv: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        wrap: import("@aethervtt/shard-core").FieldType<"clamp" | "mirror" | "repeat", "u8">;
+        filter: import("@aethervtt/shard-core").FieldType<"linear" | "nearest", "u8">;
+    }>, "object">;
+    normalTexture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        uv: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        wrap: import("@aethervtt/shard-core").FieldType<"clamp" | "mirror" | "repeat", "u8">;
+        filter: import("@aethervtt/shard-core").FieldType<"linear" | "nearest", "u8">;
+    }>, "object">;
+    occlusionTexture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        uv: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        wrap: import("@aethervtt/shard-core").FieldType<"clamp" | "mirror" | "repeat", "u8">;
+        filter: import("@aethervtt/shard-core").FieldType<"linear" | "nearest", "u8">;
+    }>, "object">;
+    emissiveTexture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+        uv: import("@aethervtt/shard-core").FieldType<number, "u8">;
+        offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        rotation: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        wrap: import("@aethervtt/shard-core").FieldType<"clamp" | "mirror" | "repeat", "u8">;
+        filter: import("@aethervtt/shard-core").FieldType<"linear" | "nearest", "u8">;
+    }>, "object">;
+}>;
+/** The material type of plain StandardMaterial assets. */
+export declare const STANDARD_TYPE: MaterialType;
+export type StandardMaterialValue = Infer<typeof StandardMaterial>;
+/** Any material's value: the standard fields (for standard extensions) plus the type's own. */
+export type MaterialValue = StandardMaterialValue & Record<string, unknown>;
+/**
+ * A material: its type and its values, with a version so GPU copies know when to re-upload. When the
+ * type is redefined (hot reload), `sync` migrates the values: new fields get their defaults.
+ */
+export declare class MaterialAsset {
+    type: MaterialType;
+    value: MaterialValue;
+    version: number;
+    private typeVersion;
+    constructor(value?: Record<string, unknown>, type?: MaterialType);
+    set(value: Record<string, unknown>): void;
+    /** Migrates to the current definition of the type. Returns true if anything changed. */
+    sync(): boolean;
+}
+/** The type a material JSON names (`"type"`), defaulting to the standard material. */
+export declare function materialTypeOf(json: unknown): MaterialType;
+/** Material JSON without its `"type"` key (what the type's schema validates). */
+export declare function materialFields(json: unknown): Record<string, unknown>;
+/** Validates material JSON against its type's schema; errors point into the JSON. */
+export declare function validateMaterial(json: unknown, ctx?: SchemaContext): ShardError[];
+/** A MaterialAsset from material JSON (files, scene inline assets, glTF). */
+export declare function materialFromJson(json: unknown, ctx?: SchemaContext): MaterialAsset;
+export declare const Meshes: import("@aethervtt/shard-core").ResourceDef<AssetStore<Mesh, "Mesh">>;
+export declare const Materials: import("@aethervtt/shard-core").ResourceDef<AssetStore<MaterialAsset, "Material">>;
+export declare const RenderTargets: import("@aethervtt/shard-core").ResourceDef<AssetStore<RenderTarget, "RenderTarget">>;
+/** Meshes load from binary artifacts (`encodeMesh`); a reload updates the mesh in place. */
+export declare const MeshAsset: import("@aethervtt/shard-assets").AssetTypeDef<Mesh>;
+/** Materials load from material JSON (any type); a reload bumps the material's version. */
+export declare const MaterialAssetType: import("@aethervtt/shard-assets").AssetTypeDef<MaterialAsset>;
+/**
+ * `*.material.json` files. `"type"` names the material type (default: render/StandardMaterial);
+ * the rest is validated by that type's schema, with errors pointing into the file.
+ */
+export declare const MaterialImporter: import("@aethervtt/shard-assets").ImporterDef;
+export { AssetStore };

package/dist/assets.js

@@ -0,0 +1,213 @@
+import { AssetStore, defineAssetType, defineImporter } from "@aethervtt/shard-assets";
+import {
+  defineComponent,
+  defineResource,
+  defineSchema,
+  ShardError
+} from "@aethervtt/shard-core";
+import { decodeMesh } from "@aethervtt/shard-mesh";
+import {
+  allMaterialTypes,
+  findMaterialType,
+  registerStandardType
+} from "./materials.js";
+import { STANDARD_FIELDS, TEXTURE_SLOTS, TextureSlot } from "./standard-fields.js";
+const StandardMaterial = defineComponent("render/StandardMaterial", STANDARD_FIELDS, {
+  description: "The standard PBR material (GGX). A material asset, not an entity component."
+});
+const STANDARD_TYPE = registerStandardType(StandardMaterial);
+class MaterialAsset {
+  type;
+  value;
+  version = 0;
+  typeVersion;
+  constructor(value = {}, type = STANDARD_TYPE) {
+    this.type = type;
+    this.typeVersion = type.version;
+    this.value = normalize(type, { ...type.schema.defaults(), ...value });
+  }
+  set(value) {
+    this.value = normalize(this.type, { ...this.value, ...value });
+    this.version++;
+  }
+  /** Migrates to the current definition of the type. Returns true if anything changed. */
+  sync() {
+    if (this.typeVersion === this.type.version) return false;
+    this.typeVersion = this.type.version;
+    const defaults = this.type.schema.defaults();
+    const next = {};
+    for (const key of Object.keys(defaults))
+      next[key] = key in this.value ? this.value[key] : defaults[key];
+    this.value = normalize(this.type, next);
+    this.version++;
+    return true;
+  }
+}
+function normalize(type, value) {
+  return type.standard ? withSlotDefaults(value) : value;
+}
+function materialTypeOf(json) {
+  const name = json && typeof json === "object" && typeof json.type === "string" ? json.type : void 0;
+  if (!name || name === "render/StandardMaterial") return STANDARD_TYPE;
+  const type = findMaterialType(name);
+  if (!type) {
+    throw new ShardError("render/unknown-material-type", `Unknown material type "${name}"`, {
+      path: "/type",
+      hint: `Material types: ${allMaterialTypes().map((t) => t.name).join(", ")}. Project types are defined with project.material(...).`
+    });
+  }
+  return type;
+}
+function materialFields(json) {
+  if (!json || typeof json !== "object") return {};
+  const { type: _, $schema: __, ...rest } = json;
+  return rest;
+}
+function validateMaterial(json, ctx) {
+  let type;
+  try {
+    type = materialTypeOf(json);
+  } catch (err) {
+    return [err];
+  }
+  return type.schema.validate(materialFields(json), ctx);
+}
+function materialFromJson(json, ctx) {
+  const type = materialTypeOf(json);
+  return new MaterialAsset(
+    type.schema.deserialize(materialFields(json), ctx),
+    type
+  );
+}
+function withSlotDefaults(value) {
+  const defaults = StandardMaterial.defaults();
+  const out = value;
+  for (const slot of TEXTURE_SLOTS) out[slot] = { ...defaults[slot], ...out[slot] };
+  return value;
+}
+const Meshes = defineResource("render/Meshes", {
+  description: "Loaded meshes by guid.",
+  init: () => new AssetStore("Mesh")
+});
+const Materials = defineResource("render/Materials", {
+  description: "Loaded standard materials by guid.",
+  init: () => new AssetStore("Material")
+});
+const RenderTargets = defineResource(
+  "render/RenderTargets",
+  {
+    description: "Offscreen render targets cameras can render into.",
+    init: () => new AssetStore("RenderTarget")
+  }
+);
+const MeshAsset = defineAssetType("Mesh", {
+  store: Meshes,
+  load: (artifact) => decodeMesh(artifact.bytes),
+  update: (existing, next) => existing.update(next.data())
+});
+const MaterialAssetType = defineAssetType("Material", {
+  store: Materials,
+  // Texture paths resolve to guids here, so the renderer can look them up directly.
+  load: (artifact, ctx) => {
+    const resolveAsset = (ref) => {
+      const found = ref.path ? ctx.resolve(ref.path) : ref.guid ? ctx.resolve(ref.guid) : void 0;
+      return found ? { guid: found.guid, path: ref.path ?? found.path, type: found.type } : void 0;
+    };
+    const errors = validateMaterial(artifact.json, { resolveAsset });
+    if (errors.length > 0) {
+      const first = errors[0];
+      throw new ShardError("assets/load-failed", `${ctx.path}: ${first.message}`, {
+        path: first.path,
+        hint: first.hint,
+        details: errors
+      });
+    }
+    return materialFromJson(artifact.json, { resolveAsset });
+  },
+  update: (existing, next) => {
+    existing.type = next.type;
+    existing.set(next.value);
+  }
+});
+const MaterialImporter = defineImporter({
+  name: "data/material",
+  version: 2,
+  extensions: [".material.json"],
+  settings: defineSchema("render/MaterialImportSettings", {}, { description: "No settings." }),
+  async import(source, ctx) {
+    let json;
+    try {
+      json = JSON.parse(source.text());
+    } catch (cause) {
+      throw new ShardError("assets/import-failed", `${source.path} isn't valid JSON`, {
+        path: source.path,
+        cause
+      });
+    }
+    const typeName = json?.type;
+    const known = typeof typeName !== "string" || findMaterialType(typeName) !== void 0;
+    let normalized = json;
+    if (known) {
+      const errors = validateMaterial(json);
+      if (errors.length > 0) {
+        const first = errors[0];
+        throw new ShardError(
+          "assets/import-failed",
+          `${source.path}: ${first.message}${errors.length > 1 ? ` (+${errors.length - 1} more)` : ""}`,
+          { path: first.path, hint: first.hint, details: errors }
+        );
+      }
+      const type = materialTypeOf(json);
+      const fields = type.schema.serialize(type.schema.deserialize(materialFields(json)));
+      normalized = type === STANDARD_TYPE ? fields : { type: type.name, ...fields };
+    } else {
+      ctx.warn(
+        `Material type "${typeName}" isn't defined here; it's checked when the game loads it.`,
+        "/type"
+      );
+      normalized = materialFields(json);
+      normalized = { type: typeName, ...normalized };
+    }
+    const dependencies = /* @__PURE__ */ new Set();
+    const collect = (value) => {
+      if (Array.isArray(value)) value.forEach(collect);
+      else if (value && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+          if (k === "path" && typeof v === "string" && !v.startsWith("procedural:"))
+            dependencies.add(v);
+          else collect(v);
+        }
+      }
+    };
+    collect(normalized);
+    return {
+      assets: [
+        {
+          label: "",
+          type: "Material",
+          json: normalized,
+          ...dependencies.size ? { dependencies: [...dependencies] } : {}
+        }
+      ]
+    };
+  }
+});
+export {
+  AssetStore,
+  MaterialAsset,
+  MaterialAssetType,
+  MaterialImporter,
+  Materials,
+  MeshAsset,
+  Meshes,
+  RenderTargets,
+  STANDARD_FIELDS,
+  STANDARD_TYPE,
+  StandardMaterial,
+  TEXTURE_SLOTS,
+  TextureSlot,
+  materialFields,
+  materialFromJson,
+  materialTypeOf,
+  validateMaterial
+};

package/dist/atmosphere-model.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The atmosphere model on the CPU (spec 0044): the same density profiles, transmittance, and
+ * multiple-scattering approximation (Hillaire 2020) the shaders in `atmosphere-shaders.ts` use, so
+ * sun light, `sunTransmittanceAt`, and `atmosphere.sample` work headless and agree with the GPU.
+ *
+ * Everything is in kilometres, relative to the atmosphere's center. Coefficients are per km.
+ */
+/** Atmosphere parameters in shader units (km, 1/km). */
+export interface AtmosphereModel {
+    /** Visible surface (or cloud top), top of the atmosphere, and the LUTs' floor (bottom − deck). */
+    bottom: number;
+    top: number;
+    ground: number;
+    rayleigh: Float64Array;
+    rayleighInvScale: number;
+    mieScattering: number;
+    mieAbsorption: number;
+    mieInvScale: number;
+    /** Per channel Cornette-Shanks asymmetry. */
+    mieG: Float64Array;
+    absorption: Float64Array;
+    absorptionCenter: number;
+    absorptionWidth: number;
+    albedo: Float64Array;
+    intensity: number;
+}
+export declare function createModel(): AtmosphereModel;
+export declare const TRANSMITTANCE_W = 256;
+export declare const TRANSMITTANCE_H = 64;
+export declare const MULTISCATTER_SIZE = 32;
+/** Steps for the transmittance LUT and for sun transmittance on the CPU. */
+export declare const TRANSMITTANCE_STEPS = 40;
+/** Scratch medium: scattering and extinction at a point. */
+export interface Medium {
+    rayleigh: Float64Array;
+    mie: number;
+    scattering: Float64Array;
+    extinction: Float64Array;
+}
+export declare function createMedium(): Medium;
+/** The medium at altitude `h` km above the bottom (negative inside a gas giant's deck). */
+export declare function mediumAt(m: AtmosphereModel, h: number, out: Medium): Medium;
+/** Near and far distances along a unit ray to a sphere at the origin; NaN when it misses. */
+export declare function raySphere(ox: number, oy: number, oz: number, dx: number, dy: number, dz: number, r: number, out: Float64Array): boolean;
+/**
+ * Transmittance from a point along a unit direction to the top of the atmosphere, integrated in
+ * `steps` midpoint steps. Zero when the ground (the LUT floor) is in the way.
+ */
+export declare function transmittanceToTop(m: AtmosphereModel, px: number, py: number, pz: number, dx: number, dy: number, dz: number, out: Float64Array, steps?: number): Float64Array;
+/** Transmittance LUT unit coordinates (x_mu, x_r) of altitude radius r and view zenith cosine mu. */
+export declare function transmittanceUnit(m: AtmosphereModel, r: number, mu: number, out: Float64Array): Float64Array<ArrayBufferLike>;
+/** The inverse: (r, mu) of transmittance LUT unit coordinates. */
+export declare function transmittanceRMu(m: AtmosphereModel, xMu: number, xR: number, out: Float64Array): Float64Array<ArrayBufferLike>;
+/** A LUT of `w × h` rgb texels, sampled bilinearly with texel centers at unit 0 and 1. */
+export interface Lut {
+    width: number;
+    height: number;
+    data: Float32Array;
+}
+/** The transmittance LUT, computed like `shard::atmosphere::transmittance_lut`. */
+export declare function transmittanceLut(m: AtmosphereModel): Lut;
+/** Transmittance from radius r toward zenith cosine mu, from the LUT (the ground is not tested). */
+export declare function lookupTransmittance(m: AtmosphereModel, lut: Lut, r: number, mu: number, out: Float64Array): Float64Array;
+/**
+ * Hillaire's multiple-scattering LUT: for each altitude and sun zenith, the isotropic
+ * second-order luminance L2 over 64 directions and the transfer f_ms, stored as L2 / (1 − f_ms)
+ * (per unit illuminance, per unit scattering).
+ */
+export declare function multiscatterLut(m: AtmosphereModel, tlut: Lut): Lut;
+/** Multiple-scattering luminance factor at radius r for a sun at zenith cosine cs. */
+export declare function lookupMultiscatter(m: AtmosphereModel, lut: Lut, r: number, cs: number, out: Float64Array): Float64Array;
+/** Rayleigh phase. */
+export declare const rayleighPhase: (mu: number) => number;
+/** Cornette-Shanks phase with asymmetry g. */
+export declare function miePhase(mu: number, g: number): number;
+/** A sun as the model sees it: direction toward it (unit) and illuminance (lux) per channel. */
+export interface ModelSun {
+    direction: ArrayLike<number>;
+    illuminance: ArrayLike<number>;
+}
+export interface SkySample {
+    /** In-scattered radiance (cd/m²) along the ray, plus the lit ground where it ends on it. */
+    radiance: Float64Array;
+    /** Transmittance along the ray to where it leaves the atmosphere (0 if it hits the ground). */
+    transmittance: Float64Array;
+    hitsGround: boolean;
+    /** Distance (km) the ray travels through the atmosphere. */
+    length: number;
+}
+export declare function createSkySample(): SkySample;
+/**
+ * Radiance along a ray from `p` (km, relative to the center) in unit direction `d`, up to
+ * `maxT` km: single scattering of every sun, the multiple-scattering LUT, and the lit ground.
+ * Same integration as `shard::atmosphere::integrate` (quadratic step distribution).
+ */
+export declare function integrateSky(m: AtmosphereModel, tlut: Lut, mslut: Lut, p: ArrayLike<number>, d: ArrayLike<number>, suns: readonly ModelSun[], out: SkySample, steps?: number, maxT?: number): SkySample;