# Manifold Standard Version: 0.1.51 ### Abstract The Manifold Standard maps digital data to a space. It defines several types of JSON objects and how to reliably reconstruct the space from them. The reconstructed space contains a three-dimensional scene, and may specify how users can interact and leave traces in the scene. ### Status of This Memo This document is currently not open to the public. ### Relation to the reference implementations One of the reference implementations of the standard is the project [Exterior Space](http://extspace.net). Exterior Space is an open-source browser for spaces stored on-chain, planned to launch alongside the standard. Exterior Space implements the standard with its own profile for optional fields and modules. It also includes additional features optimized for browsing and editing spaces. Exterior Space supports the standard, and its major version aligns with the standard’s major version. The maintainers plan to extract the conformant core into a standalone open-source package as the reference implementation of the standard, which Exterior Space will then use. Until that is complete, this document will include footnotes about Exterior Space where relevant. ### 01 Table of Content This table of contents is provided as a guide for navigating this document. It does not list all the subsections, but only lists sections to a manageable depth for navigation. - [[00-Manifold-Standard]] - [[01-Table-of-Content]] - [[02-Copyright-Notice]] - [[03-Conventions]] - [[04-Version-Control]] - [[05-Conformance-Profile]] - [[10-Introduction]] - [[11-Scope-and-Structure]] - [[20-Core-Specification]] - [[21-Scene]] - [[22-`Form`-Type-Object]] - [[23-`Embedding`-Type-Object]] - [[24-`Artifact`-Type-Object]] - [[25-`Metadata`-Type-Object]] - [[26-Enhancing-and-Modifying-the-Scene]] - [[26.01-Form-Metadata-Module]] - [[26.02-Sky-Module]] - [[26.03-Environment-Model-Module]] - [[26.04-Boundary-Module-and-Tile-Module]] - [[26.05-Layout-Mode-Module]] - [[26.05.01-Reconstruction-Logic]] - [[26.05.02-Artifact-Volume]] - [[26.05.03-Stacking-Logic]] - [[26.05.04-Cell-Placement]] - [[26.05.05-Block-Placement]] - [[26.05.06-Slot-Placement]] - [[26.05.07-Reconstruction-Logic-by-Layout-Mode]] - [[26.06-Local-Scene-Module]] - [[27-Modifying-and-Enhancing-an-Artifact]] - [[27.01-Category-Module]] - [[27.02-Artifact-Attachments]] - [[27.03-Artifact-Info]] - [[27.04-Shift-Local-origin]] - [[27.05-Local-Scene-Module-for-Artifact]] - [[27.06-Artifact-Mold]] - [[27.08-Image-Artifact]] - [[27.09-Music-Artifact]] - [[30-Extension-Specification]] - [[31-User-and-User-Interface]] - [[32-Space]] - [[33-Avatar]] - [[34-Trace]] - [[35-Interaction]] - [[36-Visit]] - [[37-Authorization]] - [[40-Modules]] - [[41-Module-Specification]] - [[42-Modules-Registration-and-Acceptance]] - [[43-Modules-Catalog]] ### 02 Copyright Notice Copyright (c) 2026 The Manifold Standard Editing Committee and the persons identified as the document authors. All rights reserved. ### 03 Conventions #### 03.01 Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [RFC2119](https://datatracker.ietf.org/doc/html/rfc2119) [RFC8174](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they appear in all capitals, as shown here. #### 03.02 Conventions Used in This Document Any JSON object defined in this document MUST conform to [RFC8259](https://datatracker.ietf.org/doc/html/rfc8259). Some examples use the combination of a TypeScript single-line comment (`//`) followed by an ellipsis (`...`) as placeholder notation for content deemed irrelevant by the authors. These placeholders must of course be deleted or otherwise replaced, before attempting to validate the corresponding JSON code example. Whitespace is used in the examples inside this document to help illustrate the data structures, but it is not required. Unquoted whitespace is not significant in JSON. #### 03.03 Type Definitions In this document, a JSON object type defines the required and optional name-value pairs of a JSON object. An object belongs to a type — or "is of that type" — if it contains all required name-value pairs and only name-value pairs that are either required or optional for that type. Each name-value pair in a type definition specifies the name of the pair and the constraint on its value. Required name-value pairs are indicated by the keywords MUST or REQUIRED; optional name-value pairs by MAY, OPTIONAL, SHOULD, or RECOMMENDED, as defined in Section 03.01. A JSON type, or simply a type, is a constraint on a JSON value. A JSON object type, as defined above, is a type that constrains an object by specifying its required and optional name-value pairs. A type may also constrain a non-object value by specifying the set of allowed values, for example, a number within a particular range, or a string equal to one of a specified set. #### 03.04 Representation of Data In this document, TypeScript code is used to represent data, such as JSON object and JSON object type. However, the TypeScript code SHOULD NOT be considered the only form in which the data can be realized in an implementation. #### 03.99 Notes The section 03.02 significantly references the standard [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946). ### 04 Version Control In this section, the meaning and handling of the version of the standard are defined. #### 04.01 Version Number The version number of the standard and each section of the standard use the format MAJOR.MINOR.PATCH. Notice this is not the standard semantic versioning. 1. MAJOR version number is the released stable version of the standard. Each MAJOR bump is a release of a stable version, which is a closure of a set of proposed changes to the standard. Each MAJOR bump resets the MINOR version number to zero and increases the MAJOR version number by one. One can refer to a stable version of the standard by the MAJOR version number. For example, Manifold Standard Version 1 refers to Version 1.0.0 of the standard. 2. MINOR version numbers are used for proposed changes for the next stable version of the standard. Each MINOR bump is a closure of a set of section changes to the standard, with each change labeled with a PATCH version number. Each MINOR bump resets the PATCH version number to zero and increases the MINOR version number by one. 3. PATCH version numbers are used for proposed changes for the next stable version of one section of the standard. A PATCH bump of the standard is performed when a section of the standard is changed. This section is also marked with the full version number it was last changed. This mark can be referred to as the version number of this section. #### 04.02 Breaking Changes A breaking change is a change that either: 1. Makes the data format not backward compatible, or 2. Alters the relationship between the data and the reconstructed space in a non-compatible way. This includes changes of default behaviors. It is RECOMMENDED that stable releases of the standard do not introduce breaking changes. The version number does not imply whether changes are breaking or non-breaking. If a breaking change is included in a stable release, an attachment describing migration from the previous version to the current version MUST be provided in Section 90 of the release. #### 04.03 Notes on Implementation 1. Closure is an event of obtaining and confirming the consensus of the Manifold Standard Editing Committee. The Manifold Standard Editing Committee is the maintenance team for the Manifold Standard before version 1.0.0. Each closure MUST ends with a version number bump and a tag of the version to the Git repository. 2. If a change in one section requires edits in another section, and if the changes have a clear logical order, each edit SHOULD be followed by a PATCH bump. If term changes, typo changes, or convention changes occur in multiple sections, changes to multiple sections MAY be merged into one PATCH bump. If there is a set of inseparable changes across multiple sections, these changes MAY be merged into one PATCH bump. 3. A section of the standard is defined as one markdown file. #### 04.04 Implementation of Referencing 1. Each release of the stable version contains an archive action, for which the released standard MUST be uploaded to durable storage, obtaining the URI for referencing the standard of the particular stable version. 2. Each proposed version can be referred to using the git tag. 3. MINOR/PATCH version of the standard MUST NOT be cited as normative in external integrations. #### 04.05 Errata for Stable Releases Each post-release erratum of the stable release version is additional documentation called amendments to the stable release version, specifying fixes to the standard of the stable release version. The amended stable release version of the standard is referred to using the version number MAJOR.0.0.ERRATA. It is RECOMMENDED not to issue an erratum for the stable release version unless critical mistakes are made. The amendments MUST be uploaded to durable storage, obtaining the URI for referencing. #### 04.06 Expiration of This Section The version numbering, meaning, and handling described in this section are for versions before version 1.0.0. At version 1.0.0, versioning and change control transfer to the governance model that is defined at that time. The governance model after version 1.0.0 may or may not follow this handling of version numbers. ### 05 Conformance Profile #todo Base/Chart/Atlas ## 10 Introduction The Manifold Standard specifies a mapping between a defined set of data and a space. Its goal is to define a virtual space where users can store, arrange, decorate, present, generate, update, and interact with digital assets. It provides a canonical data format for serializing these spaces and reliably reconstructing a space from that data. Although similar implementations exist in products and games, they remain closed and therefore fragment users’ memories, creations, and belongings, while a standard provides the common ground for decentralized, user-owned spaces open to anyone, anytime, anywhere, with any digital assets. The standard is organized into three parts that together define a framework enabling users to experience virtual spaces. The core specifications form the minimal kernel of the standard. They define the scene space and its artifacts, and hence how artifacts are placed within the scene. The extension specifications define how users are connected to the space, that is, how users present themselves and interact within and across spaces. Finally, modules are optional specifications built upon the core and extension specifications to enhance how users experience the space, providing additional layers of interaction, personalization, and growth. Together, the standard enables the space and its artifacts to encode users' live events, helps users share their spaces anywhere, assists users in discovering and engaging with other spaces, brings a sense of time or living creatures into the space, and much more. ### 11 Scope and Structure #todo #### 11.01 Core Systems Core systems form the minimal kernel for the standard, which constitute the conformance profile Manifold Base. Any implementation of the standard must include all core systems. ##### 11.01.01 Space System The Space System defines the `Form` object and its portable variant, `ExtForm`, which describe the scene layout. `Form` must follow the rules of the selected layout mode, which specifies alignment constraints or free placement. ##### 11.01.02 Artifact System The Artifact System defines `Artifact`s, which are digital assets that are presented as objects in the virtual space. Implementations may directly wrap any digital asset as an `Artifact` with default properties; using the optional interfaces defined in the standard can further enhance the user experience. #### 11.02 Optional Systems Optional systems add users and their actions to the space, creating context for spaces and connections to users. Optional systems can be implemented separately, though some features within a system require one or more other systems. It is recommended to implement the Avatar, Trace, and Interaction systems together. Combined with the core systems, they constitute the Manifold Chart conformance profile. It is also recommended to implement the Visit and Authorization systems together. When the core systems and all optional systems are implemented, they constitute the Manifold Atlas conformance profile. ##### 11.02.01 Avatar System The Avatar System defines the `Avatar` object, a movable, user-linked agent that acts as the user's presence in the virtual space. Avatars may be used to initiate spatial interactions or act as interaction targets. ##### 11.02.02 Trace System The Trace System defines `Trace`, a two-fold representation of data stored as `History` and `State`. `History` records events in the space, and `State` records the current status of the space. ##### 11.02.03 Interaction System The Interaction System defines how a user or their avatar interacts with the virtual space. Concretely, interactions are functions triggered by the user interface, either via the avatar or directly, that modify the space. ##### 11.02.04 Visit System The Visit System defines asynchronous and synchronous visit mechanisms across spaces, with or without user presence. ##### 11.02.05 Authorization System The Authorization System defines access control mechanisms for `Form`s and `Artifact`s. #### 11.03 Modules While systems define the fundamental structure of a virtual space, modules build upon these systems to enhance user experience, emotional engagement, and social dynamics. Each module is optional and can be implemented independently, although some modules are designed to work better when combined with certain systems or with each other. Each module has its own document, including its identifier, version, dependencies, and governance model. In this document, we provide a catalog of modules accepted by the standard. Each module is stated with its accepted stable version and relevant information, and it is recommended that the implementation of the standard includes them. Here we list a few highlighted modules that one may frequently encounter. ##### 11.03.01 Monument Module > The idea of the Monument Module is to allow people to bring their existence from the physical world online. Most importantly, it offers a way to digitally capture users’ lived experiences — a living memory. In other words, its purpose is not merely to replicate a digital twin, but to realize a conceptual embodiment — a digital form shaped by users’ own experiences and choices. The Monument Module relates users’ “verifiable” offline behavior to the generation and updating of digital assets. > [!info] > In practice, “verification” is performed on the client side and can generally be forged. However, it is users’ actions themselves that carry meaning, regardless of whether those actions involve forgery. In other words, even if a user fabricates an action, the choice to claim “I have done this” is itself meaningful — otherwise, the user would not have chosen to fabricate it. Thus, as long as the basic logic is preserved, the resulting expression remains valid. ##### 11.03.02 Quest Module > The idea of the Quest Module is similar to that of the Monument Module. It serves as the living memory of a digital life. Its advantage is that, in the online world, verification can be reliably enforced. Thus, the form of a quest can be more versatile, ranging from traditional puzzle-solving quests in games to online wedding events. The Quest Module relates users’ online behavior in virtual spaces to the generation and updating of digital assets. ##### 11.03.03 Share Module > The Share Module captures the impulse to open our doors to friends and share the things we’ve picked up along our journeys. Through sharing, a space becomes a conversation, and objects carry our stories from one space to another. The Share Module allows users to share their spaces and digital assets with friends or on external social platforms. ##### 11.03.04 Connection Module > The Connection Module helps users explore other spaces, whether those of friends or strangers. Visits initiated by related artifacts or spaces can provide a softer, lower-pressure scenario by enabling naturally initiated social interactions. This lowers the barrier to starting new friendships and exploring new worlds. The Connection Module defines an address book for each user to record friends’ space addresses. It also enables random or condition-triggered visits initiated by related artifacts. Beyond one-to-one relationships, this module creates a geographic network of spaces, a directed network of spaces, and a directed network of artifacts, allowing users to link their spaces with friends or people with shared interests and to discover new spaces along these networks. ##### 11.03.05 Creature Module > The idea of the Creature Module is that people naturally form strong emotional connections with different creatures, as they can react, remember, and grow. Their presence turns a static space into a flowing, evolving environment. The Creature Module defines a subclass of `Artifact` that resembles an autonomous agent to users. Creatures can move around and interact with the environment independently, and not only within their owner’s space. Beyond that, they can guide users to explore new spaces, creating new experiences and shared memories. ##### 11.03.06 Plant Module > The idea of the Plant Module is to bring life, growth, and the quiet passing of time into virtual spaces, letting users feel seasons change and their spaces slowly grow and transform. Beyond that, plants naturally produce small gifts — a green leaf, a flower petal, a dandelion puff — that fall over time. These small gifts can be offered to others, left in others’ spaces, or attached to their memories as gentle signs of appreciation. Through plants, small acts of care become organic parts of the virtual world’s memory. The Plant Module defines a subclass of `Artifact` that represents a plant. It provides `Artifact`s that grow and change over time and introduces a gift mechanism that replaces the traditional “like,” providing immediate positive feedback while minimizing long-term metrics and competition by emphasizing each gift event rather than aggregate counts. ## 20 Core Specification The Core Specification defines objects that can be mapped to a scene and objects that represent assets which can be included in the scene. ### 21 Scene #### 21.01 Scene and `Coordinate` type A scene is a vector space $\mathbb{R}^3$. We fix the right-handed orientation and an orthonormal basis, labeled $\hat x$, $\hat y$, and $\hat z$. A point in the space can be expressed as a 3-tuple $(x, y, z) = x\,\hat x + y\,\hat y + z\,\hat z$, where $x$, $y$, and $z$ are real numbers. A `Coordinate` type represents a point in the scene and is an array of three real numbers. It is represented as ```ts type Coordinate = [number, number, number] ``` where the three numbers correspond to $x$, $y$, and $z$, in that order. The ground plane is the subspace of the scene spanned by the basis $\hat x$ and $\hat y$, i.e., the set $\{(x, y, 0)\ |\ x \in \mathbb{R},\; y \in \mathbb{R}\}$. A coordinate projected onto the ground plane can therefore be specified by a 2-tuple $(x, y)$, referred to as the ground plane coordinate. On a plane in the scene, a point can be expressed as a 2-tuple $(u, v)$ with respect to a given orthonormal basis $\hat u$ and $\hat v$, similar to above. A `Coordinate2D` type represents a point in such a plane and is an array of two real numbers. It is represented as ```ts type Coordinate2D = [number, number] ``` where the two numbers correspond to $u$ and $v$, in that order. One can therefore use `Coordinate2D` to express points in the ground plane using the basis $\hat u = \hat x$ and $\hat v = \hat y$. For a plane in the scene, the up direction is defined as $\hat n = \hat u \times \hat v$, where $\times$ is the usual cross product and $\hat u$ and $\hat v$ are the orthonormal basis vectors mentioned above. The up direction of the scene is the up direction of the ground plane, i.e., the positive direction of the basis vector $\hat z$. #### 21.02 Coordinate Transformation A coordinate transformation with uniform scale in the scene defined above transforms a vector $\vec v = (v_x, v_y, v_z)$ to $s\, R \, \vec v + \vec t$, where $R$ is a rotation operator, $s$ is a real number for uniform scale, and $\vec t$ is the translation of the origin. Such a transformation can therefore be encoded in three pieces of information: translation $\vec t$, rotation $R$, and scale $s$. ##### 21.02.01 Rotation and `Euler` Type Rotation can be represented by the type `Euler`, specifying the Euler angles as a 3-tuple $(x, y, z)$ in degree. The rotations are applied in the order of the $x$-axis, then the $y$-axis, then the $z$-axis. It can be represented as ```ts type Euler = [number, number, number] ``` where the three numbers correspond to rotation in degree around the $x$-axis, $y$-axis, and $z$-axis, in that order. For each rotation, a positive value means counterclockwise rotation. A zero rotation on all axes implies that the axes of the transformed coordinate align with those of the scene coordinate. Rotation on a plane can also be represented by an Euler angle as a single number. The rotation is applied around the up-axis of the plane. A `Euler2D` represents such data as ```ts type Euler2D = number ``` where a positive `Euler2D` value means counterclockwise rotation. ##### 21.02.02 Scale and `Scale` Type The type `Scale` represents the scaling of the transformed coordinate about its local origin and is a real number, where a value of 1 means no scaling. It can be represented as ```ts type Scale = number ``` ##### 21.02.03 Local Coordinate A coordinate distinct from the scene coordinate, also referred to as the global coordinate, is called a local coordinate. A local coordinate can be defined by the coordinate transformation above with respect to the scene coordinate, or can be specified by the origin of the local coordinate in the scene coordinate along with the transformed basis; see Section [[TODO: local scene]]. #### 21.03 Entity in the scene Each entity in the scene comes with its own local coordinate, and its placement can therefore be described by the three pieces of information defined in Section 21.02. That is, one starts with the entity's local coordinate coinciding with the scene coordinate, then applies the transformation defined in Section 21.02 to the entity. ### 22 `Form` Type Object A `Form` type object represents the layout of the scene. `Form` type is defined as ```ts interface Form { version: string // REQUIRED layout: Embedding[] // REQUIRED metadata?: FormMetadata // OPTIONAL properties?: FormProperties // OPTIONAL } ``` where - `version` is REQUIRED, and its value MUST be of type `string` equal to one of the standard’s version numbers (see Section [[04-Version-Control]]). - `layout` is REQUIRED, and its value MUST be an array of `Embedding`, representing placed artifacts in the space. An empty layout MUST have the value `[]`. - `metadata` is OPTIONAL, and its value MUST be of type `FormMetadata`. It is used to hold any additional descriptive data about the space. If not provided, an empty `FormMetadata` is used by default. - `properties` is OPTIONAL, and its value MUST be of type `FormProperties`. It represents additional properties of the scene. If not provided, an empty `FormProperties` is used by default. ### 23 `Embedding` Type Object An `Embedding` type object represents an artifact being placed in the scene. `Embedding` type is define as ```ts interface Embedding { artifact: Artifact // REQUIRED position: Coordinate // REQUIRED rotation: Euler // REQUIRED scale?: Scale //OPTIONAL properties?: EmbeddingProperties // OPTIONAL } ``` where - `artifact` is REQUIRED, and its value MUST be of type `Artifact`. - `position` is REQUIRED, and its value MUST be of type `Coordinate`. - `rotation` is REQUIRED, and its value MUST be of type `Euler`. - `scale` is OPTIONAL, and its value MUST be of type `Scale`. - `properties` is OPTIONAL, and its value MUST be of type `EmbeddingProperties`. It stores data that modifies or enhances the placed artifact. An `Embedding` type object represent an artifact been placed at `position` with `rotation` and `scale`, as defined in [[21-Scene#21.03 Entity in the scene]]. ### 24 `Artifact` Type Object The `Artifact` type object represents an asset that can be loaded into the space. `Artifact` type is defined as ```ts interface Artifact { content: string // REQUIRED type: ArtifactType // REQUIRED metadata: Metadata // RECOMMENDED } ``` where * `content` is REQUIRED, and stores the content to be loaded into the scene. * `type` is REQUIRED, and its value MUST be of type `ArtifactType`. It specifies the artifact type of `content` and therefore implies the possible loaders that an implementation can use to load the `content`. * `metadata` is RECOMMENDED, and its value MUST be of type `Metadata`. It stores relevant information about the asset. If it is not provided, the default MUST be used. #### 24.01 `ArtifactType` data The `ArtifactType` indicates the artifact type of the asset and therefore the loader that the implementation needs to use to correctly load it. Modules can define more `ArtifactType` values than those specified in this section. ```ts type ArtifactType = "model" ``` - For `model` artifact type, the implementation need to use a `GLTFLoader` to load the content, following the glTF standard. The artifact type, the `type` member of `Artifact`, and the `ArtifactType` type should not be confused with the JSON object type or JSON type. In this document, the single word "type" is reserved for JSON type. #### 24.02 Artifact Content The artifact content, as specified in the `content` field of the `Artifact` object, MUST be a path or Uniform Resource Locator (URL) to the data that can be loaded by the loader and presented in the scene. For artifact content of type `"model"`, it is RECOMMENDED that the data be a model file following the GLTF standard. When loaded, such a model contains a local origin. ### 25 `Metadata` Type Object The `Metadata` type object stores data relevant to an asset. All members in `Metadata` are OPTIONAL and if they are not specified, the default value will be used. Modules and extension specifications can define additional members in type `Metadata` beyond those specified in this section. It is RECOMMENDED that modules make use of the `attachment` and `properties`members rather than introducing new members in the `Metadata` type. `Metadata` type is define as ```ts interface Metadata { id: string, name: string, description: string, preview: string, creators: string[], attachments: ArtifactAttachments properties: ArtifactProperties // ... } ``` where * `id` MUST be of type `string` representing the path or asset ID of the artifact. Its default value is the `content` string of the artifact. It is RECOMMENDED that all artifacts loaded in the scene have distinct `id` values. * `name` MUST be of type `string` and is the display name of the artifact. Its default value is `"Artifact"`. * `description` MUST be of type `string` and is the display description of the artifact. Its default value is `""`, i.e., an empty string. * `preview` MUST be of type `string` containing the URL to the preview image file, and it is RECOMMENDED that the preview image file be of type PNG. * `creators` MUST be an array of `string` representing the creators of the artifact. * `attachment` MUST be of type `ArtifactAttachments`, representing any associated files relevant to this artifact. The `attachment` member is mainly used by modules and extension specifications. * `properties` MUST be of type `ArtifactProperties`. It stores data that modifies or enhances the artifact's behavior in the scene. The `properties` member is mainly used by modules and extension specifications. ### 26 Enhancing and Modifying the Scene From the `Form` data, one can reconstruct a scene by placing each artifact in `layout` according to its placement as specified in the `Embedding`, defined in [[21-Scene]]. Modules can also add additional information to enhance or modify the scene by making use of the `FormMetadata`, `FormProperties`, and `EmbeddingProperties` types. These types by default include only empty objects, i.e., objects with no members, representing no additional or altered behavior beyond placing artifacts in the `layout` member. In this section, we go through some modules that can be used to enhance or modify the scene. These modules are not part of the core specification and implementations MAY implement them. #### 26.01 Form Metadata Module The Form Metadata module enhances the scene by adding descriptive data for the space, specified in the `FormMetadata` object. It is RECOMMENDED to include the following data to record basic information about the space: - `name` of type `string` - `description` of type `string` - `owner` of type `string` - `creator` of type `string` All other data in `FormMetadata` are OPTIONAL. An example of `FormMetadata` can be represented as: ```ts interface FormMetadata { name: string // RECOMMENDED description: string // RECOMMENDED owner: string // RECOMMENDED creator: string // RECOMMENDED // ... } ``` #### 26.02 Sky Module The Sky module enhances the scene by introducing two new members in `FormProperties` and a new artifact type, allowing a skybox to be specified for the scene. The new member in `FormProperties` is defined as ```ts interface FormProperties { sky: Artifact // OPTIONAL skyVisible: boolean // OPTIONAL // ... } ``` where * `sky` is OPTIONAL, and its value MUST be of type `Artifact` with artifact type `hdri`. * `skyVisible` is OPTIONAL, and its value MUST be of type `boolean`. If it is not provided, the default value `false` MUST be used. The new artifact type is defined as ```ts type ArtifactType = "hdri" // ... ``` and the implementation MUST use an `EXRLoader` to load the content, following the EXR standard. When `sky` in `FormProperties` is specified, a supported implementation MUST use the `content` of the specified artifact as the skybox of the scene. If the `sky` member is not provided, the implementation may use a default skybox or no skybox. When a skybox is present and `skyVisible` is `true`, the skybox MUST be rendered as the visible background. Otherwise, there MUST be no visible background rendered, and the skybox, if present, is used only for environment lighting and reflections. An implementation that does not support the Sky module MUST ignore the `sky` and `skyVisible` member of `FormProperties` and discard any artifact with artifact type `hdri`. When used with the Category module, the artifact MUST use `sky` as its artifact category. ```ts type Category = "sky" // ... ``` #### 26.03 Environment Model Module The Environment Model module enhances the scene by introducing a new member in `FormProperties`, allowing an environment model to be specified for the scene. The new member in `FormProperties` is defined as ```ts interface FormProperties { environmentModel: Artifact // OPTIONAL // ... } ``` where * `environmentModel` is OPTIONAL, and its value MUST be of type `Artifact` with artifact type `model`. When `environmentModel` in `FormProperties` is specified, a supported implementation MUST place the `content` of the specified artifact at the origin of the scene. If the `environmentModel` member is not provided, the implementation MUST NOT render any environment model. An implementation that does not support the Environment Model module MUST ignore the `environmentModel` member of `FormProperties`. When used with the Category module, the artifact MUST use `environment` as its artifact category. ```ts type Category = "environment" // ... ``` #### 26.04 Boundary Module and Tile Module ##### 26.04.01 Boundary Module The Boundary module modifies the scene by introducing a new member in `FormProperties`, defining a horizontal boundary of the scene. The new member in `FormProperties` is defined as ```ts interface FormProperties { boundary: OBB[] // OPTIONAL // ... } ``` where * `boundary` is OPTIONAL, and its value MUST be an array of `OBB` type objects. An `OBB` type object represents an oriented rectangle on the ground plane, defined by its `center`, its `rotation` about the center, and its `halfWidth` and `halfLength`. The `OBB` type is defined as ```ts interface OBB { center: Coordinate2D // REQUIRED rotation: Euler2D // REQUIRED halfWidth: number // REQUIRED halfLength: number // REQUIRED } ``` where - `center` is REQUIRED, and its value MUST be of type `Coordinate2D`. It represents the center of the oriented rectangle on the ground plane. - `rotation` is REQUIRED, and its value MUST be of type `Euler2D`. It represents the rotation of the rectangle about its center. - `halfWidth` is REQUIRED, and its value MUST be a `number`. It represents half the width of the rectangle, aligned with the $x$-axis at rotation 0. - `halfLength` is REQUIRED, and its value MUST be a `number`. It represents half the length of the rectangle, aligned with the $y$-axis at rotation 0. ##### 26.04.02 Tile Module The Tile module modifies the scene by introducing three new members in `FormProperties`, defining a tiled horizontal boundary of the scene. The new members in `FormProperties` are defined as ```ts interface FormProperties { tileList: Coordinate2D[] // OPTIONAL tileModel: Artifact // OPTIONAL tileVisible: boolean // OPTIONAL // ... } ``` where * `tileList` is OPTIONAL, and its value MUST be an array of `Coordinate2D`. It represents a tiled horizontal boundary of the scene as an array of positions of square tiles on the ground plane. * `tileModel` is OPTIONAL, and its value MUST be of type `Artifact`. It represents the visual representation of each tile in the scene. Its value MUST be ignored if `tileList` is not specified, or if `tileVisible` is `false`, or both. * `tileVisible` is OPTIONAL, and its value MUST be of type `boolean`. It represents the visibility toggle of the tile model. If it is not provided, the default value `true` MUST be used. Its value MUST be ignored if `tileList` is not specified. When `tileVisible` is `true` and `tileModel` is specified, the implementation MUST place `tileModel` at each position on the ground plane specified by `tileList` with zero rotation as the visual representation of each tile. When working with the Layout Mode module, the placed `tileModel` MUST NOT affect the reconstruction logic of the scene and MUST NOT appear in the `layout` data. When `tileVisible` is `true` and `tileModel` is not specified, the implementation MAY use its own `Artifact` as `tileModel` for the visual representation of the tile. It is RECOMMENDED to use a mid-tone gray plane with dimensions 1 by 1 as the default visual representation of each tile. When `tileVisible` is `false`, there MUST NOT be any visual representation of the tile and the value of `tileModel` MUST be ignored. When used with the Category module, the artifact that can be used as value of `tileModel` MUST use `tile` as its artifact category. ```ts type Category = "tile" // ... ``` ##### 26.04.03 Horizontal Boundary of the Scene A horizontal boundary of the scene is defined by a list of oriented rectangles, commonly referred to as oriented bounding boxes (OBBs), as defined in [[26.04-Boundary-Module-and-Tile-Module#26.02.02 Boundary Module]], lying on the ground plane. The union of the specified list of OBBs defines the inside of the scene, and any point that does not lie within this union is considered outside of the scene. The line where the outside and the inside of the scene meet is the scene boundary. For general artifacts, the ground plane $(x, y)$ placement, i.e., the projection of its $(x, y, z)$ placement onto the ground plane, MUST NOT lie outside of the scene. This means its $(x, y)$ placement may lie on the scene boundary by the definition of outside of the scene. Any artifact whose $(x, y)$ placement lies outside of the scene MUST be removed during reconstruction of the scene. When working with the Layout Mode module, for artifacts participating in stacking logic, no point of such an artifact's footprint MUST lie outside of the scene. That is, such artifacts in `layout` MUST be removed before the stacking logic is applied. When the Boundary module, the Tile module, or both are used, the boundary can be specified by the `boundary` member, the `tileList` member, or both, in `FormProperties`. When the boundary is specified by `boundary`, its value directly gives the OBBs of the boundary. When the boundary is specified by `tileList`, it is equivalent to a list of OBBs with zero rotation and width and length of 1, i.e., `halfWidth` and `halfLength` of 0.5, centered at each element of `tileList`. When both `boundary` and `tileList` are specified, the boundary is their intersection. When neither `boundary` nor `tileList` is specified, or both modules are not supported by the implementation, there is no boundary for the scene and every point in the scene is considered to lie within the boundary. One MUST NOT confuse the case where these data are specified as empty lists, which indicates that every point lies outside of the boundary, with the case where these data are not specified, which indicates that there is no boundary and every point in the scene lies within the boundary. Please note that this boundary is the boundary of the scene, not the boundary for avatar movement. For the boundary of avatar movement, please see [[TODO]]. #### 26.05 Layout Mode Module The Layout Mode module modifies the scene by introducing different layout modes. The original layout, i.e., each artifact placed in the scene with all possible positions, rotations, and scales as specified in the `Embedding` type object, is referred to as the freeform layout mode in the Layout Mode module. Other layout modes are restrictions on the freeform mode that are more suitable for particular uses of the space. Besides the freeform layout mode, four layout modes are specified, each with a two-dimensional and a three-dimensional version. Other modules can extend this module by introducing new layout modes. The layout modes defined by this module are: - Continuous layout mode - Discrete layout mode - Block layout mode - Slot layout mode The Layout Mode module introduces a few new members in `FormProperties`. The central member is the `layoutMode` member, defined as ```ts interface FormProperties { layoutMode: LayoutMode // OPTIONAL // ... } ``` where - `layoutMode` is OPTIONAL, and its value MUST be of type `LayoutMode`. It specifies which layout mode is used. If not provided, the freeform layout mode is used by default. The `LayoutMode` type is defined as ```ts type LayoutMode = | 'freeform' | 'continuous' | 'discrete' | 'block' | "slot" | 'flat-freeform' | 'flat-continuous' | 'flat-discrete' | 'flat-block' ``` where - `freeform` indicates the freeform layout mode in three dimensions. - `continuous` indicates the continuous layout mode in three dimensions. It does not have restrictions on position, but the placement must follow the stacking logic. - `discrete` indicates the discrete layout mode in three dimensions. It imposes a cell-placement rule and a stacking logic. - `block` indicates the block layout mode in three dimensions. It imposes a block-placement rule and allows only artifacts whose `volume` in each dimension is exactly 1 or an integer to be placed in the scene. - `slot` indicates the slot layout mode. It allows artifacts to be placed only at specified slots with specified orientations. - `flat-freeform` indicates the freeform layout mode in two dimensions. - `flat-continuous` indicates the continuous layout mode in two dimensions. - `flat-discrete` indicates the discrete layout mode in two dimensions. - `flat-block` indicates the block layout mode in two dimensions. The terms "cell-placement rule", "stacking logic", "block-placement rule", and "volume" will be defined throughout this section. Other modules extending this module can define more `LayoutMode` values than those specified in this section. Implementations supporting the Layout Mode module MAY support only one or more of the layout modes. Implementations SHOULD state which layout modes are supported. ##### 26.05.01 Reconstruction Logic The reconstruction logic takes a `Form` with a specified layout mode and outputs a `layout` following the specified layout mode restrictions, derived from the original `layout` in `Form`. The output `layout` is then used to reconstruct the scene by placing each artifact in the output `layout` according to its placement as specified in the `Embedding`, as defined in [[21-Scene]]. The reconstruction logic therefore refers to how to produce a `layout` following the restrictions from the original `layout`. The reconstruction logic MUST be idempotent: re-applying it to its own output MUST yield the same `layout`, i.e., if $f$ is the function representing a given reconstruction logic and $\Lambda$ is the input `Form`, then $f(f(\Lambda)) = f(\Lambda)$. For the freeform layout mode, the `layout` in the input `Form` is the output `layout` and is directly used for the reconstruction of the scene. ##### 26.05.02 Artifact Volume Artifact volume models each artifact as a three-dimensional box. The box then participates in the reconstruction logic, instead of relying on the explicit content of the artifact. For layout modes that use artifact volume, the `scale` member of the `Embedding` object SHOULD be ignored and a new member is introduced to `Artifact`'s `properties`: ```ts interface ArtifactProperties { volume: Volume // RECOMMENDED // ... } ``` where - `volume` is RECOMMENDED, and its value MUST be of type `Volume`. If it is not provided but is needed for the reconstruction logic, the default value MUST be used. The `Volume` type object is used to represent the dimensions of the artifact for the reconstruction logic, such as the stacking logic. The `Volume` type is defined as ```ts type Volume = { width: number // REQUIRED length: number // REQUIRED height: number // REQUIRED } ``` where each member is REQUIRED. If the artifact has not been rotated in the scene, then - `width` corresponds to the x-axis in the scene. - `length` corresponds to the y-axis in the scene. - `height` corresponds to the z-axis in the scene. The default value for `volume` is `1` for each member of the `Volume` type. Implementations SHOULD proportionally scale down oversized artifacts to fit within their volume box, or their volume box multiplied by a factor. The Layout Mode module introduces two new members in `FormProperties`: ```ts interface FormProperties { volumeBoxLimit: [boolean, boolean, boolean] // OPTIONAL scaleVolumeMultiplier: [number, number, number] // OPTIONAL // ... } ``` where - `volumeBoxLimit` is OPTIONAL and its value MUST be an array of 3 `boolean` values, corresponding to which directions the volume box limit is imposed on, where the three `boolean` values represent whether the limit is imposed on `width`, `length`, and `height`, in that order. If it is not provided, the default value `[true, true, true]` MAY be used, or implementations MAY use their own default value and SHOULD state the default value they use.[^1] - `scaleVolumeMultiplier` is OPTIONAL and its value MUST be an array of 3 `number` values. It represents the tolerance for oversized artifacts and the target size of the scale-down on `width`, `length`, and `height`, in that order. On each direction, the artifact SHOULD be scaled down to its `volume` on that direction multiplied by the corresponding element in `scaleVolumeMultiplier`. If the corresponding value in `volumeBoxLimit` is `false` for that direction, then the corresponding value in `scaleVolumeMultiplier` MUST be ignored. If it is not provided, the default value `[1, 1, 1]` MAY be used, or implementations MAY use their own default value and SHOULD state the default value they use.[^2] [^1]: In the reference implementation Exterior Space, the default value `[true, true, false]` is used for `volumeBoxLimit` to allow oversizing in height. [^2]: In the reference implementation Exterior Space, the default value `[1.5, 1.5, 1.5]` is used for `scaleVolumeMultiplier` to allow slightly oversized artifacts. ##### 26.05.03 Stacking Logic The idea of the stacking logic is to provide an intuitive way to organize the space for general users. The intuition behind the stacking logic is to airdrop artifacts from above, one by one, so that each newly dropped artifact stacks on top of the existing artifacts. The stacking logic makes use of the `volume` of the artifact, as defined in [[26.05.02-Artifact-Volume]]. ###### 26.05.03.01 Requirements of the Stacking Logic The artifact itself, i.e., the `Artifact` object, that participates in the stacking logic MUST have `volume`, as defined in [[26.05.02-Artifact-Volume]]. `Artifact` objects MAY have additional data, `evenPlacement` and `stackable`, to alter their behavior in the stacking logic. If these data are not provided, default behavior applies, corresponding to the specified default values. `Form` objects MAY have additional data in `FormProperties`, such as `spaceHeight`, `evenBandTolerance`, `coverageThreshold`, and `coverageThresholdEven`, to alter the behavior of the stacking logic. If these data are not provided, default behavior applies, corresponding to the specified default values. ###### 26.05.03.02 Alter the Scene Level Stacking Logic The Layout Mode module introduces a few new members in `FormProperties` to adjust the behavior of the stacking logic. The new members in `FormProperties` are defined as ```ts interface FormProperties { spaceHeight: number // OPTIONAL evenBandTolerance: number // OPTIONAL coverageThreshold: number // OPTIONAL coverageThresholdEven: number // OPTIONAL // ... } ``` where - `spaceHeight`, `evenBandTolerance`, `coverageThreshold`, and `coverageThresholdEven` are all OPTIONAL and their values MUST all be of type `number`. They are parameters that can be specified to alter the default behavior of the stacking logic. When not specified, the implementation MUST use their default values in the stacking logic. The default values for these parameters are given in the following table. | Parameter | Default value | | ----------------------- | ------------- | | `spaceHeight` | 3 | | `evenBandTolerance` | 0.05 | | `coverageThreshold` | 0.1 | | `coverageThresholdEven` | 0.9 | ###### 26.05.03.03 Alter the Artifact Level Stacking Logic The Layout Mode module introduces a few new members in `ArtifactProperties` to adjust the behavior of the stacking logic. The new members in `ArtifactProperties` are defined as ```ts interface ArtifactProperties { evenPlacement: boolean // OPTIONAL stackable: boolean // OPTIONAL stacking: boolean // OPTIONAL // ... } ``` where `evenPlacement`, `stackable`, and `stacking` are all OPTIONAL and their values MUST all be of type `boolean`. They are parameters that can be specified to alter the default behavior of the stacking logic. When not specified, the implementation MUST use their default values in the stacking logic if no other module alters the default value. The default value for `evenPlacement` is `false`, for `stackable` is `true`, and for `stacking` is `true`. When working with the Category module, the default values MUST follow the default values defined for each category. An artifact with `stacking` set to `false` will not participate in the stacking logic. ###### 26.05.03.04 The Input and Result of the Stacking Logic The stacking logic takes an input `layout` from `Form` and produces a resulting `layout` in which each element, if it participates in the stacking logic, follows the stacking logic. For artifact $i$, its original placement can be written as $(x_i', y_i', z_i')$ before performing the stacking logic, where $i$ indexes artifacts in the input `layout` that participate in the stacking logic. The resulting placement can be written as $(x_i, y_i, z_i)$ after performing the stacking logic. For artifact $i$, its original rotation can be written as the Euler angle $(\alpha_i', \beta_i', \gamma_i')$ before performing the stacking logic, where $i$ indexes artifacts in the input `layout` that participate in the stacking logic. The resulting rotation can be written as $(\alpha_i, \beta_i, \gamma_i)$ after performing the stacking logic. The stacking logic alters the height of the artifact and the rotations around the $x$- and $y$-axes. The ground plane coordinate and the rotation around the $z$-axis are left unchanged. ###### 26.05.03.05 Stacking Index A stacking index can be intuitively understood as the order in which artifacts are air-dropped into the scene. Given a list of `Embedding` objects, i.e., the `Embedding`s in the `layout` of the `Form` object that are participating in the stacking logic, one can order them by their height, i.e., $z_i'$ as defined in [[26.05.03-Stacking-Logic#26.05.03.04 The Input and Result of the Stacking Logic]], from smallest to largest, with ties broken by order of appearance in the `layout` list. The stacking index of an `Embedding` in the list is then defined by the position of the `Embedding` in the ordered list. In the following sections, this stacking index obtained from the `layout` with artifacts participating in the stacking logic will be referred to as `stackIndex`. ###### 26.05.03.06 Performing the Stacking Logic Conceptually, the stacking logic models each artifact as a box according to its `volume` and airdrops the to-be-placed artifact $i$ in ascending order of its `stackIndex` at the ground plane coordinate $(x_i', y_i')$, placing it on top of the already placed artifacts. The height of the top of the supporting artifact is therefore the $z_i$ of the to-be-placed artifact $i$, and the ground plane coordinate is unchanged, i.e., $(x_i, y_i) = (x_i', y_i')$. Each artifact has only $z$-axis rotation and rotations around other axes are ignored. Therefore the resulting rotation is $(\alpha_i, \beta_i, \gamma_i) = (0, 0, \gamma_i')$. If the placed artifact that directly supports the to-be-placed artifact is not `stackable`, the airdrop fails, the to-be-placed artifact is withdrawn, and the process moves on to airdrop the next artifact. If the to-be-placed artifact would be supported by multiple artifacts that do not form an even surface, and the to-be-placed artifact requires `evenPlacement`, the airdrop fails, the to-be-placed artifact is withdrawn, and the process moves on to airdrop the next artifact. ###### Algorithm This process of performing stacking logic can be operated by the following steps. The $z_i$ of the placed artifact $i$ in the scene MUST be able to be reproduced by these steps regardless of the implementation of the stacking logic. ###### Definitions - **Footprint** of an `Embedding`: the oriented rectangle on the ground plane obtained from its ground plane coordinate and the $z$-axis rotation at the beginning of the stacking logic, and the artifact’s `volume.width` and `volume.length`. Mesh geometry is not consulted. At 0 $z$-axis rotation, width aligns with $x$, length with $y$. - **Top** of a support: the support’s base height $z$ plus its `volume.height`. - **Positive-area overlap**: two ground rectangles “overlap” only if their intersection has non-zero area; touching along an edge or at a point does not count. ###### Algorithm 0. **Preparing for the Stacking Logic** For each artifact in the input `layout`, identify only those participating in the stacking logic and set their $x$- and $y$-axis rotations to zero. To focus only on the relevant data in the stacking logic, in the following steps, `rotation` refers to the $z$-axis rotation, `position` refers to the ground plane coordinate, and `layout` refers to the input `layout` with only participating artifacts. Artifacts that do not participate in the stacking logic are output as-is. 1. **Order to place.** Order all embeddings in `layout` by ascending `stackIndex`. Process them in that order. Let the already processed ones be the “placed set.” 2. **For each to-be-placed artifact $i$: build its ground context.** 1. Compute its **footprint** from its `position`, `rotation`, and `volume`. 2. Create an initial list of **supports** consisting of: 1. the **floor** at height 0 with the same footprint, treated as `stackable = true`; and 2. every embedding already in the placed set whose footprint has **positive-area overlap** with $i$’s footprint. 3. For each such support, record its footprint, its **top** (base $z$ plus `volume.height`), and whether its artifact is **stackable**. 3. **Find the highest resting level.** Let $H$ be the maximum **top** among all supports gathered in step 2 (including the floor’s top at 0). Intuitively, this is the height where $i$ would first make contact from above. 4. **Respect the form’s height cap.** 1. Let $h_i$ be $i$’s `volume.height`, and let $Z_{\max}$ be the form’s `spaceHeight`. 2. If $H + h_i$ exceeds $Z_{\max}$, the placement of $i$ is **invalid** (it would protrude past the allowed space height). Do not place $i$; continue with the next artifact from step 2. 5. **Select which supports “count” at the contact level.** Collect the **band supports**: those supports whose **top** lies at and within this band. - If $i$’s artifact has `evenPlacement = true`, then the **support band** is the vertical interval from $H - \texttt{evenBandTolerance}$ up to $H$. - Otherwise, the support band collapses to the single level $H$. 6. **Enforce the stackable rule at the band.** Every **band support** must be `stackable`. - If any band support is not stackable, the placement of $i$ is **invalid**. Do not place $i$; continue with the next artifact from step 2. 7. **Require sufficient supporting area at the band.** Compute how much of $i$’s footprint is covered by the union of the **band supports’** footprints (on the ground plane). The **coverage** is the ratio of the covered area to the total area of $i$’s footprint, a value between 0 and 1. - If $i$ has `evenPlacement = true`, this **coverage** MUST be at least `coverageThresholdEven`. - Otherwise, the **coverage** MUST be at least `coverageThreshold`. If the required coverage is not met, the placement of $i$ is **invalid**. Do not place $i$; continue with the next artifact from step 2. 8. **Assign the height.** If steps 4–7 all pass, set $z_i = H$. The artifact $i$ is considered **placed** at $(x_i, y_i, z_i)$, where $(x_i, y_i)$ comes from its original `position`. Add $i$ to the placed set and proceed to the next artifact from step 2. After iterating through the ordered `layout`, each successfully placed artifact $i$ has a determined height $z_i$. Artifacts that violated the height cap, stackability, or area-coverage requirements at their contact level are not placed. ###### 26.05.03.07 The Stacking Logic in the Flat Layout Mode In the flat layout mode, the stacking logic is applied with `spaceHeight` set to zero and `volume.height` overridden to zero. This forbids overlapping footprints. If a to-be-placed artifact’s footprint overlaps an existing one, do not place it. Effectively, when any overlap occurs, the artifact with the smaller `stackIndex` prevails. ##### 26.05.04 Cell Placement Cell-placement constrains the placement of artifacts onto a grid for easy placement for general users. Cell-placement is not compatible with block-placement. The cell-placement makes use of the `volume` of the artifact, as defined in [[26.05.02-Artifact-Volume]]. ###### 26.05.04.01 Requirements of the Cell-placement The artifact itself, i.e., the `Artifact` object, that participates in the cell-placement MUST have `volume`, as defined in [[26.05.02-Artifact-Volume]]. ###### 26.05.04.02 Alter the Artifact Level Cell-placement The Layout Mode module introduces a new member in `ArtifactProperties` to adjust the behavior of the cell-placement. The new member in `ArtifactProperties` is defined as ```ts interface ArtifactProperties { snapping: boolean // OPTIONAL // ... } ``` where `snapping` is OPTIONAL and its value MUST be of type `boolean`. When not specified, the implementation MUST use the default value `true` if no other module alters the default value. When working with the Category module, the default value MUST follow the default value defined for each category. An artifact with `snapping` set to `false` will not participate in the cell-placement. ###### 26.05.04.03 The Input and Result of the Cell-placement Snapping The cell-placement snapping takes an input `layout` from `Form` and produces a resulting `layout` in which each element in the `layout` list, if it participates in the snapping, follows the cell-placement. For artifact $i$, its original placement can be written as $(x_i', y_i', z_i')$ before performing the cell-placement snapping, where $i$ indexes artifacts in the input `layout` that participate in the cell-placement snapping. The resulting placement can be written as $(x_i, y_i, z_i)$ after performing the cell-placement snapping. For artifact $i$, its original rotation can be written as the Euler angle $(\alpha_i', \beta_i', \gamma_i')$ before performing the cell-placement snapping, where $i$ indexes artifacts in the input `layout` that participate in the cell-placement snapping. The resulting rotation can be written as $(\alpha_i, \beta_i, \gamma_i)$ after performing the cell-placement snapping. The cell-placement snapping alters the ground plane coordinate of the artifact and the rotation. The height is left unchanged. ###### 26.05.04.04 Snap the Rotation The cell placement allows only $z$-axis rotation. The input $x$ and $y$-axis rotations will be mapped to 0 during the snapping. To focus only on the relevant data in the cell-placement, in the following sections, `rotation` refers to the $z$-axis rotation, as rotation around any other axis is mapped to zero. The snapped $z$-axis rotation together with zero rotation on the other axes is the resulting `rotation` for each `Embedding`. Cell-placement allows artifacts to have only $z$-axis rotations of 0, 90, 180, or 270 degrees. This means the value of the resulting `rotation` around $z$-axis MUST be in the set $\{k\, 90\degree\mid k\in\mathbb{Z}\}$. ###### 26.05.04.05 Snap the Position The cell placement constrains the position horizontally, i.e., the ground plane coordinate $(x, y)$, and the height $z$ is left unchanged. In the following section, it should be understood that the snapping is performed on the ground plane coordinate. The ground plane is divided into cells of size $\frac{1}{2}$ by $\frac{1}{2}$. The cells are placed so that the origin of the ground plane coincides with the corner points of nearby cells. Therefore, - the center of a cell belongs to the set $\{(a, b)\mid a, b \in \mathbb{Z} + \{\pm\frac{1}{4}\}\}$, known as the cell lattice, - the corners (vertices) of the cells belong to the set $\{(a, b)\mid a, b \in \tfrac{1}{2}\mathbb{Z}\}$, where $\tfrac{1}{2}\mathbb{Z}$ denotes all integers and half-integers, known as the vertex lattice. A valid placement of an `Embedding` MUST have the corners of its rounded volume’s footprint, as defined in [[26.05.04-Cell-Placement#26.05.04.06 Rounding Rule]], coincide exactly with points in the vertex lattice. Moreover, the above rules mean: - If the rounded `volume.length` is an integer, then the coordinate in the length direction must lie in $\tfrac{1}{2}\mathbb{Z}$. - If the rounded `volume.length` is a half-integer, then the coordinate in the length direction must lie in $\mathbb{Z} + \{\pm\tfrac{1}{4}\}$. - The same rule applies to the rounded `volume.width`. Note that a 90 or 270 degrees rotation swaps length and width in the scene coordinates. ###### 26.05.04.06 Rounding Rule When performing cell-placement snapping, an `Embedding` MUST be rounded to respect the cell-placement as follows in the following order 1. The `rotation` of the `Embedding` MUST be rounded to the nearest value defined in [[26.05.04-Cell-Placement#26.05.04.04 Snap the Rotation]]. If it is exactly between two legal values, it MUST round to the larger value. 2. Each element of the `Artifact`’s `volume`, for the purposes of cell-placement and stacking logic, MUST be rounded up (ceiling) to the next integer or half-integer, i.e., an element in $\tfrac{1}{2}\mathbb{Z}$. The volume after being rounded up is called the rounded volume. The footprint calculated using the rounded volume is therefore its rounded volume’s footprint. 3. Each element of the `Embedding`’s `position` MUST be rounded to the nearest value defined in [[26.05.04-Cell-Placement#26.05.04.05 Snap the Position]]. If it is exactly between two legal values, it MUST round to the larger value. ##### 26.05.05 Block Placement Block-placement snaps the placement of artifacts onto a block grid. Block-placement is not compatible with cell-placement. The block-placement makes use of the `volume` of the artifact, as defined in [[26.05.02-Artifact-Volume]]. ###### 26.05.05.01 Requirements of the Block-placement The artifact itself, i.e., the `Artifact` object, that participates in the block-placement MUST have `volume`, as defined in [[26.05.02-Artifact-Volume]]. ###### 26.05.05.02 Alter the Artifact Level Block-placement The Layout Mode module introduces a new member in `ArtifactProperties` to adjust the behavior of the block-placement. The new member in `ArtifactProperties` is defined as ```ts interface ArtifactProperties { snapping: boolean // OPTIONAL // ... } ``` where `snapping` is OPTIONAL and its value MUST be of type `boolean`. When not specified, the implementation MUST use the default value `true` if no other module alters the default value. When working with the Category module, the default value MUST follow the default value defined for each category. An artifact with `snapping` set to `false` will not participate in the block-placement. ###### 26.05.05.03 The Input and Result of the Block-placement Snapping The block-placement snapping takes an input `layout` from `Form` and produces a resulting `layout` in which each element in the `layout` list, if it participates in the snapping, follows the block-placement. For artifact $i$, its original placement can be written as $(x_i', y_i', z_i')$ before performing the block-placement snapping, where $i$ indexes artifacts in the input `layout` that participate in the block-placement snapping. The resulting placement can be written as $(x_i, y_i, z_i)$ after performing the block-placement snapping. For artifact $i$, its original rotation can be written as the Euler angle $(\alpha_i', \beta_i', \gamma_i')$ before performing the block-placement snapping, where $i$ indexes artifacts in the input `layout` that participate in the block-placement snapping. The resulting rotation can be written as $(\alpha_i, \beta_i, \gamma_i)$ after performing the block-placement snapping. ###### 26.05.05.04 Snap the Rotation Block-placement allows artifacts to have only rotations of 0, 90, 180, or 270 degrees. This means all values of all members of the resulting `rotation` MUST be in the set $\{k\, 90 \degree\mid k\in\mathbb{Z}\}$. ###### 26.05.05.05 Snap the Position The scene is divided into cells of size $1$ by $1$ by $1$. The cells are placed so that the origin of the scene is the center of a cell. Therefore, - the center of a cell belongs to the set $\{(a, b, c)\mid a, b, c \in \mathbb{Z}\}$, known as the cell lattice, - the corners (vertices) of the cells belong to the set $\{(a, b, c)\mid a, b, c \in \mathbb{Z} + \tfrac{1}{2}\}$, where $\mathbb{Z} + \tfrac{1}{2}$ denotes all half-integers, known as the vertex lattice. A valid placement of an `Embedding` MUST have the corners of its rotated rounded volume, as defined in [[26.05.05-Block-Placement#26.05.05.06 Rounding Rule]], coincide exactly with points in the vertex lattice. Moreover, the above rules mean: - If `volume.length` is an odd integer, then the coordinate in the length direction must lie in $\mathbb{Z}$. - If `volume.length` is an even integer, then the coordinate in the length direction must lie in $\mathbb{Z} + \tfrac{1}{2}$. - The same rule applies to `volume.width` and `volume.height`. Note that a 90 or 270 degrees rotation swaps between length, width, and height in the scene coordinates. ###### 26.05.05.06 Rounding Rule When performing block-placement snapping, an `Embedding` MUST be rounded to respect the block-placement as follows in the following order 1. Each member of `rotation` for the `Embedding` MUST be rounded to the nearest value defined in [[26.05.05-Block-Placement#26.05.05.04 Snap the Rotation]]. If a value is exactly between two legal values, it MUST be rounded up to the larger value. 2. Each element of the `Artifact`’s `volume`, for the purposes of block-placement, MUST be rounded up (ceiling) to an integer. The volume after being rounded up is called the rounded volume. 3. Each element of the `Embedding`’s `position` MUST be rounded to the nearest value defined in [[26.05.05-Block-Placement#26.05.05.05 Snap the Position]]. If it is exactly between two legal values, it MUST round to the larger value. To respect the block-placement, it is usually easier in an implementation to round the rotation and volume first, then round the position. ###### 26.05.05.07 Block-placement in Flat Layout Mode In flat layout mode, artifacts are placed on a plane. The plane is divided into cells of size $1$ by $1$. The cells are placed so that the origin of the scene is the center of a cell. Therefore, - the center of a cell belongs to the set $\{(a, b)\mid a, b \in \mathbb{Z}\}$, known as the cell lattice, - the corners (vertices) of the cells belong to the set $\{(a, b)\mid a, b \in \mathbb{Z} + \tfrac{1}{2}\}$, where $\mathbb{Z} + \tfrac{1}{2}$ denotes all half-integers, known as the vertex lattice. A valid placement of an `Embedding` MUST have the corners of its rotated rounded volume, as defined in [[26.05.05-Block-Placement#26.05.05.06 Rounding Rule]], coincide exactly with points in the vertex lattice. The rotated volume in the $z$ direction of the artifact is ignored and is effectively overridden to zero. It is RECOMMENDED that all rotations are around the $z$ axis, i.e., the `volume.height` is consistently ignored. The rotation snapping works as specified in [[26.05.05-Block-Placement#26.05.05.04 Snap the Rotation]]. ##### 26.05.06 Slot Placement Slot-placement places artifacts in a set of predefined slots. ###### 26.05.06.01 Requirements of the Slot-placement The Slot-placement introduces a new member in `FormProperties` to represent the slots allowing for placing artifacts. It is defined as ```ts interface FormProperties { slotProfile: SlotProfile // OPTIONAL // ... } ``` where `slotProfile` is OPTIONAL and MUST be of type `SlotProfile`. If `slotProfile` is not present, then slot-placement MUST NOT be performed regardless of layout mode. If layout mode is not slot layout mode, `slotProfile` SHOULD be ignored unless specified and used by other modules. The input `Form` for slot-placement MUST have a `slotProfile` in its `properties` member. The slot-placement introduces two new members in `EmbeddingProperties` to represent which slot the artifact is placed in. They are defined as ```ts interface EmbeddingProperties { slotIndex: number // OPTIONAL slotOrientationIndex: number // OPTIONAL // ... } ``` where - `slotIndex` is OPTIONAL and MUST be of type `number` and MUST be an integer. - `slotOrientationIndex` is OPTIONAL, and MUST be of type `number` and MUST be an integer. The `Embedding` participating in slot-placement MUST have an `EmbeddingProperties` with member `slotIndex`. Embeddings not carrying it MUST NOT participate in slot-placement. ###### 26.05.06.02 Define Slot and `SlotProfile` and `Slot` Type Object A `SlotProfile` type object defines the slots available in the scene. It is defined as ```ts interface SlotProfile { slots: Slot[] // REQUIRED } ``` where - `slots` is REQUIRED and MUST be an array of `Slot`. Each `Slot` in the array MUST have a distinct `slotIndex`. A `Slot` defines a slot in the scene. It MUST be representable as a JSON object, contain only JSON-serializable values, and contain the following data. ```ts interface Slot { slotIndex: number // REQUIRED position: Coordinate // REQUIRED slotRotation: SlotRotation // OPTIONAL } ``` where - `slotIndex` is REQUIRED, and its value MUST be of type `number` and MUST be an integer. - `position` is REQUIRED and it MUST be of type `Coordinate`. - `slotRotation` is OPTIONAL, and its value MUST be of type `SlotRotation`. When `slotRotation` is not provided, it indicates zero rotation on all axes. A `SlotRotation` defines the possible rotations for the artifact. ```ts interface SlotRotation { rotationStep: number // OPTIONAL rotationStepAxis: Coordinate // OPTIONAL eulerStep: Euler[] // OPTIONAL } ``` - `rotationStep` is OPTIONAL and its value MUST be of type `number` and MUST be an integer. `rotationStep` indicates the allowed rotations around `rotationStepAxis` by $\frac{k\,360\degree}{N}$, where $N$ is the integer specified by `rotationStep` and $k$ is an integer that can be specified via `slotOrientationIndex` in `EmbeddingProperties`. A `rotationStep` of zero indicates that smooth rotation is allowed and, in the `Embedding`, the rotation MUST be specified in `rotation`. - `rotationStepAxis` is OPTIONAL and its value MUST be of type `Coordinate`. It specifies the axis around which `rotationStep` rotations are applied. The magnitude of `rotationStepAxis` MUST be ignored; only its direction is used. If not provided, the default axis is the $z$-axis, i.e., `[0, 0, 1]`. - `eulerStep` is OPTIONAL and its value MUST be an array of type `Euler`. `eulerStep` indicates the allowed Euler rotations. In the `Embedding`, the choice can be specified in `slotOrientationIndex` by the index of an element in `eulerStep`, where the index starts from zero. An empty `eulerStep` array indicates that smooth Euler rotation is allowed and, in the `Embedding`, the rotation MUST be specified in `rotation`. The default value for `SlotRotation` is `{eulerStep: [[0, 0, 0]]}`. ###### 26.05.06.03 The Input and Result of the Slot-placement The slot-placement takes an input `layout` from `Form` and produces a resulting `layout` in which each element, if it participates in the slot-placement, is placed in a slot. For artifact $i$, its original placement can be written as $(x_i', y_i', z_i')$ before performing the slot-placement, where $i$ indexes artifacts in the input `layout` that participate in the slot-placement. The resulting placement can be written as $(x_i, y_i, z_i)$ after performing the slot-placement. For artifact $i$, its original rotation can be written as the Euler angle $(\alpha_i', \beta_i', \gamma_i')$ before performing the slot-placement, where $i$ indexes artifacts in the input `layout` that participate in the slot-placement. The resulting rotation can be written as $(\alpha_i, \beta_i, \gamma_i)$ after performing the slot-placement. The input $(x_i', y_i', z_i')$ will not be used for slot-placement. $(x_i, y_i, z_i)$ is completely determined by the `SlotProfile`. ###### 26.05.06.04 Performing the Slot-placement In this section, we illustrate how to place an artifact at a slot. To place an artifact $i$, where $i$ indexes artifacts in the `layout`, is to derive its placement $(x_i, y_i, z_i)$ and its rotation in the scene. The process of placing at slots can be operated by the following steps. The placement $(x_i, y_i, z_i)$ of the artifact $i$ in the scene MUST be reproducible by these steps, regardless of the implementation. 1. **Order to place.** Process embeddings in the order they appear in the `layout`. Keep a set of “used slots.” 2. **Select the slot.** Using the `slotIndex` in the `Embedding`, find the matching `Slot` in `slotProfile`. - If no matching `Slot` exists, do not place $i$; continue with the next artifact from step 2. - If this `slotIndex` is already in the “used slots” set, do not place $i$; continue with the next artifact from step 2. - Otherwise, add this `slotIndex` to the “used slots” set. 3. **Derive the position.** Determine $(x_i, y_i, z_i)$ from the selected `Slot`. - If `position` is provided, set $(x_i, y_i, z_i)$ to `position`. - Otherwise, do not place $i$; continue with the next artifact from step 2. After iterating through the `layout`, each placed artifact $i$ has a determined placement $(x_i, y_i, z_i)$. It is RECOMMENDED not to define `slotProfile` entries whose slots lie outside the scene. The process of deriving the rotation of the placed artifact can be operated by the following steps. The rotation of the artifact $i$ in the scene MUST be reproducible by these steps, regardless of the implementation. 1. **Select the slot.** Using the `slotIndex` in the `Embedding`, find the matching `Slot` in `slotProfile`. - If no matching `Slot` exists, do not place $i$; continue with the next artifact from step 1. - Otherwise, proceed to step 2. 2. **No `slotRotation` specified.** If the `Slot` has no `slotRotation`, the rotation of the artifact is zero on all axes. 3. **`rotationStep` is a non-zero integer $N$.** Allowed rotations are around the axis of `rotationStepAxis` only, from the set $\{\tfrac{k\,360\degree}{N}\mid k\in\mathbb{Z}\}$; 1. If `slotOrientationIndex` is present and is an integer $k$, set the rotation around `rotationStepAxis` to $\tfrac{k\,360\degree}{N}$. 2. Else if `rotation` is present, round it to the nearest value in rotation around `rotationStepAxis` to $\tfrac{k\,360\degree}{N}$, where “nearest” is the shortest Euclidean distance after wrapping angles on the lattice with basis $\{360\degree\,\hat x,360\degree\,\hat y,360\degree\,\hat z\}$. If exactly between two options, select the one with larger $k$. 3. Else set the $z$ rotation to 0. 4. **`rotationStep` is zero.** A smooth rotation around `rotationStepAxis` is allowed. - If `rotation` is present, use it. - Otherwise set the rotation around `rotationStepAxis` to 0. 5. **`eulerStep` is a non-empty array.** Allowed rotations are the Euler triples listed in `eulerStep`. 1. If `slotOrientationIndex` is present and is an integer, select the Euler triple at that index; if the index exceeds the array length, select the first element (index 0). 2. Else if `rotation` is present, select the nearest Euler triple from `eulerStep`, where “nearest” is the shortest Euclidean distance after wrapping angles on the lattice with basis $\{360\degree\,\hat x,360\degree\,\hat y,360\degree\,\hat z\}$. If exactly between two options, select the one with the smaller array index. 3. Else select the first element (index 0) of `eulerStep`. 6. **`eulerStep` is an empty array.** A smooth Euler rotation is allowed. - If `rotation` is present, use it. - Otherwise the rotation is zero on each axis. ##### 26.05.07 Reconstruction Logic by Layout Mode For the layout modes defined in the Layout Mode module, as in [[26.05-Layout-Mode-Module]], a general reconstruction logic of the scene can be described by the following steps. Given an input `Form` object, perform the following steps on its `layout`. The resulting `layout` of each step is the input `layout` for the next step. 1. Read the layout mode and determine the reconstruction logic from the `Form` object. 2. If cell-placement is to be imposed, i.e., the layout mode is discrete, perform the cell-placement snapping, as specified in [[26.05.04-Cell-Placement]]. 3. If block-placement is to be imposed, i.e., the layout mode is block, perform the block-placement snapping, as specified in [[26.05.05-Block-Placement]]. 4. If slot-placement is to be imposed, i.e., the layout mode is slot, perform the slot placement, as specified in [[26.05.06-Slot-Placement]]. 5. If stacking logic is to be imposed, i.e., the layout mode is discrete or continuous, perform the stacking logic, as specified in [[26.05.03-Stacking-Logic]]. If flat layout mode is used, zero MUST be used for `spaceHeight` for this step. 6. If flat layout mode is used, set the $z$ coordinate of all artifacts to zero if `spaceHeight` is not provided, or set the $z$ coordinate of all artifacts to `spaceHeight` if `spaceHeight` is provided as a finite number. 7. If the Boundary module or the Tile module, or both, are in use, remove elements in `layout` that lie outside of the boundary, as specified in [[26.04-Boundary-Module-and-Tile-Module]]. The resulting `layout` is the output of the reconstruction logic. ###### 26.05.07.01 Flat Layout Mode Layout modes in two dimensions can be referred to as flat layout modes. They use only the ground plane in the scene, and artifacts' rotated volume in the $z$ direction is ignored, or equivalently, taken as zero. When working with the Local Scene module, if the `Form` object is not specified in a local scene, it uses the ground plane. #### 26.07 Storage Module The Storage module is used to indicate the storage for artifacts. The Storage module introduces a new type `Storage` defined as ```ts type Storage = Artifact[] ``` where all `Artifact` type objects in it MUST have an `id` member in their `metadata` and the `id` values MUST be unique. ```ts interface Metadata { id: string // REQUIRED if Storage module is in use // ... } ``` The `id` MUST be used to resolve the `Artifact` in `Form` to the `Artifact` in `Storage`, i.e., they are considered the same object. If two or more `Artifact` objects share the same `id`, the `Artifact` appearing first in the array MUST be considered the only `Artifact` with that `id` and the rest MUST be discarded. The Storage module also introduces new members in `FormProperties`, defined as ```ts interface FormProperties { storage: "path" | "impl" // OPTIONAL storagePath: string // OPTIONAL storageOverwrite: boolean // OPTIONAL storageEnforce: boolean // OPTIONAL // ... } ``` where - `storage` is OPTIONAL and its value MUST be one of those specified above. When it is provided, the Storage module is in use. When its value is `"impl"`, the implementation MUST specify the `Storage` and use it to resolve the scene with the `Form` object. - `storagePath` is OPTIONAL and its value MUST be of type `string` and MUST be a path or URL to a JSON file of the `Storage` data used for the `Form`. If it is not provided, the default value `"./storage.json"` MUST be used. Its value MUST be ignored if `storage` has a value other than `"path"`. - `storageOverwrite` is OPTIONAL and its value MUST be of type `boolean`. If it is not provided, the default value `true` MUST be used. Its value MUST be ignored if `storage` is not specified. When it is `true`, any conflict between an `Artifact` in `Form` and an `Artifact` in `Storage` MUST be resolved in favor of the `Artifact` in `Storage`; when it is `false`, the `Artifact` in `Form` MUST be merged into the corresponding `Artifact` in `Storage` member by member at every level, where each member present in `Form` overwrites the corresponding member in `Storage`, and the merged `Artifact` MUST be used, providing further customization of the scene in addition to the `Storage` data. - `storageEnforce` is OPTIONAL and its value MUST be of type `boolean`. If it is not provided, the default value `true` MUST be used. Its value MUST be ignored if `storage` is not specified. When it is `true`, any `Artifact` in `Form` that is not present in `Storage` MUST be discarded. `Storage` MUST contain the full information of artifacts. When a `storage` value is provided, any member whose value is of type `Artifact` MAY be a `string`. When it is a `string`, it MUST be the `id` of an `Artifact` in `Storage` and MUST be resolved accordingly. If the relevant artifact is missing from `Storage`, the relevant member MUST fall back to its default value; if no default value is specified, the member MUST be treated as not provided. In particular, when a `storage` value is provided, the `artifact` member of the `Embedding` object MAY be a `string` to reference the artifact in `Storage`. ```ts interface Embedding { artifact: Artifact | string // REQUIRED // ... } ``` where - The value of `artifact` MUST be either of type `Artifact` or a `string`. When it is a `string`, it MUST be the `id` of an `Artifact` in `Storage`. If `Storage` is not provided or the relevant `Artifact` is missing from `Storage`, an `Embedding` whose `artifact` is of type `string` MUST be discarded. An `Embedding` whose `artifact` is of type `string` MUST always be resolved in favor of the `Artifact` in `Storage`, regardless of the `storageOverwrite` value. ## 30 Extension Specification Extension Specifications define objects that represent users and their actions within the space, creating context for spaces and connections between users. ### 31 User and User Interface #todo A user is an being that must own or have access to an interface, and may have an inventory. Concretely, users include, but are not limited to, human beings, other intelligent beings, programs. #### Interface An interface is the input from a user to space and output to a user from space. The input from a user is a set of events that can trigger a set of corresponding functions known as interactions that changes the space. The output to a user is what user experienced from the space. ##### Camera Each user may be associated with a camera. The camera can be moved in response to interface interactions and serves as the user’s primary visual viewport. ##### External interface There are predefined sets of external interfaces commonly available on different platforms: - Desktop: - Mouse click (left or right) (at a place) - Mouse drag (along a path) - Keyboard input (with some characters) - Mobile: - Single tap and multi-tap (at places) - long tap (at a place) - Tap and drag (along a path) - On-screen keyboard input (with some characters) - System / Null users: - System interface: may monitor user-defined events occurring in the space or inventory as interfaces. - A null user is a system user that is implemented in a non-explicit way. ##### Avatar interface The avatar interface has two layers: the control layer and the avatar layer. The control layer is the external interface. When triggered, it calls an interaction function to control the avatar and perform a behavior. The avatar’s behavior then acts as an interface in the avatar layer. Common behaviors include: - Moving (towards a direction or along a path) - Standing (at a location) - Engaging (with an object, self, or another avatar, may with options) #### Inventory An inventory is a list of items associated with a user. It represents the set of artifacts currently held by the user. An inventory may include special slots that are monitored by system users. These are sometimes referred to as equipment slots or state slots. In implementation, inventory elements may correspond to items or tokens stored in a user's wallet, or to contextual contents such as a backpack. ##### Item Items are typically `Artifact` objects, but may be any object. They can also be monitored by system users. ### 32 Space #todo A space is the totality of what a user can experience. Concretely, a space can include the scene, its state, how it evolves and responds to user input, its recorded history, and any data stored within it along with how that data is presented. In this section we define a few potential constituents of a space besides the scene. The constituents defined here should not be considered the only possible parts of a space beyond the scene. #### State A state of the scene is #### UI Component #### Interaction #### Time #### History #### Background music and sounds effect