Skip to content
Art library0.0.1
API reference

catalog

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/art-library/catalog";

Exports

Section titled “Exports”
Kind Export Description
class CatalogError A pack’s receipt is inconsistent with its files.
class UnknownModelError A model id that no catalog row has; suggestions are the nearest real models.
type alias PackSource Where the catalog reads a pack’s receipt and model bytes.
type alias ModelKind The catalog’s closed vocabulary of model categories.
type alias ModelRow A validated catalog row, including model dimensions and attribution.
constant shippedPacks Reads the packs shipped beside this module.
constant packKinds The kind of every model in a pack, or null for a pack whose receipt lists no model rows (its files are parts or one-offs, and stay out of the catalog). Every pack is named, so a new pack cannot ship without a decision here.
function modelCatalog() The library’s models, derived from each pack’s PROVENANCE.json and the files on disk; nothing else lists them. A row exists for each item row of a receipt (and each character), and packs without item rows are absent. A pack’s reused rows name files another pack already lists, so they add none.
function searchModels() The rows that best match a query, best first. Query words match a row’s id words, then its tags and kind; a misspelling still matches its nearest id words. Rows that match nothing are left out.
function requireModel() The row with exactly this id.

Node catalog discovery from @fungi.computer/art-library/catalog: modelCatalog(), searchModels and requireModel.

This entrypoint reads the shipped provenance receipts and model bytes to derive rows, including their dimensions and licences. Browser applications use the generated models rows from @fungi.computer/art-library/models instead; do not bundle this Node reader. Selecting a row does not load a mesh. Use the /three entrypoint’s modelLoader() and a bundled asset URL for that step.

Example

Section titled “Example”
TS
import {
  modelCatalog,
  requireModel,
  searchModels,
} from "@fungi.computer/art-library/catalog";


const rows = await modelCatalog();
const candidates = searchModels(rows, "alpaca", { kind: "animal" });
const mascot = requireModel(rows, "animated-animals/alpaca");
console.log(candidates, mascot.originalLicense);

CatalogErrorclass

Section titled “CatalogError”

A pack’s receipt is inconsistent with its files.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new CatalogError(message?): CatalogError;
Parameters
Section titled “Parameters”
Parameter Type
message? string
Returns
Section titled “Returns”

CatalogError

Inherited from
Section titled “Inherited from”
Signature
Error.constructor;

Constructor

Section titled “Constructor”
Signature
new CatalogError(message?, options?): CatalogError;
Parameters
Section titled “Parameters”
Parameter Type
message? string
options? ErrorOptions
Returns
Section titled “Returns”

CatalogError

Inherited from
Section titled “Inherited from”
Signature
Error.constructor;

Properties

Section titled “Properties”

name

Section titled “name”
Signature
readonly name: "CatalogError" = "CatalogError";

Stable diagnostic name for a receipt/file inconsistency.

Overrides
Section titled “Overrides”
Signature
Error.name;

UnknownModelErrorclass

Section titled “UnknownModelError”

A model id that no catalog row has; suggestions are the nearest real models.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new UnknownModelError(id, suggestions): UnknownModelError;
Parameters
Section titled “Parameters”
Parameter Type Description
id string Requested id absent from the catalog.
suggestions readonly Readonly<{ id: string; pack: | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"; kind: | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"; name: string; tags: string[]; description: string; width: number; height: number; depth: number; sizeSource: "declared" | "typical"; sizeNote: string | null; file: string; author: string; originalLicense: string; fileLicense: string; }>[] Nearest existing catalog rows, ordered by search relevance.
Returns
Section titled “Returns”

UnknownModelError

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

name

Section titled “name”
Signature
readonly name: "UnknownModelError" = "UnknownModelError";

Stable diagnostic name for a missing model id.

Overrides
Section titled “Overrides”
Signature
Error.name;

id

Section titled “id”
Signature
readonly id: string;

Requested id absent from the catalog.

suggestions

Section titled “suggestions”
Signature
readonly suggestions: readonly Readonly<{
  id: string;
  pack:   | "animated-animals"
     | "buildings"
     | "cell-keys"
     | "characters"
     | "farm-animals"
     | "food-a"
     | "furnishings-b"
     | "interiors"
     | "inventory"
     | "medieval-village"
     | "modular-ar3"
     | "modular-guns"
     | "plain-bat"
     | "rifle"
     | "storage-a"
     | "storage-b"
     | "street-a"
     | "survival-loot"
     | "town-props-b"
     | "upper-floor-a"
     | "vehicles";
  kind:   | "item"
     | "character"
     | "animal"
     | "building"
     | "furniture"
     | "street"
     | "vehicle"
     | "food";
  name: string;
  tags: string[];
  description: string;
  width: number;
  height: number;
  depth: number;
  sizeSource: "declared" | "typical";
  sizeNote: string | null;
  file: string;
  author: string;
  originalLicense: string;
  fileLicense: string;
}>[];

Nearest existing catalog rows, ordered by search relevance.

PackSourcetype alias

Section titled “PackSource”
Signature
type PackSource = object;

Where the catalog reads a pack’s receipt and model bytes.

Methods

Section titled “Methods”

receipt()

Section titled “receipt()”
Signature
receipt(pack): Promise<string>;

Read a pack’s provenance receipt as JSON text.

Parameters
Section titled “Parameters”
Parameter Type
pack | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"
Returns
Section titled “Returns”

Promise<string>

model()

Section titled “model()”
Signature
model(pack, file): Promise<Uint8Array<ArrayBufferLike>>;

Read one model file relative to its pack.

Parameters
Section titled “Parameters”
Parameter Type
pack | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"
file string
Returns
Section titled “Returns”

Promise<Uint8Array<ArrayBufferLike>>

ModelKindtype alias

Section titled “ModelKind”
Signature
type ModelKind =
  | "item"
  | "character"
  | "animal"
  | "building"
  | "furniture"
  | "street"
  | "vehicle"
  | "food";

The catalog’s closed vocabulary of model categories.

ModelRowtype alias

Section titled “ModelRow”
Signature
type ModelRow = Readonly<{
  id: string;
  pack:
    | "animated-animals"
    | "buildings"
    | "cell-keys"
    | "characters"
    | "farm-animals"
    | "food-a"
    | "furnishings-b"
    | "interiors"
    | "inventory"
    | "medieval-village"
    | "modular-ar3"
    | "modular-guns"
    | "plain-bat"
    | "rifle"
    | "storage-a"
    | "storage-b"
    | "street-a"
    | "survival-loot"
    | "town-props-b"
    | "upper-floor-a"
    | "vehicles";
  kind:
    | "item"
    | "character"
    | "animal"
    | "building"
    | "furniture"
    | "street"
    | "vehicle"
    | "food";
  name: string;
  tags: string[];
  description: string;
  width: number;
  height: number;
  depth: number;
  sizeSource: "declared" | "typical";
  sizeNote: string | null;
  file: string;
  author: string;
  originalLicense: string;
  fileLicense: string;
}>;

A validated catalog row, including model dimensions and attribution.

shippedPacksconstant

Section titled “shippedPacks”
Signature
const shippedPacks: PackSource;

Reads the packs shipped beside this module.

packKindsconstant

Section titled “packKinds”
Signature
const packKinds: object;

The kind of every model in a pack, or null for a pack whose receipt lists no model rows (its files are parts or one-offs, and stay out of the catalog). Every pack is named, so a new pack cannot ship without a decision here.

Type Declaration

Section titled “Type Declaration”
Name Type Default value Description
animated-animals "animal" "animal" Animated animal models.
buildings "building" "building" Building models.
cell-keys null null Separate cell and key parts, excluded from the model catalog.
characters "character" "character" Human character models.
farm-animals "animal" "animal" Farm animal models.
food-a "food" "food" Food models.
furnishings-b "furniture" "furniture" Furniture models.
interiors "furniture" "furniture" Interior furniture models.
inventory "item" "item" Inventory item models.
medieval-village "building" "building" Medieval building models.
modular-ar3 null null Modular weapon parts, excluded from the model catalog.
modular-guns null null Modular gun parts, excluded from the model catalog.
plain-bat "item" "item" Baseball bat item models.
rifle "item" "item" Rifle item models.
storage-a "furniture" "furniture" Storage furniture models.
storage-b null null Separate storage parts, excluded from the model catalog.
street-a "street" "street" Street prop models.
survival-loot "item" "item" Survival item models.
town-props-b "street" "street" Town street prop models.
upper-floor-a "furniture" "furniture" Upper-floor furniture models.
vehicles "vehicle" "vehicle" Vehicle models.

modelCatalog()function

Section titled “modelCatalog()”
Signature
function modelCatalog(source?): Promise<
  readonly Readonly<{
    id: string;
    pack:
      | "animated-animals"
      | "buildings"
      | "cell-keys"
      | "characters"
      | "farm-animals"
      | "food-a"
      | "furnishings-b"
      | "interiors"
      | "inventory"
      | "medieval-village"
      | "modular-ar3"
      | "modular-guns"
      | "plain-bat"
      | "rifle"
      | "storage-a"
      | "storage-b"
      | "street-a"
      | "survival-loot"
      | "town-props-b"
      | "upper-floor-a"
      | "vehicles";
    kind:
      | "item"
      | "character"
      | "animal"
      | "building"
      | "furniture"
      | "street"
      | "vehicle"
      | "food";
    name: string;
    tags: string[];
    description: string;
    width: number;
    height: number;
    depth: number;
    sizeSource: "declared" | "typical";
    sizeNote: string | null;
    file: string;
    author: string;
    originalLicense: string;
    fileLicense: string;
  }>[]
>;

The library’s models, derived from each pack’s PROVENANCE.json and the files on disk; nothing else lists them. A row exists for each item row of a receipt (and each character), and packs without item rows are absent. A pack’s reused rows name files another pack already lists, so they add none.

Size comes from the model’s bounding box, scaled to the real height or length its receipt gives (heightMetres or lengthMetres, else a typicalLengthMetres with its note). A receipt that gives none is an error, so every row is in metres.

Parameters

Section titled “Parameters”
Parameter Type Default value
source PackSource shippedPacks

Returns

Section titled “Returns”

Promise<readonly Readonly<{ id: string; pack: | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"; kind: | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"; name: string; tags: string[]; description: string; width: number; height: number; depth: number; sizeSource: "declared" | "typical"; sizeNote: string | null; file: string; author: string; originalLicense: string; fileLicense: string; }>[]>

Throws

Section titled “Throws”

CatalogError when a receipt and its files disagree.

searchModels()function

Section titled “searchModels()”
Signature
function searchModels(
  rows,
  query,
  options?,
): readonly Readonly<{
  id: string;
  pack:
    | "animated-animals"
    | "buildings"
    | "cell-keys"
    | "characters"
    | "farm-animals"
    | "food-a"
    | "furnishings-b"
    | "interiors"
    | "inventory"
    | "medieval-village"
    | "modular-ar3"
    | "modular-guns"
    | "plain-bat"
    | "rifle"
    | "storage-a"
    | "storage-b"
    | "street-a"
    | "survival-loot"
    | "town-props-b"
    | "upper-floor-a"
    | "vehicles";
  kind:
    | "item"
    | "character"
    | "animal"
    | "building"
    | "furniture"
    | "street"
    | "vehicle"
    | "food";
  name: string;
  tags: string[];
  description: string;
  width: number;
  height: number;
  depth: number;
  sizeSource: "declared" | "typical";
  sizeNote: string | null;
  file: string;
  author: string;
  originalLicense: string;
  fileLicense: string;
}>[];

The rows that best match a query, best first. Query words match a row’s id words, then its tags and kind; a misspelling still matches its nearest id words. Rows that match nothing are left out.

Parameters

Section titled “Parameters”
Parameter Type
rows readonly Readonly<{ id: string; pack: | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"; kind: | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"; name: string; tags: string[]; description: string; width: number; height: number; depth: number; sizeSource: "declared" | "typical"; sizeNote: string | null; file: string; author: string; originalLicense: string; fileLicense: string; }>[]
query string
options { kind?: | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"; limit?: number; }
options.kind? | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"
options.limit? number

Returns

Section titled “Returns”

readonly Readonly<{ id: string; pack: | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"; kind: | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"; name: string; tags: string[]; description: string; width: number; height: number; depth: number; sizeSource: "declared" | "typical"; sizeNote: string | null; file: string; author: string; originalLicense: string; fileLicense: string; }>[]

requireModel()function

Section titled “requireModel()”
Signature
function requireModel(rows, id): ModelRow;

The row with exactly this id.

Parameters

Section titled “Parameters”
Parameter Type
rows readonly Readonly<{ id: string; pack: | "animated-animals" | "buildings" | "cell-keys" | "characters" | "farm-animals" | "food-a" | "furnishings-b" | "interiors" | "inventory" | "medieval-village" | "modular-ar3" | "modular-guns" | "plain-bat" | "rifle" | "storage-a" | "storage-b" | "street-a" | "survival-loot" | "town-props-b" | "upper-floor-a" | "vehicles"; kind: | "item" | "character" | "animal" | "building" | "furniture" | "street" | "vehicle" | "food"; name: string; tags: string[]; description: string; width: number; height: number; depth: number; sizeSource: "declared" | "typical"; sizeNote: string | null; file: string; author: string; originalLicense: string; fileLicense: string; }>[]
id string

Returns

Section titled “Returns”

ModelRow

Throws

Section titled “Throws”

UnknownModelError listing the 3 nearest real models.