@adatechnology/game-items-three 0.5.0 → 0.6.0

package/README.md

@@ -5,6 +5,7 @@ three.js presentation for `@adatechnology/game-items`. Everything is drawn at th
 - **Models of the team:** the 24 builders of the Itens do Vale Cinzento showcase, ported as they are (their units, their materials by tag) and scaled to metres by the `scale` of its entry. A game adds or replaces one with `registerItemModel`.
 - **Simple shapes:** 25 shapes (`can`, `bottle`, `box`, `bag`, `tool`, `blade`, `long_tool`, `garment`, `backpack`, `jerrycan`, `tank`, `book`, `key`, `battery`, `plank`, `device`...) drawn inside the `size` of any item, chosen by its `shape` hint refined by category and proportions (`shapeOf`).
 - **Wear:** `setWear(object, 0 | 1 | 2)` takes the materials from new to used to spoiled, as the showcase does.
+- **Opened cans:** `openItem(THREE, root, modelId)` draws a sealed model open (`data/opening.json`): a tin's cut lid bent up with the food inside the rim, the sardines' peeled lid, the mouth of a drink can; `setOpeningContents(root, share)` empties it as it is eaten. The items area gives each sealed item (`ItemDef.seal`) the room's `seal` and the `eat` use.
 - **Budgets:** `mergeItem` joins an item by material, `buildItemLod` gives three levels (model or shape, half-detail shape, nothing past 30 m for a small item and 60 m for a large one), `ITEM_BUDGETS` and `checkBudget` hold the page's 30 draw calls and 400 / 1200 triangles.
 
 ```ts

package/dist/index.d.ts

@@ -105,6 +105,10 @@ interface DrawableItem extends ShapeSubject {
     model?: string;
     /** Real weight in kg; with `destructible` it becomes the mass of the destruction body. */
     weight?: number;
+    /** Loose dry contents in their colour (0xRRGGBB); with `destructible` a hole through the item puffs them out (`PartSpec.powder`). */
+    powder?: {
+        color: number;
+    };
 }
 interface BuildItemOptions {
     /** Wear of the materials, 0 new (default), 1 used, 2 spoiled. */
@@ -184,6 +188,8 @@ interface ItemContents {
     /** The shell is a box (a flat tin) and not a cylinder. */
     readonly box?: boolean;
 }
+/** The rule of an item drawn as the simple shape `shapeId` (`game-items-three`'s `drawShape`), if any. */
+declare const shapeDestruction: (shapeId: string) => ItemDestruction | undefined;
 /** 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;
@@ -211,20 +217,59 @@ declare function itemContents(subject: ContentsSubject): {
 /** What `tagForDestruction` needs to know about the item beside its meshes. */
 interface DestructionTagOptions {
     readonly modelId?: string;
+    /** The simple shape the item is drawn as when it has no model (`shapeDestruction`). */
+    readonly shapeId?: string;
     /** Real weight in kg. */
     readonly weight?: number;
     /** Size in metres, for the contents of the shell. */
     readonly size?: readonly [number, number, number];
+    /** Loose dry contents in their colour: written on the shell (`userData.destructionPowder`), so a hole through it puffs them out. */
+    readonly powder?: {
+        readonly color: number;
+    };
     /** three.js, for the shapes three only makes from scratch (a cylinder with rings on its ends: `tessellate.cylinder.capRings`). */
     readonly three?: typeof THREE_NS;
 }
 /**
  * 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`) and the real thickness of each wall (`destructionThickness`).
+ * the item's real weight in kg (`destructionMass`, so the world weighs what the thing weighs) and what the model's family (or the simple shape it is drawn as) in `data/destruction.json` asks for (hollow shells, welded parts, skins),
+ * with the liquid the model holds on its shell (`destructionContains`), its loose dry contents (`destructionPowder`) and the real thickness of each wall (`destructionThickness`).
  */
 declare function tagForDestruction(root: THREE_NS.Object3D, options?: DestructionTagOptions): void;
 
+/**
+ * How a sealed model looks once open: `cut_lid` (a tin opened with a can opener: the lid cut along the rim and bent up on a hinge, the food showing),
+ * `peel_lid` (a flat tin with a ring pull: the lid rolled back along its length), `pull_tab` (a drink can: the scored mouth pushed in under the tab) and `screw_cap`
+ * (a jar or a bottle: the meshes its model marks `userData.itemLid` taken off, the mouth under them showing).
+ */
+type ItemOpeningStyle = 'cut_lid' | 'peel_lid' | 'pull_tab' | 'screw_cap';
+interface ItemOpening {
+    readonly style: ItemOpeningStyle;
+    /** Colour of what shows inside (`#rrggbb`); a dark inside when the data gives none. */
+    readonly food?: string;
+}
+/** The opened look of a model (`data/opening.json`: its family's style, the model's own entry over it), or undefined for a model that does not open. */
+declare const itemOpening: (modelId: string) => ItemOpening | undefined;
+/** Name of the group `openItem` adds to the root. */
+declare const OPENING_NAME = "opening";
+/** Marks the cap of a model (`userData.itemLid`), the part a `screw_cap` opening takes off; wraps the mesh where the model makes it, so nothing is reordered. */
+declare const asLid: <TMesh extends THREE_NS.Object3D>(mesh: TMesh) => TMesh;
+/**
+ * Draws the model `modelId` opened on the root `buildItem` returned: a child group named `opening` (marked as decals, `userData.destructionDebris`, so a
+ * shot and the liquid ignore it). Measured on the drawn model, so it fits any scale. Once: a second call does nothing. False for a model that does not open.
+ */
+declare function openItem(T: typeof THREE_NS, root: THREE_NS.Object3D, modelId: string): boolean;
+/**
+ * Turns the cap of a `screw_cap` model `turned` radians round its axis and lifts it `lift` (0..1) of the way off its thread, from where the model drew it. Before
+ * `openItem`, which takes it off. False for a model that does not open with a screw cap.
+ */
+declare function turnItem(root: THREE_NS.Object3D, modelId: string, state: {
+    readonly turned: number;
+    readonly lift: number;
+}): boolean;
+/** Shows how much is left in an opened item: the food inside the rim shrinks with `share` (0..1 of what it held) and is gone when it is eaten up. */
+declare function setOpeningContents(root: THREE_NS.Object3D, share: number): 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.
@@ -477,4 +522,4 @@ interface ScenarioLike {
     expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
 }
 
-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 };
+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 ItemOpening, type ItemOpeningStyle, type ItemSizeClass, type ItemsAreaState, type ItemsTestModule, type ItemsTestModuleOptions, type LayoutItem, MODEL_BUDGET_DEVIATIONS, OPENING_NAME, 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, asLid, buildItem, buildItemLod, canonicalFrame, checkBudget, composeThumbnailScene, countDrawCalls, countTriangles, createItemKit, createItemsTestModule, cullDistanceOf, drawShape, hasItemModel, isShape, itemContents, itemDestruction, itemFamily, itemModelBuilder, itemModelEntry, itemOpening, itemThumbnail, itemThumbnailSvg, listItemModels, mergeItem, openItem, registerItemModel, renderItemThumbnail, setOpeningContents, setWear, shade, shapeDestruction, shapeOf, shapeThumbnailSvg, shelvesLayout, sizeClassOf, tagForDestruction, thumbnailPatch, triangleBudgetOf, turnItem, unregisterItemModel, wearableMaterials };