Artifact System

The artifact system defines Artifacts, which are digital assets that are presented as items in the virtual space.

Artifact: Digital Asset

An Artifact is a piece of data with the following data

interface Artifact {
    content: unknown // required
    type: ArtifactType // required
    loader: Loader // recommended
    metadata: Metadata // recommended
    ... // other possible modules
}

where

• content is required, and it stores the content that is relevant to load into the space, for example, a model or shader. The type of the content, or how to use and load the content, is specified in type and loader.
• type is required, and it describes the type of the Artifact.
• loader is recommended, and it specifies how the content should be loaded. In some cases, one can usually infer the loader from the type, but we encourage developers to specify it explicitly.
• metadata is recommended, and it stores the readable information of the Artifact.

type and loader

The type in general describes what the artifact is. Some examples are

type ArtifactType = "model" | "shader" | "hdri" | "image" | "VFX" | ...

The loader is used to specify how to load the content. For example, a model type artifact can use GLTFLoader to load its content in three.js.

The practical use of type and loader is to specify how the content is to be used, therefore, usually type can infer loader if the implementation has a dictionary or convention.

metadata

metadata stores an object that contains information that is useful.

Substandard of Artifact

Artifact is very flexible, and the metadata usually depends on how you are going to use it. Here we list some typical substandards for Artifact that are relevant for many use cases.

Exterior Space metadata

This section defines the Artifact substandard for Exterior Space. Artifacts used in Exterior Space must follow this substandard, and invalid metadata will fall back to a sculptures category Artifact with all other fields set to default values.

interface Metadata {
    id: string, // required, the mint address of the asset
    token: string, // optional, the token address of the asset, if any
    name: string, // required, the display name of the artifact
    description: string, // recommended, a short description of the artifact
    category: Category, // recommended, defaults to 'sculptures' if not specified
    stackable: boolean, // optional, inferred from category by default, but can be set manually
    volume: Volume, // recommended, defaults to 1x1x1 if not specified
    preview: image, // recommended, an image preview used in inventory display
    edition: NFTEdition, // optional, used to check if the asset is a Solana edition, only used for Solana
    interaction: Interaction[], // optional, see interaction system
    positionFineTune: boolean, // optional, defaults to true, enables sub-cell fine-tuning of placement, see positionFineTune module.
    wallMounted: boolean, // not recommended, inferred from category by default, set only in edge cases
    creators: string[] // optional, addresses of the creators
    infoKind: ArtifactInfoKind // optional, used for monument/quest module quick check, see relevant module for more information
    info: ArtifactInfo // optional, used to store monument/quest module info, see relevant module for more information
    infoLink: string // optional, used to store link monument/quest module info, see relevant module for more information
}
 
 
type Volume = {
    width: number   // x-axis
    length: number  // y-axis
    height: number  // z-axis
}
 
type Category = "housewares" | "miscellaneous" | "sculptures" | "paintings" | "frame" | "wallmounted" | "ceiling" | "wall" | "carpets" | "rugs" | "fashion" | "creatures" | "plant" ;

For more details on how each field is processed in Exterior Space, please refer to the Artist Guide.

Subspace artifact

Most different kinds (infoKind) of artifacts in Exterior Space are differentiated by interaction behavior — for example, artifacts that allow node addition like a visitor book, those that act as an artboard, or those that launch mini-games like TRPGs. These will be discussed further when we introduce the trace system and interaction system.

Here we highlight a particular kind of artifact known as the subspace artifact. A subspace artifact uses the trace system to store a Form or ExtForm object — hence the name.

Such artifacts are typically used to present objects like bookshelves, wine cabinets, or framed picture collages.