@adatechnology/game-items-three 0.6.1 → 0.7.0

package/dist/testing-CBYX7wTL.d.ts

@@ -0,0 +1,196 @@
+import * as THREE_NS from 'three';
+import { 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;
+
+/** 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;
+}
+/** 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;
+/** The models of one registry: what `buildItem` reads through its `models` option. */
+interface ItemModelRegistry {
+    has(id: string): boolean;
+    entry(id: string): ItemModelEntry | undefined;
+    builder(id: string): ItemModelBuilder | undefined;
+    /** The ids registered, in the order of registration (the order of the showcase for the ones the kit ships). */
+    list(): string[];
+    /** Adds (or replaces) the model of an item: `entry.id` is the catalog id the item's `model` field names. */
+    register(entry: ItemModelEntry, builder: ItemModelBuilder): void;
+    /** Takes a model out (a game that wants the simple shape instead). */
+    unregister(id: string): void;
+}
+/** The registry behind `registerItemModel`, `hasItemModel` and the rest of the global functions, created on first use. */
+declare const defaultItemModels: () => ItemModelRegistry;
+/**
+ * Adds (or replaces) the model of an item: `entry.id` is the catalog id the item's `model` field names.
+ * @deprecated use `createItemModels(...).register`.
+ */
+declare const registerItemModel: (entry: ItemModelEntry, builder: ItemModelBuilder) => void;
+/** @deprecated use `createItemModels(...).unregister`. */
+declare const unregisterItemModel: (id: string) => void;
+/** @deprecated use `createItemModels(...).entry`. */
+declare const itemModelEntry: (id: string) => ItemModelEntry | undefined;
+/** @deprecated use `createItemModels(...).builder`. */
+declare const itemModelBuilder: (id: string) => ItemModelBuilder | undefined;
+/** @deprecated use `createItemModels(...).has`. */
+declare const hasItemModel: (id: string) => boolean;
+/** @deprecated use `createItemModels(...).list`. */
+declare const listItemModels: () => 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.
+ */
+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;
+    /** The models to show and draw with (`createItemModels(...)`); default the shared set behind `registerItemModel`. */
+    models?: ItemModelRegistry;
+}
+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;
+}
+
+export { unregisterItemModel as A, FINDS_TABLE_ID as F, HUMAN_HEIGHT as H, type ItemKit as I, type LayoutItem as L, ROW_LIMIT as R, SHELF_HEIGHT as S, type Vec3Tuple as V, WEAR_TAGS as W, type ItemModelRegistry as a, type ItemModelEntry as b, type ItemModelBuilder as c, HUMAN_ID as d, ITEM_PREFIX as e, type ItemMaterialData as f, type ItemsAreaState as g, type ItemsTestModule as h, type ItemsTestModuleOptions as i, RULER_HEIGHT as j, RULER_ID as k, SHELF_PREFIX as l, SHOWCASE_PREFIX as m, SHOWCASE_STAND_ID as n, type ScenarioLike as o, type ShelfPlan as p, type WearTag as q, createItemKit as r, createItemsTestModule as s, defaultItemModels as t, hasItemModel as u, itemModelBuilder as v, itemModelEntry as w, listItemModels as x, registerItemModel as y, shelvesLayout as z };

package/dist/testing.d.ts

@@ -0,0 +1,4 @@
+export { F as FINDS_TABLE_ID, H as HUMAN_HEIGHT, d as HUMAN_ID, g as ItemsAreaState, h as ItemsTestModule, i as ItemsTestModuleOptions, j as RULER_HEIGHT, k as RULER_ID, n as SHOWCASE_STAND_ID, o as ScenarioLike, s as createItemsTestModule } from './testing-CBYX7wTL.js';
+import 'three';
+import '@adatechnology/game-contracts';
+import '@adatechnology/game-items';

package/dist/testing.js

@@ -0,0 +1,19 @@
+import {
+  FINDS_TABLE_ID,
+  HUMAN_HEIGHT,
+  HUMAN_ID,
+  RULER_HEIGHT,
+  RULER_ID,
+  SHOWCASE_STAND_ID,
+  createItemsTestModule
+} from "./chunk-WGFTVYO3.js";
+export {
+  FINDS_TABLE_ID,
+  HUMAN_HEIGHT,
+  HUMAN_ID,
+  RULER_HEIGHT,
+  RULER_ID,
+  SHOWCASE_STAND_ID,
+  createItemsTestModule
+};
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adatechnology/game-items-three",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "license": "MIT",
   "description": "three.js presentation for @adatechnology/game-items: the 24 models of the Itens do Vale Cinzento showcase at real size, simple shapes at real size for every other item, wear (new, used, spoiled) on the materials, merge by material, LOD and the draw budgets of the team.",
   "keywords": [
@@ -32,18 +32,22 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
     "./global": "./dist/index.global.js"
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@adatechnology/game-contracts": "^0.20.0",
-    "@adatechnology/game-floorplan-three": "^0.8.2",
-    "@adatechnology/game-fluids": "^0.4.0",
-    "@adatechnology/game-interactables": "^0.2.12",
-    "@adatechnology/game-items": "^0.2.0",
-    "@adatechnology/game-shapes-three": "^0.2.0"
+    "@adatechnology/game-contracts": "^0.22.0",
+    "@adatechnology/game-floorplan-three": "^0.9.0",
+    "@adatechnology/game-fluids": "^0.4.2",
+    "@adatechnology/game-interactables": "^0.2.14",
+    "@adatechnology/game-items": "^0.2.2",
+    "@adatechnology/game-shapes-three": "^0.3.0"
   },
   "peerDependencies": {
     "three": "^0.160.0"
@@ -56,8 +60,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.7.3",
     "vitest": "^3.2.4",
-    "@adatechnology/game-items-goods": "^0.3.0",
-    "@adatechnology/game-test-room": "^0.19.1",
+    "@adatechnology/game-items-goods": "^0.3.2",
+    "@adatechnology/game-test-room": "^0.21.0",
     "@adatechnology/golden-tool": "^0.0.0"
   },
   "scripts": {