@adatechnology/game-items-three 0.1.5 → 0.2.0

package/README.md

@@ -20,3 +20,8 @@ scene.add(buildItemLod(THREE, items.get('hammer')).root)  // merged, with LOD an
 ```
 
 three.js is a peer dependency (`^0.160`). The global of the IIFE build is `GameItemsThree`.
+
+The geometry comes from [`game-shapes`](../game-shapes): the kit's `T` is `shapeGeometries(THREE)`, so the ported builders keep writing
+`new T.CylinderGeometry(...)` and get the same bytes from game-shapes' template cache (a tube still comes from three), and `mergeItem` joins on
+`game-shapes-three`. `tests/exact-golden.test.ts` holds every bit of the 24 models and 25 shapes (alone, merged, half detail, LOD) as the old
+path made them.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as THREE_NS from 'three';
-import { Thumbnail, Vec3, AreaPlacement, TestableModule } from '@adatechnology/game-contracts';
+import { ContainerSpec, Thumbnail, Vec3, AreaPlacement, TestableModule } from '@adatechnology/game-contracts';
 import { FindStack, ItemsCatalog, FindsProvider } from '@adatechnology/game-items';
 
 type Three = typeof THREE_NS;
@@ -16,7 +16,9 @@ interface ItemMaterialData {
 type Vec3Tuple = readonly [number, number, number];
 /**
  * The helpers the showcase page defines before its models (`M`, `mesh`, `cyl`, `bx`, `lathe`, `torus`, `extrude`, `G` and the seven material makers), so that the
- * builders ported from the page read the same as the originals. `T` is the three.js the kit was made with; `materials` lists every material it made, in order.
+ * builders ported from the page read the same as the originals. `T` is the three.js the kit was made with, with its box, cylinder, cone, sphere, plane, lathe, torus and
+ * (straight-edged) extrude geometries made by game-shapes (`shapeGeometries`: the same bytes, the same classes, a template cache); `materials` lists every material it made,
+ * in order.
  */
 interface ItemKit {
     readonly T: Three;
@@ -38,7 +40,7 @@ interface ItemKit {
     glass(color: number, opacity: number): THREE_NS.MeshStandardMaterial;
 }
 /** The helpers of the showcase page on a given three.js; every kit has its own list of materials. */
-declare function createItemKit(T: Three): ItemKit;
+declare function createItemKit(three: Three): ItemKit;
 
 /** 0 new, 1 used, 2 spoiled (the three stages of the showcase). */
 type WearStage = 0 | 1 | 2;
@@ -101,6 +103,8 @@ interface DrawableItem extends ShapeSubject {
     size: Vec3Tuple;
     /** Key of a showcase model; without one (or when the model is not registered) the simple shape is drawn. */
     model?: string;
+    /** Real weight in kg; with `destructible` it becomes the mass of the destruction body. */
+    weight?: number;
 }
 interface BuildItemOptions {
     /** Wear of the materials, 0 new (default), 1 used, 2 spoiled. */
@@ -109,6 +113,8 @@ interface BuildItemOptions {
     simple?: boolean;
     /** Level of detail of the simple shape, 1 (default) or 0.5 for half the segments. */
     detail?: number;
+    /** Write the `userData` that `game-destruction-three`'s `specFromObject3D` reads (material of each mesh, hollow shells, welded parts, skins; see `tagForDestruction`). Default off. */
+    destructible?: boolean;
     /** A kit to draw with (and to collect the materials in); default a new one. */
     kit?: ItemKit;
 }
@@ -131,6 +137,82 @@ interface ItemModel {
  */
 declare function buildItem(T: typeof THREE_NS, item: DrawableItem, options?: BuildItemOptions): ItemModel;
 
+/** The destruction material (`game-destruction` id) of each material tag of the kit, for a mesh whose model says nothing else. */
+declare const DESTRUCTION_MATERIAL_BY_TAG: Readonly<Record<string, string>>;
+/** How a model behaves under `game-destruction-three`'s `specFromObject3D`, as `data/destruction.json` keeps it. */
+interface ItemDestruction {
+    /** The meshes are thin shells, not solid blocks. */
+    readonly hollow?: boolean;
+    /** The parts of the model are welded to its largest mesh, so a hit dents and holes them instead of tearing them off. */
+    readonly welded?: boolean;
+    /** Meshes made of these material tags are skins (labels, coats): drawn on a part, never a part of their own. */
+    readonly skinTags?: readonly string[];
+    /** Material tag to destruction material id, over `DESTRUCTION_MATERIAL_BY_TAG`. */
+    readonly materials?: Readonly<Record<string, string>>;
+    /** Segments the cylinder and box meshes of the model are rebuilt with, so a bullet dent (a few millimetres wide) finds vertices to push in. */
+    readonly tessellate?: {
+        readonly cylinder?: {
+            readonly heightSegments: number;
+            readonly radialSegments: number;
+        };
+        readonly box?: {
+            readonly widthSegments: number;
+            readonly heightSegments: number;
+            readonly depthSegments: number;
+        };
+    };
+}
+/** A family of models that behave alike: one rule for all of them, so adding a model is one id and changing the rule changes them all. */
+interface ItemFamily {
+    readonly models: readonly string[];
+    readonly rule: ItemDestruction;
+}
+/** What a model holds inside its shell: a liquid (`game-fluids` id) filling `fill` of the inner volume. */
+interface ItemContents {
+    readonly liquid: string;
+    readonly fill: number;
+    /** The shell is a box (a flat tin) and not a cylinder. */
+    readonly box?: boolean;
+}
+/** Id of the family a model belongs to (`drink_can`), if any. */
+declare const itemFamily: (modelId: string) => string | undefined;
+declare const itemDestruction: (modelId: string) => ItemDestruction | undefined;
+/** The family ids and their models, as the data gives them. */
+declare const ITEM_FAMILIES: Readonly<Record<string, ItemFamily>>;
+/** The subject of `itemContents`: what `buildItem` draws. */
+interface ContentsSubject {
+    readonly model?: string;
+    /** Metres. */
+    readonly size: readonly [number, number, number];
+    /** Kg, shell included. */
+    readonly weight?: number;
+}
+/** Id of the welded part that is the whole shell of a container. */
+declare const SHELL_PART_ID = "shell";
+/**
+ * The container the model holds (`TestableItem.fluid` of the test room and `PartSpec.contains` of the shell), sized from the item: the inner volume of its
+ * box times the fill of the model, never more than the item weighs in that liquid. Undefined for a model that holds nothing.
+ */
+declare function itemContents(subject: ContentsSubject): {
+    readonly container: ContainerSpec;
+    readonly liquid: string;
+    readonly liters: number;
+} | undefined;
+/** What `tagForDestruction` needs to know about the item beside its meshes. */
+interface DestructionTagOptions {
+    readonly modelId?: string;
+    /** Real weight in kg. */
+    readonly weight?: number;
+    /** Size in metres, for the contents of the shell. */
+    readonly size?: readonly [number, number, number];
+}
+/**
+ * Writes the `userData` that `specFromObject3D` reads onto the meshes of a drawn item: the destruction material of each mesh from its kit material tag,
+ * the item's real weight in kg (`destructionMass`, so the world weighs what the thing weighs) and what the model's family in `data/destruction.json` asks for (hollow shells, welded parts, skins),
+ * with the liquid the model holds on its shell (`destructionContains`).
+ */
+declare function tagForDestruction(root: THREE_NS.Object3D, options?: DestructionTagOptions): void;
+
 /**
  * The same item with its meshes joined by material: one mesh and one draw call per material instead of one per part (the "one material for all the items" of the page's
  * budget, as far as the materials of the kit allow). The materials are the same objects, so `setWear` still reaches them. The model's scale stays on the root.
@@ -378,4 +460,4 @@ interface ScenarioLike {
     expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
 }
 
-export { type BudgetReport, type BuildItemOptions, type DrawableItem, FINDS_TABLE_ID, HUMAN_HEIGHT, HUMAN_ID, ITEM_BUDGETS, ITEM_PREFIX, type ItemBudgets, type ItemKit, type ItemLod, type ItemLodOptions, type ItemMaterialData, type ItemModel, type ItemModelBuilder, type ItemModelEntry, type ItemSizeClass, type ItemsAreaState, type ItemsTestModule, type ItemsTestModuleOptions, type LayoutItem, MODEL_BUDGET_DEVIATIONS, ROW_LIMIT, RULER_HEIGHT, RULER_ID, SHAPES, SHELF_HEIGHT, SHELF_PREFIX, SHIPPED_MODELS, SHOWCASE_PREFIX, SHOWCASE_STAND_ID, type ScenarioLike, type ShapeContext, type ShapeId, type ShapeSubject, type ShelfPlan, type ThumbnailRenderOptions, type ThumbnailRenderer, type ThumbnailScene, type Vec3Like, type Vec3Tuple, WEAR_AMOUNT, WEAR_TAGS, WEAR_TARGET, type WearStage, type WearTag, buildItem, buildItemLod, canonicalFrame, checkBudget, composeThumbnailScene, countDrawCalls, countTriangles, createItemKit, createItemsTestModule, cullDistanceOf, drawShape, hasItemModel, isShape, itemModelBuilder, itemModelEntry, itemThumbnail, itemThumbnailSvg, listItemModels, mergeItem, registerItemModel, renderItemThumbnail, setWear, shade, shapeOf, shapeThumbnailSvg, shelvesLayout, sizeClassOf, thumbnailPatch, triangleBudgetOf, unregisterItemModel, wearableMaterials };
+export { type BudgetReport, type BuildItemOptions, type ContentsSubject, DESTRUCTION_MATERIAL_BY_TAG, type DestructionTagOptions, type DrawableItem, FINDS_TABLE_ID, HUMAN_HEIGHT, HUMAN_ID, ITEM_BUDGETS, ITEM_FAMILIES, ITEM_PREFIX, type ItemBudgets, type ItemContents, type ItemDestruction, type ItemFamily, type ItemKit, type ItemLod, type ItemLodOptions, type ItemMaterialData, type ItemModel, type ItemModelBuilder, type ItemModelEntry, type ItemSizeClass, type ItemsAreaState, type ItemsTestModule, type ItemsTestModuleOptions, type LayoutItem, MODEL_BUDGET_DEVIATIONS, ROW_LIMIT, RULER_HEIGHT, RULER_ID, SHAPES, SHELF_HEIGHT, SHELF_PREFIX, SHELL_PART_ID, SHIPPED_MODELS, SHOWCASE_PREFIX, SHOWCASE_STAND_ID, type ScenarioLike, type ShapeContext, type ShapeId, type ShapeSubject, type ShelfPlan, type ThumbnailRenderOptions, type ThumbnailRenderer, type ThumbnailScene, type Vec3Like, type Vec3Tuple, WEAR_AMOUNT, WEAR_TAGS, WEAR_TARGET, type WearStage, type WearTag, buildItem, buildItemLod, canonicalFrame, checkBudget, composeThumbnailScene, countDrawCalls, countTriangles, createItemKit, createItemsTestModule, cullDistanceOf, drawShape, hasItemModel, isShape, itemContents, itemDestruction, itemFamily, itemModelBuilder, itemModelEntry, itemThumbnail, itemThumbnailSvg, listItemModels, mergeItem, registerItemModel, renderItemThumbnail, setWear, shade, shapeOf, shapeThumbnailSvg, shelvesLayout, sizeClassOf, tagForDestruction, thumbnailPatch, triangleBudgetOf, unregisterItemModel, wearableMaterials };