@aethervtt/shard-terrain 0.1.0 → 0.2.1

package/dist/heightfield/source-asset.js

@@ -0,0 +1,372 @@
+import {
+  AssetStore,
+  defineAssetSchema,
+  defineAssetType,
+  defineImporter,
+  sha256Hex
+} from "@aethervtt/shard-assets";
+import { defineResource, defineSchema, ShardError } from "@aethervtt/shard-core";
+import {
+  parseTerrainSource,
+  sourceDependencies,
+  terrainLayout
+} from "./source.js";
+class TerrainSourceAsset {
+  source;
+  layout;
+  deps;
+  hash;
+  /** Bumps on hot reload. */
+  version = 0;
+  constructor(a) {
+    this.source = a.source;
+    this.layout = a.layout;
+    this.deps = a.deps;
+    this.hash = a.hash;
+  }
+}
+const TerrainSources = defineResource("terrain/TerrainSources", {
+  description: "Loaded heightfield terrain sources (*.terrain.json) by guid.",
+  init: () => new AssetStore("terrain/TerrainSource")
+});
+const TerrainSourceAssetType = defineAssetType("terrain/TerrainSource", {
+  store: TerrainSources,
+  load: (artifact) => new TerrainSourceAsset(artifact.json),
+  update: (existing, next) => {
+    existing.source = next.source;
+    existing.layout = next.layout;
+    existing.deps = next.deps;
+    existing.hash = next.hash;
+    existing.version++;
+  },
+  references: (item) => Object.values(item.deps).filter((d) => d.type === "Texture").map((d) => ({ guid: d.guid }))
+});
+const NoSettings = defineSchema(
+  "terrain/TerrainSourceSettings",
+  {},
+  { description: "None: the terrain is the file." }
+);
+const EXPECTED = {
+  noise: "NoiseGraph",
+  heightmaps: "Heightmap",
+  textures: "Texture"
+};
+const TerrainSourceImporter = defineImporter({
+  name: "terrain",
+  version: 2,
+  extensions: [".terrain.json"],
+  settings: NoSettings,
+  async import(file, ctx) {
+    let json;
+    try {
+      json = JSON.parse(file.text());
+    } catch (cause) {
+      throw new ShardError("assets/import-failed", `${file.path} isn't valid JSON`, {
+        path: file.path,
+        cause
+      });
+    }
+    const source = parseTerrainSource(json);
+    const layout = terrainLayout(source);
+    const deps = {};
+    const lists = sourceDependencies(source);
+    for (const [kind, paths] of Object.entries(lists)) {
+      for (const path of paths) {
+        const dep = await ctx.asset(path);
+        if (dep.type !== EXPECTED[kind]) {
+          throw new ShardError(
+            kind === "heightmaps" ? "terrain/heightmap-format" : "terrain/bad-source",
+            `${path} is a ${dep.type}, not a ${EXPECTED[kind]}`,
+            {
+              path,
+              hint: kind === "heightmaps" ? 'Image layers and masks read Heightmaps: a 16-bit grayscale PNG with "importer": "heightmap" in its .meta (or named *.height.png), or a .r16/.r32 file.' : `Point it at a ${EXPECTED[kind]}.`
+            }
+          );
+        }
+        deps[path] = { guid: dep.guid, type: dep.type, hash: dep.hash };
+      }
+    }
+    const fill = (r) => {
+      if (r && deps[r.path]) r.guid = deps[r.path].guid;
+    };
+    for (const l of source.height) {
+      if (l.kind === "noise") fill(l.noise);
+      if (l.kind === "image") fill(l.image);
+    }
+    for (const p of source.paint) {
+      fill(p.noise?.ref ?? null);
+      fill(p.mask?.ref ?? null);
+    }
+    fill(source.textures.albedo);
+    fill(source.textures.normal);
+    fill(source.textures.orm);
+    const hash = await sha256Hex(
+      new TextEncoder().encode(JSON.stringify({ source, deps: Object.entries(deps).sort() }))
+    );
+    const artifact = { format: 1, source, layout, deps, hash };
+    return {
+      assets: [
+        {
+          label: "",
+          type: "terrain/TerrainSource",
+          json: artifact,
+          dependencies: Object.keys(deps),
+          info: {
+            size: source.size,
+            spacing: source.spacing,
+            roots: layout.rootsX * layout.rootsZ,
+            depth: layout.depth,
+            blocks: layout.blocksX * layout.blocksZ,
+            heightLayers: source.height.length,
+            materialLayers: source.layers.length
+          }
+        }
+      ]
+    };
+  }
+});
+const num = (description, extra = {}) => ({
+  type: "number",
+  description,
+  ...extra
+});
+const pairOf = (description, examples) => ({
+  type: "array",
+  items: { type: "number" },
+  minItems: 2,
+  maxItems: 2,
+  description,
+  examples
+});
+const refOf = (description, example) => ({
+  type: "object",
+  properties: { path: { type: "string", minLength: 1 }, guid: { type: "string" } },
+  required: ["path"],
+  description,
+  examples: [{ path: example }]
+});
+const rect = {
+  at: pairOf("Center of the rectangle, [x, z] metres from the terrain\u2019s corner.", [[2048, 1800]]),
+  size: pairOf("Width (along X before rotation) and depth (along Z), metres.", [[1200, 900]]),
+  rotation: num("Degrees about +Y (right-handed: positive turns +X toward \u2212Z). Default 0.", {
+    examples: [20]
+  })
+};
+const blend = {
+  enum: ["add", "max", "min", "replace"],
+  description: "How the layer combines with the height below, mixed by its falloff mask: add (default for noise), max, min, replace (default for images)."
+};
+function terrainJsonSchema() {
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "Heightfield terrain (spec 0071)",
+    description: "A bounded landscape as an ordered stack of height layers (noise, heightmap images, splines that flatten, raise or carve) and paint layers (material weights by height, slope, noise, masks and splines). `shard import` (or the first run) bakes it into page packs in .shard/cache/terrain; a Terrain component on an entity draws, streams and collides with it. Coordinates are metres from the terrain\u2019s corner, x along +X and z along +Z.",
+    type: "object",
+    properties: {
+      $schema: { type: "string" },
+      size: pairOf(
+        "Size [x, z] in metres, 256 m \u2013 64 km a side, a whole number of roots: 64 \xD7 spacing \xD7 2^k, at most 64 roots (2048, 4096, 16384 at 1 m spacing).",
+        [[4096, 4096]]
+      ),
+      spacing: num("Leaf sample spacing (m), 0.25\u20134. 1 for most open worlds, 0.5 for detail.", {
+        minimum: 0.25,
+        maximum: 4,
+        examples: [1]
+      }),
+      paintSpacing: num("Control (paint) sample spacing: 1, 2 (default) or 4 times spacing.", {
+        examples: [2]
+      }),
+      heightRange: pairOf(
+        "Lowest and highest height the bake stores (m); heights are 16-bit over it, so a 1 km range keeps 1.5 cm steps. A baked height outside it clips and is reported as terrain/out-of-range.",
+        [[-200, 800]]
+      ),
+      seed: num("Mixed into every noise layer and mask: the same graphs make another terrain.", {
+        examples: [7]
+      }),
+      splines: {
+        type: "object",
+        description: "Named splines (Catmull-Rom through their points): height layers flatten, raise or carve along them; paint layers paint along them; scatter can avoid them.",
+        additionalProperties: {
+          type: "object",
+          properties: {
+            points: {
+              type: "array",
+              minItems: 2,
+              items: {
+                type: "array",
+                minItems: 3,
+                maxItems: 3,
+                items: [
+                  { type: "number" },
+                  { anyOf: [{ type: "number" }, { const: "ground" }] },
+                  { type: "number" }
+                ]
+              },
+              description: '[x, y, z] points; y may be "ground": the height of the layers below the one using the spline at that point.',
+              examples: [
+                [
+                  [120, "ground", 300],
+                  [900, 40, 420]
+                ]
+              ]
+            },
+            width: num("Full width of the flat part (m).", { examples: [8] }),
+            falloff: num("Metres beyond the width over which a height layer using it fades out.", {
+              examples: [14]
+            })
+          },
+          required: ["points", "width"],
+          additionalProperties: false
+        }
+      },
+      height: {
+        type: "array",
+        description: "Height layers, applied in order from 0 m.",
+        items: {
+          oneOf: [
+            {
+              type: "object",
+              description: "Noise (0041) over the whole terrain, or over a rectangle with a falloff.",
+              properties: {
+                noise: refOf("A noise graph.", "noise/hills.noise.json"),
+                scale: num("Metres per unit of the graph\u2019s output (default 1).", {
+                  examples: [260]
+                }),
+                offset: num("Metres added after scaling (default 0)."),
+                blend,
+                falloff: num("Metres outside the rectangle over which it fades (default 0)."),
+                ...rect
+              },
+              required: ["noise"],
+              additionalProperties: false
+            },
+            {
+              type: "object",
+              description: "A heightmap image over a rotated rectangle.",
+              properties: {
+                image: refOf(
+                  "A Heightmap (16-bit grayscale PNG, .r16 or .r32).",
+                  "terrain/valley.height.png"
+                ),
+                range: pairOf("Metres the image\u2019s 0 and 1 map to.", [[0, 140]]),
+                blend,
+                falloff: num("Metres outside the rectangle over which it fades (default 0).", {
+                  examples: [80]
+                }),
+                ...rect
+              },
+              required: ["image", "at", "size", "range"],
+              additionalProperties: false
+            },
+            {
+              type: "object",
+              description: "A spline: flatten to its height, raise up to it (embankments), or carve down to it (cuttings, river beds).",
+              properties: {
+                spline: { type: "string", description: 'A name from "splines".' },
+                mode: { enum: ["flatten", "raise", "carve"], description: "Default flatten." },
+                offset: num("Metres added to the spline\u2019s height (a carve\u2019s depth: \u22122)."),
+                falloff: num("Overrides the spline\u2019s falloff for this layer.")
+              },
+              required: ["spline"],
+              additionalProperties: false
+            }
+          ]
+        }
+      },
+      layers: {
+        type: "array",
+        maxItems: 32,
+        description: "Material layers (at most 32), sampled from the texture arrays.",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Paint layers name it.", examples: ["grass"] },
+            albedo: num("Layer of the albedo array (default: this layer\u2019s index)."),
+            normal: num("Layer of the normal array (default: albedo\u2019s)."),
+            orm: num("Layer of the ORM array (default: albedo\u2019s)."),
+            scale: num("Metres one texture repeat covers (default 4).", { examples: [4] }),
+            triplanar: {
+              type: "boolean",
+              description: "Projected from three axes where the slope passes 45\xB0 (rock on cliffs)."
+            },
+            tint: {
+              type: "array",
+              items: { type: "number" },
+              minItems: 3,
+              maxItems: 3,
+              description: "Linear RGB multiplying the albedo, and the whole color when the terrain has no texture arrays (default: a palette by index: grass, rock, gravel, sand, snow\u2026).",
+              examples: [[0.16, 0.3, 0.08]]
+            }
+          },
+          required: ["name"],
+          additionalProperties: false
+        }
+      },
+      textures: {
+        type: "object",
+        description: "Texture arrays (0043\u2019s *.texarray.json), one layer per surface texture.",
+        properties: {
+          albedo: refOf("Albedo array.", "terrain/albedo.texarray.json"),
+          normal: refOf("Normal map array.", "terrain/normal.texarray.json"),
+          orm: refOf("Occlusion / roughness / metallic array.", "terrain/orm.texarray.json")
+        },
+        additionalProperties: false
+      },
+      paint: {
+        type: "array",
+        description: "Paint layers, in order: the first is the base; each later one paints its layer over what\u2019s below where all its masks pass.",
+        items: {
+          type: "object",
+          properties: {
+            layer: { type: "string", description: "A material layer\u2019s name." },
+            height: pairOf("Where the height is in [min, max] (m).", [[600, 2e3]]),
+            slope: pairOf("Where the slope is in [min, max] degrees (0 flat, 90 a cliff).", [
+              [32, 90]
+            ]),
+            noise: {
+              ...refOf("A noise graph above a threshold.", "noise/patches.noise.json"),
+              properties: {
+                path: { type: "string" },
+                guid: { type: "string" },
+                above: num("Paints where the graph is above this (default 0).", {
+                  examples: [0.2]
+                })
+              }
+            },
+            mask: {
+              type: "object",
+              description: "A Heightmap over a rectangle: paints by its value (0\u20131).",
+              properties: {
+                path: { type: "string" },
+                guid: { type: "string" },
+                ...rect
+              },
+              required: ["path", "at", "size"]
+            },
+            spline: {
+              type: "string",
+              description: "Paints along a spline, out to half its width."
+            },
+            blend: num(
+              "Softens the masks\u2019 edges: metres for height, masks and splines, degrees for slope (default 0, hard).",
+              { examples: [6] }
+            )
+          },
+          required: ["layer"],
+          additionalProperties: false
+        }
+      }
+    },
+    required: ["size", "spacing", "heightRange", "height"],
+    additionalProperties: false
+  };
+}
+const terrainSchema = defineAssetSchema("terrain.schema.json", terrainJsonSchema);
+export {
+  TerrainSourceAsset,
+  TerrainSourceAssetType,
+  TerrainSourceImporter,
+  TerrainSources,
+  terrainJsonSchema,
+  terrainSchema
+};

package/dist/heightfield/source.d.ts

@@ -0,0 +1,151 @@
+/** Most material layers a terrain may have (the control page stores a layer in a byte; 0043's arrays hold 32). */
+export declare const MAX_MATERIAL_LAYERS = 32;
+/** Sides from 256 m to 64 km; sample spacing from 0.25 to 4 m. */
+export declare const MIN_SIZE = 256;
+export declare const MAX_SIZE = 65536;
+export declare const MIN_SPACING = 0.25;
+export declare const MAX_SPACING = 4;
+/** Roots a terrain may have, at most (the importer picks the root depth to stay under it). */
+export declare const MAX_ROOTS = 64;
+/** Deepest root depth: a block's samples hold every level's lattice up to 2^10. */
+export declare const MAX_DEPTH = 10;
+export type BlendOp = 'add' | 'max' | 'min' | 'replace';
+export type SplineMode = 'flatten' | 'raise' | 'carve';
+/** An asset reference in a terrain file: by path, and its guid once imported. */
+export interface SourceRef {
+    path: string;
+    guid?: string;
+}
+/** A rotated rectangle on the terrain: center, size (width along X before rotation, depth along Z), degrees about +Y. */
+export interface SourceRect {
+    at: [number, number];
+    size: [number, number];
+    rotation: number;
+}
+export interface SourceSpline {
+    /** [x, y, z] in terrain metres; y may be "ground" (the stack's height below the layer using it). */
+    points: [number, number | 'ground', number][];
+    /** Full width of the flat part (m). */
+    width: number;
+    /** Metres past the width over which a layer using it fades out. */
+    falloff: number;
+}
+export type SourceHeightLayer = ({
+    kind: 'noise';
+    noise: SourceRef;
+    /** Metres per unit of the graph's output. */
+    scale: number;
+    offset: number;
+    blend: BlendOp;
+    falloff: number;
+} & {
+    region: SourceRect | null;
+}) | ({
+    kind: 'image';
+    image: SourceRef;
+    /** Metres the image's 0 and 1 map to. */
+    range: [number, number];
+    blend: BlendOp;
+    falloff: number;
+} & SourceRect) | {
+    kind: 'spline';
+    spline: string;
+    mode: SplineMode;
+    /** Metres added to the spline's height (a carve's depth below it, say). */
+    offset: number;
+    /** The spline's falloff unless set here. */
+    falloff: number;
+};
+export interface SourceMaterialLayer {
+    name: string;
+    /** Layers of the texture arrays (0043's `*.texarray.json`): albedo, and normal and ORM (default: the albedo's). */
+    albedo: number;
+    normal: number;
+    orm: number;
+    /** Metres one texture repeat covers. */
+    scale: number;
+    /** Projected from three axes where the slope passes 45° (cliffs). */
+    triplanar: boolean;
+    /** Linear RGB multiplying the albedo; the whole color without texture arrays. */
+    tint: [number, number, number];
+}
+/** Tints for layers that don't set one, by index: grass, rock, gravel, sand, snow, soil, … */
+export declare const LAYER_TINTS: [number, number, number][];
+export interface SourcePaint {
+    /** Material layer name. */
+    layer: string;
+    height: [number, number] | null;
+    slope: [number, number] | null;
+    noise: {
+        ref: SourceRef;
+        above: number;
+    } | null;
+    mask: ({
+        ref: SourceRef;
+    } & SourceRect) | null;
+    spline: string | null;
+    /** Edge softness: metres for height, masks and splines; degrees for slope. */
+    blend: number;
+}
+/** A terrain source (`*.terrain.json`) after validation, with every default filled in. */
+export interface TerrainSource {
+    size: [number, number];
+    spacing: number;
+    paintSpacing: number;
+    heightRange: [number, number];
+    seed: number;
+    splines: Record<string, SourceSpline>;
+    height: SourceHeightLayer[];
+    layers: SourceMaterialLayer[];
+    textures: {
+        albedo: SourceRef | null;
+        normal: SourceRef | null;
+        orm: SourceRef | null;
+    };
+    paint: SourcePaint[];
+}
+/** The terrain's grid (spec 0071): roots, depths, blocks, and paint cells. */
+export interface TerrainLayout {
+    sizeX: number;
+    sizeZ: number;
+    spacing: number;
+    paintSpacing: number;
+    /** Leaf samples per paint sample. */
+    paintStep: number;
+    /** Paint cells per page side (control pages hold cells + 1 texels a side). */
+    cells: number;
+    /** Leaves are at this depth; roots at 0. */
+    depth: number;
+    rootsX: number;
+    rootsZ: number;
+    /** Metres a root covers. */
+    rootSize: number;
+    /** Metres a leaf covers. */
+    leafSize: number;
+    leavesX: number;
+    leavesZ: number;
+    /** Leaves per block side (BLOCK), and the levels each block bakes itself above its leaves. */
+    block: number;
+    blocksX: number;
+    blocksZ: number;
+    blockLevels: number;
+}
+/**
+ * Validates a terrain file's JSON and fills in defaults. Throws a ShardError whose path is a JSON
+ * pointer into the file: `terrain/bad-size`, `terrain/bad-spacing`, `terrain/unknown-spline`,
+ * `terrain/unknown-layer`, `terrain/too-many-layers`, or `terrain/bad-source` for anything else.
+ */
+export declare function parseTerrainSource(json: unknown): TerrainSource;
+/**
+ * The terrain's grid (spec 0071): leaves of PAGE segments at `spacing`, roots at the shallowest
+ * depth giving at most MAX_ROOTS of them, and blocks of `block` × `block` leaves (a power of two;
+ * BLOCK but in tests). Throws `terrain/bad-size` when a side is outside 256 m – 64 km or isn't a
+ * whole number of roots.
+ */
+export declare function terrainLayout(source: Pick<TerrainSource, 'size' | 'spacing' | 'paintSpacing'>, block?: number): TerrainLayout;
+/** Every asset a source refers to, by path: noise graphs, heightmaps (images and masks), texture arrays. */
+export declare function sourceDependencies(source: TerrainSource): {
+    noise: string[];
+    heightmaps: string[];
+    textures: string[];
+};