@adatechnology/game-terrain-three 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,21 @@
-# Temporary Holding Version
+# @adatechnology/game-terrain-three
 
-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.
+three.js renderer for [`@adatechnology/game-terrain`](../game-terrain).
+
+```ts
+import { createTerrainRenderer } from '@adatechnology/game-terrain-three'
+
+const view = createTerrainRenderer(THREE, { terrain })
+scene.add(view.group)
+// every frame:
+view.sync(camera.position)
+```
+
+- Chunks nobody touched share one flat geometry (one draw call for a whole floor); a dug chunk gets a mesh that draws half or a quarter of its vertices far away (`lodDistance`).
+- The pattern of each surface (grass, grout, planks, asphalt, slab joints) is drawn per pixel from the world position, so it never tiles or stretches; the edge between two materials stays sharp.
+- Marks are instanced decals (not drawn beyond `markDistance`), thrown pieces are instanced, and rebar appears where a slab is dug past its cover.
+- `createTerrainTestModule()`: a strip of each ground side by side to shoot, blow up, burn and drop weights on. `room.openArea('terrain')`.
+
+## Português
+
+Renderizador three.js do terreno: chunks intactos numa só geometria, chunks escavados com malha própria e LOD ao longe, padrão de cada piso por pixel, marcas e torrões instanciados, vergalhão onde a laje foi escavada além do cobrimento. `createTerrainTestModule()` traz as faixas de piso lado a lado para testar tiro, explosão, fogo e queda de peso.

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import * as THREE_NS from 'three';
+import { Terrain } from '@adatechnology/game-terrain';
+import { GroundLayout, TestableModule } from '@adatechnology/game-contracts';
+
+type ThreeLib$1 = typeof THREE_NS;
+interface TerrainRendererOptions {
+    readonly terrain: Terrain;
+    /** Beyond this distance in metres a dug chunk draws half its vertices (default 30), twice this a quarter. */
+    readonly lodDistance?: number;
+    /** Marks farther than this in metres are not drawn (default 45). */
+    readonly markDistance?: number;
+    /** Metres the untouched ground goes on beyond the terrain, so that it has no edge in sight (default 300). */
+    readonly skirt?: number;
+}
+interface TerrainRenderer {
+    readonly group: THREE_NS.Group;
+    /** Call every frame with the camera's position. Redraws at most the terrain's budget of chunks. */
+    sync(camera: {
+        readonly x: number;
+        readonly y: number;
+        readonly z: number;
+    }): void;
+    /** What is on the screen, for a bench. */
+    stats(): {
+        readonly chunkMeshes: number;
+        readonly pristineChunks: number;
+        readonly marksDrawn: number;
+        readonly debrisDrawn: number;
+    };
+    dispose(): void;
+}
+/** The ground of a `Terrain`: chunks nobody touched share one flat geometry, a dug one gets a mesh of its own that gets simpler far away. */
+declare function createTerrainRenderer(THREE: ThreeLib$1, options: TerrainRendererOptions): TerrainRenderer;
+
+type ThreeLib = typeof THREE_NS;
+/** The ground's material: the colour of what is exposed comes per vertex, flat so that the edge between two materials stays sharp, its pattern (blades of grass, grout, planks) is drawn per pixel from the world position so that it never tiles or stretches. */
+declare function createSurfaceMaterial(THREE: ThreeLib): THREE_NS.MeshStandardMaterial;
+
+/** The strips of the area, side by side, one of each ground. */
+declare const TERRAIN_STRIPS: readonly ["dirt", "lawn", "sand", "road", "concrete_slab", "suspended_slab", "wood_floor", "tile_floor", "stone_paving"];
+declare const TERRAIN_AREA_GROUND: GroundLayout;
+/**
+ * The ground bench: a strip of each surface side by side to shoot, blow up, burn and drop weights on. Opening the area lays the strips (`ground`) and drops a concrete block
+ * on each from four metres.
+ */
+declare function createTerrainTestModule(options?: {
+    readonly locale?: string;
+}): TestableModule;
+
+export { TERRAIN_AREA_GROUND, TERRAIN_STRIPS, type TerrainRenderer, type TerrainRendererOptions, createSurfaceMaterial, createTerrainRenderer, createTerrainTestModule };