@adatechnology/game-items-three 0.6.2 → 0.7.1

package/dist/index.d.ts

@@ -1,46 +1,8 @@
+import { V as Vec3Tuple, I as ItemKit, a as ItemModelRegistry, b as ItemModelEntry, c as ItemModelBuilder } from './testing-CBYX7wTL.js';
+export { F as FINDS_TABLE_ID, H as HUMAN_HEIGHT, d as HUMAN_ID, e as ITEM_PREFIX, f as ItemMaterialData, g as ItemsAreaState, h as ItemsTestModule, i as ItemsTestModuleOptions, L as LayoutItem, R as ROW_LIMIT, j as RULER_HEIGHT, k as RULER_ID, S as SHELF_HEIGHT, l as SHELF_PREFIX, m as SHOWCASE_PREFIX, n as SHOWCASE_STAND_ID, o as ScenarioLike, p as ShelfPlan, W as WEAR_TAGS, q as WearTag, r as createItemKit, s as createItemsTestModule, t as defaultItemModels, u as hasItemModel, v as itemModelBuilder, w as itemModelEntry, x as listItemModels, y as registerItemModel, z as shelvesLayout, A as unregisterItemModel } from './testing-CBYX7wTL.js';
 import * as THREE_NS from 'three';
-import { ContainerSpec, Thumbnail, Vec3, AreaPlacement, TestableModule } from '@adatechnology/game-contracts';
-import { FindStack, ItemsCatalog, FindsProvider } from '@adatechnology/game-items';
-
-type Three = typeof THREE_NS;
-/** The material tags the team's showcase wears: what `setWear` turns toward its spoiled colour. */
-declare const WEAR_TAGS: readonly ["metal", "wood", "cloth", "plastic", "paper", "food", "glass"];
-type WearTag = (typeof WEAR_TAGS)[number];
-/** What a material of the kit remembers so that `setWear` can go back to new: the colour it was made with (as three read it, and as sRGB floats), its tag and its roughness. */
-interface ItemMaterialData {
-    base: THREE_NS.Color;
-    baseRgb: readonly [number, number, number];
-    tag: string;
-    rough: number;
-}
-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, 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;
-    readonly materials: THREE_NS.MeshStandardMaterial[];
-    M(color: number, tag: string, options?: THREE_NS.MeshStandardMaterialParameters): THREE_NS.MeshStandardMaterial;
-    mesh(geometry: THREE_NS.BufferGeometry, material: THREE_NS.Material, position?: Vec3Tuple, rotation?: Vec3Tuple, scale?: Vec3Tuple): THREE_NS.Mesh;
-    cyl(radiusTop: number, radiusBottom: number, height: number, segments?: number): THREE_NS.CylinderGeometry;
-    bx(width: number, height: number, depth: number): THREE_NS.BoxGeometry;
-    lathe(points: ReadonlyArray<readonly [number, number]>, segments?: number): THREE_NS.LatheGeometry;
-    torus(radius: number, tube: number, arc?: number): THREE_NS.TorusGeometry;
-    extrude(points: ReadonlyArray<readonly [number, number]>, depth: number, bevel?: number): THREE_NS.ExtrudeGeometry;
-    G(...children: THREE_NS.Object3D[]): THREE_NS.Group;
-    metal(color: number): THREE_NS.MeshStandardMaterial;
-    wood(color: number): THREE_NS.MeshStandardMaterial;
-    cloth(color: number): THREE_NS.MeshStandardMaterial;
-    plastic(color: number): THREE_NS.MeshStandardMaterial;
-    paper(color: number): THREE_NS.MeshStandardMaterial;
-    food(color: number): THREE_NS.MeshStandardMaterial;
-    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(three: Three): ItemKit;
+import { ContainerSpec, Thumbnail, DeepPartial } from '@adatechnology/game-contracts';
+import '@adatechnology/game-items';
 
 /** 0 new, 1 used, 2 spoiled (the three stages of the showcase). */
 type WearStage = 0 | 1 | 2;
@@ -121,6 +83,8 @@ interface BuildItemOptions {
     destructible?: boolean;
     /** A kit to draw with (and to collect the materials in); default a new one. */
     kit?: ItemKit;
+    /** The models to draw with; default the shared set behind `registerItemModel` (`createItemModels` makes one of your own). */
+    models?: ItemModelRegistry;
 }
 /** What `buildItem` returns. */
 interface ItemModel {
@@ -270,6 +234,12 @@ declare function turnItem(root: THREE_NS.Object3D, modelId: string, state: {
 /** 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 item models as a source a weapon or an explosive can draw with (`ItemModels` of game-weapons-three): a host lends it as `items`. */
+declare const itemModels: {
+    readonly has: (id: string) => boolean;
+    readonly build: typeof buildItem;
+};
+
 /**
  * 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.
@@ -339,28 +309,28 @@ interface ItemLod {
  */
 declare function buildItemLod(T: typeof THREE_NS, item: DrawableItem, options?: ItemLodOptions): ItemLod;
 
-/** One model of the showcase as `data/models.json` keeps it: the item it draws, the id the team gave it, the box it has in the units of the page and the scale to metres. */
-interface ItemModelEntry {
-    /** Catalog id of the item (`canned_beans`). */
-    readonly id: string;
-    /** The id in the team's `MODELS` (`feijao_lata`). */
-    readonly teamId: string;
-    /** Box of the builder's group in the page's units (`Box3.setFromObject`), x y z. */
-    readonly teamBox: readonly [number, number, number];
-    /** Metres per unit of the page, from one real measure of the object. */
-    readonly scale: number;
+interface ItemModelRecord {
+    readonly entry: ItemModelEntry;
+    readonly builder: ItemModelBuilder;
+}
+interface ItemModelsOptions {
+    /** Models added to the shipped ones; one with the id of a shipped model replaces it. */
+    readonly packs?: readonly (readonly ItemModelRecord[])[];
+    /** Changes to an entry by item id (`scale`, `teamBox`), merged field by field. */
+    readonly patch?: Readonly<Record<string, DeepPartial<ItemModelEntry>>>;
+    /** Item ids whose model is taken out (the item then gets its simple shape). */
+    readonly remove?: readonly string[];
+}
+interface ItemModels extends ItemModelRegistry {
+    /** `buildItem` that reads this set of models. */
+    build(T: typeof THREE_NS, item: DrawableItem, options?: Omit<BuildItemOptions, 'models'>): ItemModel;
+    /** `buildItemLod` that reads this set of models. */
+    buildLod(T: typeof THREE_NS, item: DrawableItem, options?: Omit<ItemLodOptions, 'models'>): ItemLod;
+    /** `itemThumbnail` that asks this set whether the item has a model. */
+    thumbnail(item: DrawableItem): Thumbnail;
 }
-/** A builder of the showcase, ported as it is: it draws in the page's units and returns the group. */
-type ItemModelBuilder = (kit: ItemKit) => THREE_NS.Group;
-/** Adds (or replaces) the model of an item: `entry.id` is the catalog id the item's `model` field names. */
-declare function registerItemModel(entry: ItemModelEntry, builder: ItemModelBuilder): void;
-/** Takes a model out (a game that wants the simple shape instead). */
-declare function unregisterItemModel(id: string): void;
-declare const itemModelEntry: (id: string) => ItemModelEntry | undefined;
-declare const itemModelBuilder: (id: string) => ItemModelBuilder | undefined;
-declare const hasItemModel: (id: string) => boolean;
-/** The ids of the models registered, in the order of registration (the order of the showcase for the ones the kit ships). */
-declare const listItemModels: () => string[];
+/** A set of item models of its own: the shipped ones plus `packs`, `patch` and `remove`. Nothing is shared with any other set on the page. */
+declare function createItemModels(options?: ItemModelsOptions): ItemModels;
 
 /** The 24 models of the showcase in the page's order: the entry of `data/models.json` (generated by `tools/items-catalog`) and the builder ported from the page. */
 declare const SHIPPED_MODELS: ReadonlyArray<{
@@ -381,11 +351,11 @@ declare function shapeThumbnailSvg(shape: ShapeId, color?: number): string;
  * The picture of an item for catalogues and inventories: an item that has a 3D model asks the host to draw it (`render: true`), every other gets the SVG of its shape in
  * its colour.
  */
-declare function itemThumbnail(item: DrawableItem): Thumbnail;
+declare function itemThumbnail(item: DrawableItem, models?: ItemModelRegistry): Thumbnail;
 /** The SVG of an item whatever it has: its shape in its colour (what a host with no renderer shows for a modeled item). */
 declare const itemThumbnailSvg: (item: DrawableItem) => string;
 /** `{ id: { thumbnail } }` for `createItems({ patch })`, so that a catalog carries its pictures. */
-declare function thumbnailPatch(items: Iterable<DrawableItem>): Record<string, {
+declare function thumbnailPatch(items: Iterable<DrawableItem>, models?: ItemModelRegistry): Record<string, {
     thumbnail: Thumbnail;
 }>;
 interface ThumbnailRenderOptions {
@@ -397,6 +367,8 @@ interface ThumbnailRenderOptions {
     /** Multiplies the distance that just fits the item (default 1). */
     distance?: number;
     wear?: WearStage;
+    /** The models to draw with; default the shared set behind `registerItemModel`. */
+    models?: ItemModelRegistry;
 }
 interface ThumbnailScene {
     scene: THREE_NS.Scene;
@@ -413,113 +385,10 @@ interface ThumbnailRenderer {
         toDataURL(type?: string): string;
     };
 }
-/** Draws the item with the host's renderer and returns the PNG as a data URL (transparent background). */
-declare function renderItemThumbnail(T: typeof THREE_NS, renderer: ThumbnailRenderer, item: DrawableItem, options?: ThumbnailRenderOptions): string;
-
-/** What the layout needs of an item: its id, category and real size [width, height, depth] in metres. */
-interface LayoutItem {
-    readonly id: string;
-    readonly category: string;
-    readonly size: readonly [number, number, number];
-}
-/** Height of the top of a shelf, metres. */
-declare const SHELF_HEIGHT = 0.9;
-/** Longest row of items on a shelf, metres. */
-declare const ROW_LIMIT = 5;
-/** One shelf: a category's items laid out in rows at real size, the shelf's footprint and where its items sit on its top. */
-interface ShelfPlan {
-    category: string;
-    /** Item id of the shelf in the module (`shelf_<category>`). */
-    id: string;
-    /** Footprint on the floor: length along x, depth along z. */
-    length: number;
-    depth: number;
-    position: Vec3;
-    /** Where each item sits, in world coordinates. */
-    items: AreaPlacement[];
-}
-declare const SHELF_PREFIX = "shelf_";
-declare const ITEM_PREFIX = "item_";
-declare const SHOWCASE_PREFIX = "showcase_";
 /**
- * The shelves of the area: one per category, in the order the categories come, with every item of the category side by side at real size, wrapped in rows of at most
- * `ROW_LIMIT` metres. Shelves stand in a grid of four columns; an item that is longer than the row limit gets a row to itself. Pure: the same items always land in the same spots.
+ * Draws the item with the host's renderer and returns the PNG as a data URL (transparent background). The scene has lights of its own (the one allowlisted place for them, see `eslint.config.mjs`),
+ * so pass a renderer made for thumbnails, never the game's: its lights would link programs on the game's renderer, which `ProgramWarmup.linkedSince` shows.
  */
-declare function shelvesLayout(items: readonly LayoutItem[], categories: readonly string[]): ShelfPlan[];
-
-interface ItemsTestModuleOptions {
-    /** The catalog to lay out (for example `createGoodsItems()` of `game-items-goods`). The module knows no content of its own. */
-    catalog: ItemsCatalog;
-    /** `en` or `pt-BR` (default). */
-    locale?: string;
-    /** Text of a key such as `item.canned_beans`, `place.house`, `category.food`, `container.fridge`, `recipe.stew` (the goods package has them in `goodsText`); without it the module falls back to the id. */
-    translate?: (key: string, locale: string) => string | undefined;
-    /** Seed of the finds roll (default 1). */
-    seed?: number;
-    /** Wear the items start with: `new` (default), `used` or `spoiled`. */
-    wear?: string;
-    /** The finds provider; default the one of `game-items` over `catalog`. A game gives its own (floorplan bindings, pools). */
-    provider?: FindsProvider;
-    /**
-     * Draws a person of the kit to judge the scale by (for example a survivor of `createPersonBuilder` of `game-characters-three`); the module brings it to 1.80 m. Without it
-     * the area shows the ruler alone.
-     */
-    person?: (THREE: unknown) => THREE_NS.Object3D;
-}
-declare const SHOWCASE_STAND_ID = "stand_models";
-declare const RULER_ID = "ruler_155";
-declare const HUMAN_ID = "human_180";
-declare const FINDS_TABLE_ID = "finds_table";
-declare const RULER_HEIGHT = 1.55;
-declare const HUMAN_HEIGHT = 1.8;
-/** What the scenarios of the area ask of the module (and what a host or a test may read). */
-interface ItemsAreaState {
-    readonly category: string;
-    readonly wear: string;
-    readonly ageDays: number;
-    readonly storage: string;
-    readonly powered: boolean;
-    readonly place: string;
-    readonly container: string;
-    readonly state: string;
-    readonly day: number;
-    readonly seed: number;
-    readonly recipe: string;
-}
-interface ItemsTestModule extends TestableModule {
-    /** Everything the module has put in the scene so far, with what was measured when it was drawn. */
-    placed(): ReadonlyArray<{
-        id: string;
-        itemId: string;
-        group: 'shelf' | 'showcase';
-        kind: 'model' | 'shape';
-        size: readonly [number, number, number];
-        root: THREE_NS.Object3D;
-    }>;
-    /** The stacks now on the finds table. */
-    finds(): readonly FindStack[];
-    /** The shelves of the layout. */
-    shelves(): readonly ShelfPlan[];
-    readonly state: ItemsAreaState;
-    /** The bench actions, callable without a host (what the buttons do). */
-    rollFinds(): readonly FindStack[];
-    craftSelected(): {
-        ok: boolean;
-        missing: readonly string[];
-    };
-    selectRecipe(id: string): void;
-    /** The box of a drawn object, metres [x, y, z] (needs the host's three.js namespace: null before the module is attached or an item built). */
-    measure(root: THREE_NS.Object3D): [number, number, number] | null;
-}
-/**
- * The items test area as a `TestableModule` of @adatechnology/game-contracts: every item of a catalog on shelves by category at real size (the real model of the team where there is
- * one, the simple shape of its category elsewhere), a stand where the 24 models turn, a ruler and a human figure to judge the scale, and a table where the finds of a container
- * and the result of a recipe are laid. The bench sets wear, age and storage, the place, container, state, outbreak day and seed of the finds, and the recipe.
- */
-declare function createItemsTestModule(options: ItemsTestModuleOptions): ItemsTestModule;
-/** What the scenarios use of the context the test room passes (`ScenarioContext`). */
-interface ScenarioLike {
-    expect(condition: boolean, label: string, data?: Record<string, unknown>): void;
-}
+declare function renderItemThumbnail(T: typeof THREE_NS, renderer: ThumbnailRenderer, item: DrawableItem, options?: ThumbnailRenderOptions): string;
 
-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 };
+export { type BudgetReport, type BuildItemOptions, type ContentsSubject, DESTRUCTION_MATERIAL_BY_TAG, type DestructionTagOptions, type DrawableItem, ITEM_BUDGETS, ITEM_FAMILIES, type ItemBudgets, type ItemContents, type ItemDestruction, type ItemFamily, ItemKit, type ItemLod, type ItemLodOptions, type ItemModel, ItemModelBuilder, ItemModelEntry, type ItemModelRecord, ItemModelRegistry, type ItemModels, type ItemModelsOptions, type ItemOpening, type ItemOpeningStyle, type ItemSizeClass, MODEL_BUDGET_DEVIATIONS, OPENING_NAME, SHAPES, SHELL_PART_ID, SHIPPED_MODELS, type ShapeContext, type ShapeId, type ShapeSubject, type ThumbnailRenderOptions, type ThumbnailRenderer, type ThumbnailScene, type Vec3Like, Vec3Tuple, WEAR_AMOUNT, WEAR_TARGET, type WearStage, asLid, buildItem, buildItemLod, canonicalFrame, checkBudget, composeThumbnailScene, countDrawCalls, countTriangles, createItemModels, cullDistanceOf, drawShape, isShape, itemContents, itemDestruction, itemFamily, itemModels, itemOpening, itemThumbnail, itemThumbnailSvg, mergeItem, openItem, renderItemThumbnail, setOpeningContents, setWear, shade, shapeDestruction, shapeOf, shapeThumbnailSvg, sizeClassOf, tagForDestruction, thumbnailPatch, triangleBudgetOf, turnItem, wearableMaterials };