@adatechnology/game-terrain 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anderson Fernandes
+
+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,28 @@
-# Temporary Holding Version
+# @adatechnology/game-terrain
 
-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.
+Deformable ground with no three.js in it: a height field in chunks where every column has strata, each stratum a material of the destruction catalogue.
+
+```ts
+import { createTerrain, createTerrainImpl } from '@adatechnology/game-terrain'
+
+const terrain = createTerrain({ bounds: [-50, -50, 50, 50], layout: { surface: 'lawn', zones: [{ rect: [-50, -4, 50, 4], surface: 'road' }] } })
+world.register(createTerrainImpl(terrain, { id: 'ground' })) // shots, blows, blasts and flames of the destruction world reach it
+terrain.heightAt(x, z) // what things stand on
+```
+
+## What it does
+
+- **Profiles** (`TERRAIN_PROFILES`, replace or add through `profiles`): `lawn` (turf 5 cm, soil 1.5 m, rock), `dirt`, `sand`, `road` (asphalt 5 cm, gravel, soil), `concrete_slab` (12 cm with rebar at 3 cm), `tile_floor` (tile, mortar, slab), `wood_floor`, `stone_paving`.
+- **Digging**: a blow removes `energy / specificEnergy` cubic metres (`TERRAIN_MATERIALS`, per blow type: ballistic, blunt, slash, explosive) as a bowl with the shape of the material. It takes the top stratum and spends what is left on the next. The strata end at the digging limit: **a slab is never pierced**, and a crater has a floor.
+- **Bars**: bare bars bend with each blow and give way at `yieldJoules`. A slab on the ground stays the floor; `suspended_slab` (`TerrainProfile.drop`) opens onto the floor below.
+- **Fine marks**: a bowl under 1.5 cells stays a mark, not a change of the height field. Blows on the same mark grow it until it is dug in.
+- **Budget** (`budget`): marks per area and in total (past it the closest two merge, then the oldest goes), thrown pieces, chunks redrawn per frame, cells checked for sliding, cells on fire.
+- **What comes out**: soft ground heaps a rim and throws clods that land and join the height field, so they can be walked over; rigid material throws chips that stay as rubble. Loose ground slides to its angle of repose.
+- **Fire**: `fire` of each material says how black it gets and whether it burns away and spreads: turf and wood char and carry the fire, concrete only soots.
+- `serialize()` / `load()`: only what changed, as plain JSON.
+
+Draw it with [`@adatechnology/game-terrain-three`](../game-terrain-three). The test room's floor is one of these.
+
+## Português
+
+Chão deformável: mapa de altura em chunks com estratos por coluna, cada estrato um material do catálogo de destruição. O golpe escava o estrato de cima e só passa ao de baixo quando ele acaba; a laje no chão nunca é atravessada e a cratera tem fundo. Vergalhão exposto entorta a cada golpe e cede; laje sobre vão (`suspended_slab`) abre para o andar de baixo. Marcas finas de tiro com limite por área (fundem, depois reciclam a mais antiga); a terra removida vira borda e torrões que caem e somam na altura; areia escorrega até o ângulo de repouso; grama e madeira carbonizam e o fogo se espalha, concreto só escurece.

package/dist/index.d.ts

@@ -0,0 +1,295 @@
+import { GroundLayout, Hit, DestructibleImpl } from '@adatechnology/game-contracts';
+export { GroundLayout, GroundZone } from '@adatechnology/game-contracts';
+
+/** The blows that remove ground. Fire and heat char it instead (`TerrainMaterial.fire`). */
+type TerrainBlow = 'ballistic' | 'blunt' | 'slash' | 'explosive';
+/** What one kind of blow does to a material. */
+interface TerrainBlowResponse {
+    /** Joules it takes to remove one cubic metre. */
+    readonly specificEnergy: number;
+    /** Depth over radius of the bowl it leaves: a soft ground craters deep, a hard one spalls wide and shallow. */
+    readonly aspect: number;
+    /** A blow under this many joules leaves nothing (a punch on a slab). */
+    readonly thresholdJoules?: number;
+    /** The bowl is never narrower: a tile comes off as a piece, not as the size of the bullet. */
+    readonly minRadius?: number;
+}
+type TerrainDebrisKind = 'clods' | 'chips' | 'shards' | 'splinters' | 'dust';
+/** How a material of the destruction catalogue behaves as ground. `id` is the catalogue's. */
+interface TerrainMaterial {
+    readonly id: string;
+    readonly hits: Partial<Record<TerrainBlow, TerrainBlowResponse>>;
+    readonly debris: TerrainDebrisKind;
+    /** Share of what a blow removes that piles up on the rim; the rest is thrown. Rigid materials have none. */
+    readonly rimShare?: number;
+    /** Steepest slope in degrees it holds; loose ground slides until it is back to it. */
+    readonly reposeDegrees?: number;
+    readonly fire?: TerrainFireResponse;
+    /** Linear rgb, 0..1, of the material where it is exposed. */
+    readonly color: readonly [number, number, number];
+    /** Surface pattern a renderer draws while the stratum is intact (`TERRAIN_PATTERNS`). */
+    readonly pattern?: TerrainPattern;
+}
+interface TerrainFireResponse {
+    /** How black it gets, 0..1: concrete only soots, wood and turf char through. */
+    readonly maxScorch: number;
+    /** Scorch gained per second in a flame. */
+    readonly scorchPerSecond: number;
+    /** Metres per second the flame eats away (wood char). */
+    readonly burnsAway?: number;
+    /** Catches and carries the fire to the next cells on its own. */
+    readonly flammable?: boolean;
+}
+declare const TERRAIN_PATTERNS: readonly ["plain", "grass", "soil", "sand", "asphalt", "concrete", "tile", "planks", "stone"];
+type TerrainPattern = (typeof TERRAIN_PATTERNS)[number];
+/** One layer of a column, from the top down. */
+interface TerrainStratum {
+    /** A `TerrainMaterial.id`. */
+    readonly material: string;
+    /** Metres. */
+    readonly thickness: number;
+    /** Bars inside the layer: exposed at `cover`, they make the digging `resistance` times harder. */
+    readonly reinforcement?: {
+        readonly material: string;
+        readonly cover: number;
+        readonly spacing: number;
+        readonly resistance: number;
+        /** Joules on one spot of bare bars before they give way (default `DEFAULT_BAR_YIELD_JOULES`). */
+        readonly yieldJoules?: number;
+    };
+}
+/** What a column of ground is made of. The strata end at the digging limit: under them nothing is removed. */
+interface TerrainProfile {
+    readonly id: string;
+    readonly strata: readonly TerrainStratum[];
+    /** A slab with nothing under it: where its bars give way the floor opens, and the ground is this many metres further down (the floor below). Without it the ground under the slab holds it up. */
+    readonly drop?: number;
+}
+interface TerrainBudget {
+    /** Side in metres of the squares that hold a limited number of marks. */
+    readonly markAreaSize: number;
+    readonly maxMarksPerArea: number;
+    readonly maxMarks: number;
+    /** Chunks a renderer redraws per frame; the rest wait. */
+    readonly maxDirtyChunksPerFrame: number;
+    readonly maxDebris: number;
+    /** Thrown pieces of one blow. */
+    readonly maxDebrisPerBlow: number;
+    /** Cells checked for sliding per frame. */
+    readonly maxSlideCellsPerFrame: number;
+    /** Cells on fire at once. */
+    readonly maxBurningCells: number;
+}
+interface TerrainOptions {
+    /** World rectangle `[x0, z0, x1, z1]` in metres. */
+    readonly bounds: readonly [number, number, number, number];
+    /** Metres per cell (default 0.1). */
+    readonly cellSize?: number;
+    /** Cells per side of a chunk (default 32). */
+    readonly chunkCells?: number;
+    /** Which profile is where. */
+    readonly layout?: GroundLayout;
+    /** Extra or overriding profiles, by id. */
+    readonly profiles?: readonly TerrainProfile[];
+    /** Extra or overriding materials, by id. */
+    readonly materials?: readonly TerrainMaterial[];
+    readonly budget?: Partial<TerrainBudget>;
+    /** Height of the untouched ground (default flat at 0). */
+    readonly baseHeight?: (x: number, z: number) => number;
+    /** Metres per second squared. */
+    readonly gravity?: number;
+    readonly seed?: number;
+}
+/** A fine mark: a bullet pock or a chip, smaller than a cell. It grows with the blows on it until it is dug into the height field. */
+interface TerrainMark {
+    readonly id: number;
+    x: number;
+    z: number;
+    radius: number;
+    depth: number;
+    /** The material the mark shows at the bottom. */
+    material: string;
+    blow: TerrainBlow;
+    /** Blows and marks merged into this one. */
+    count: number;
+    /** Order of creation: the oldest is the one recycled. */
+    born: number;
+}
+interface TerrainDebris {
+    readonly id: number;
+    readonly material: string;
+    readonly kind: TerrainDebrisKind;
+    readonly radius: number;
+    readonly position: [number, number, number];
+    readonly velocity: [number, number, number];
+    readonly spin: [number, number, number];
+    atRest: boolean;
+    bounces: number;
+    /** Order of creation: the oldest is the one recycled. */
+    readonly born: number;
+}
+/** What a blow did. */
+interface TerrainBlowResult {
+    readonly point: readonly [number, number, number];
+    /** Bowl radius in metres; 0 when the blow left nothing. */
+    readonly radius: number;
+    /** Metres removed at the point. */
+    readonly depth: number;
+    /** Metres under the untouched surface the point is now. */
+    readonly totalDepth: number;
+    /** Materials removed, top first, with the cubic metres of each. */
+    readonly removed: readonly {
+        readonly material: string;
+        readonly volume: number;
+    }[];
+    /** Material now exposed at the point. */
+    readonly exposed: string;
+    /** The column has no more to give here: the slab's bottom, the end of the rock. */
+    readonly atLimit: boolean;
+    /** Reinforcement is showing at the point. */
+    readonly rebarExposed: boolean;
+    /** The bars gave way here and the slab opened (`TerrainProfile.drop`). */
+    readonly collapsed: boolean;
+    /** Left a fine mark (`true`) or dug the height field (`false`). */
+    readonly fine: boolean;
+}
+interface TerrainRegion {
+    readonly x: number;
+    readonly z: number;
+    readonly radius: number;
+}
+interface TerrainColumn {
+    readonly profile: string;
+    readonly material: string;
+    readonly stratum: number;
+    /** Metres under the untouched surface. */
+    readonly depth: number;
+    /** Metres that can still be dug here. */
+    readonly remaining: number;
+    readonly scorch: number;
+    readonly loose: number;
+}
+interface TerrainStats {
+    readonly marks: number;
+    readonly debris: number;
+    readonly debrisMoving: number;
+    readonly dirtyChunks: number;
+    readonly burning: number;
+}
+interface TerrainChunk {
+    readonly index: number;
+    /** First column and row of the chunk's vertices. */
+    readonly column: number;
+    readonly row: number;
+    readonly cells: number;
+    /** True while nothing touched it and it has one profile: one flat quad draws it. */
+    readonly pristine: boolean;
+}
+interface Terrain {
+    readonly bounds: readonly [number, number, number, number];
+    readonly cellSize: number;
+    readonly columns: number;
+    readonly rows: number;
+    /** Vertices per row. */
+    readonly stride: number;
+    readonly chunkCells: number;
+    readonly chunksX: number;
+    readonly chunksZ: number;
+    readonly budget: TerrainBudget;
+    /** Per vertex: metres removed under the untouched surface. */
+    readonly dug: Float32Array;
+    /** Per vertex: metres of loose ground heaped on top. */
+    readonly loose: Float32Array;
+    /** Per vertex: 0..1, how burnt. */
+    readonly scorch: Float32Array;
+    /** Per vertex: how far the bare bars have given, 0 straight, 1 or more gone. */
+    readonly barBend: Float32Array;
+    /** Per vertex: index in `profileList`. */
+    readonly profileIndex: Uint8Array;
+    readonly profileList: readonly TerrainProfile[];
+    material(id: string): TerrainMaterial;
+    layout(): GroundLayout;
+    setLayout(layout: GroundLayout): void;
+    /** Height at (x, z) as things stand on it. */
+    heightAt(x: number, z: number): number;
+    /** Height of vertex (column, row). */
+    vertexHeight(column: number, row: number): number;
+    /** Material exposed at a vertex. */
+    vertexMaterial(column: number, row: number): TerrainMaterial;
+    columnAt(x: number, z: number): TerrainColumn;
+    contains(x: number, z: number): boolean;
+    /** First point of the ground along a ray, or null. */
+    raycast(origin: readonly number[], direction: readonly number[], maxDistance: number): {
+        point: [number, number, number];
+        distance: number;
+        normal: [number, number, number];
+    } | null;
+    /** A blow at (x, z). `energy` in joules, `direction` where it travels (it throws the pieces back along it). */
+    strike(blow: TerrainBlow, spec: {
+        x: number;
+        z: number;
+        energy: number;
+        direction?: readonly number[];
+        contactRadius?: number;
+    }): TerrainBlowResult;
+    /** A flame over a disc for `seconds`. */
+    burn(spec: {
+        x: number;
+        z: number;
+        radius: number;
+        temperature: number;
+        seconds: number;
+    }): void;
+    /** Applies a world hit (`Hit` of the destruction contract); null when it does nothing to the ground. */
+    applyHit(hit: Hit): TerrainBlowResult | null;
+    /** Follow the ground changing: `region` is the disc it changed in. What rests there has lost its support and must look again. Returns the unsubscribe function. */
+    onDeform(listener: (region: TerrainRegion) => void): () => void;
+    /** Moves the pieces, the sliding ground and the fire. */
+    update(dt: number): void;
+    /** Takes up to the budget's chunks that changed since the last call. */
+    drainDirtyChunks(max?: number): TerrainChunk[];
+    chunk(index: number): TerrainChunk;
+    marks(): readonly TerrainMark[];
+    debris(): readonly TerrainDebris[];
+    /** Cells on fire now, as world points. */
+    burningPoints(): readonly (readonly [number, number])[];
+    /** Goes up when the marks change. */
+    readonly marksVersion: number;
+    stats(): TerrainStats;
+    /** Back to the untouched ground. */
+    reset(): void;
+    serialize(): TerrainSnapshot;
+    load(snapshot: TerrainSnapshot): void;
+}
+interface TerrainSnapshot {
+    readonly layout: GroundLayout;
+    readonly dug: readonly (readonly [number, number])[];
+    readonly loose: readonly (readonly [number, number])[];
+    readonly scorch: readonly (readonly [number, number])[];
+    readonly barBend?: readonly (readonly [number, number])[];
+    readonly marks: readonly TerrainMark[];
+}
+
+declare const DEFAULT_TERRAIN_BUDGET: TerrainBudget;
+declare function createTerrain(options: TerrainOptions): Terrain;
+
+interface TerrainImplOptions {
+    readonly id: string;
+    readonly name?: string;
+    /** Every blow that left its mark, with what it did. */
+    readonly onBlow?: (result: TerrainBlowResult, hit: Hit) => void;
+}
+/**
+ * The ground as an object of the destruction world (`DestructionWorld.register`): shots, blows, blasts and flames reach it through the world's own raycast and blast like anything else.
+ * The collision part is a flat box; a ray that enters it goes on to the real surface, so a round fired into a crater lands on its floor.
+ */
+declare function createTerrainImpl(terrain: Terrain, options: TerrainImplOptions): DestructibleImpl;
+
+declare const TERRAIN_MATERIALS: readonly TerrainMaterial[];
+declare const TERRAIN_PROFILES: readonly TerrainProfile[];
+/** About twelve grenades (200 kJ) on the same spot of bare bars. */
+declare const DEFAULT_BAR_YIELD_JOULES = 2400000;
+/** The profile of a floor with nothing else said: a plain slab. */
+declare const DEFAULT_PROFILE = "concrete_slab";
+
+export { DEFAULT_BAR_YIELD_JOULES, DEFAULT_PROFILE, DEFAULT_TERRAIN_BUDGET, TERRAIN_MATERIALS, TERRAIN_PATTERNS, TERRAIN_PROFILES, type Terrain, type TerrainBlow, type TerrainBlowResponse, type TerrainBlowResult, type TerrainBudget, type TerrainChunk, type TerrainColumn, type TerrainDebris, type TerrainDebrisKind, type TerrainFireResponse, type TerrainImplOptions, type TerrainMark, type TerrainMaterial, type TerrainOptions, type TerrainPattern, type TerrainProfile, type TerrainRegion, type TerrainSnapshot, type TerrainStats, type TerrainStratum, createTerrain, createTerrainImpl };