Basic Components
The World Explorer supports a list of basic components that share their definition with scenes, providing built-in support for positioning, animation, media, world state queries
There are five types of components:
Object components add visual and physical properties to Entities.
Game components can request actions and receive information from the game engine.
Media components can display images and play sounds.
Area components alter the behavior of Entities in specific zones.
UI components allow scenes to render floating interfaces.
Except for Transform, which is specified in detail below, the state of all components is serialized using protocol buffers. You can follow the link in each title to see the complete definition.
Object Components
The most common components are those that attach visual and pyhisical properties to an Entity. They can be used to position, resize, paint and add collision to in-game objects.
Transform ↗ spec
Adds position, rotation and scale to an entity.
This component is, by a wide margin, the most commonly used and frequently updated during the lifespan of a scene. Because of this, Transform is not serialized using protocol buffers, and is instead packed into a custom structure.
Transform has a size of 44 bytes, with this exact layout:
.-----------------------.-------------------------------.-----------------------.-----------------.
| x | y | z | x | y | z | w | x | y | z | parent (uint32) |
'-----------------------'-------------------------------'-----------------------'-----------------'
╵ position (3x float) ╵ rotation (4x float) ╵ scale (3x float) ╵
This approach allows the runtime (especially in low-level code environments) to avoid intermediate serialization and deserialization steps. The memory where a Transform resides can be copied, shared and directly pointed to.
Coordinates can be fractionary, and thus use a 4-byte floating point number.
The parent field indicates that this Entity should be positioned relative to another one, identified by their ID.
Since the null-value for parent is also the RootEntity ID (0), any Transform is relative to it by default.
By protocol, Transform must be serialized in big-endian byte order.
MeshRenderer ↗ source
Provides basic rendering behavior for an Entity.
It can be set to render a plane, a sphere, a cube or cylinder. To render arbitrary 3D shapes, use GltfContainer.
MeshCollider ↗ source
Provides basic collision behavior and mouse pointer detection for an Entity.
It can be set to behave like a plane, a sphere, a cube or cylinder. To have a custom collision mesh, use GltfContainer.
Material ↗ source
Sets the texture, lighting, color and transparency properties of an Entity that also has the MeshRenderer component.
It's a complex structure designed to cover all common cases, but every field has a reasonable default value and can be left unspecified.
To completely customize the visual properties of an Entity, use GltfContainer.
GltfContainer ↗ source
Attaches a 3D model to this Entity, given the file path of a .gltf asset in the scene's manifest.
Since the model has its own meshes and materials, this component overrides any behavior from MeshRenderer, MeshCollider and Material.
Billboard ↗ source
Makes an Entity automatically reorient its Transform to face the camera. As the name indicates, it's used to display in-game billboards and frequently combined with TextShape.
It affects all directions by default, but can be set to only rotate in one axis.
Animator ↗ source
Defines one or more animations that can be applied simultaneously to an entity.
Scenes can set the component state to customize, play and transition between animations, as well as read it to check which animations are available or currently being played.
AvatarAttach ↗ source
Indicates that an Entity's position must follow a particular anchor point in an avatar's body.
It can affect any avatar, not only the player's, by setting a user ID.
TextShape ↗ source
Renders text on an Entity's position, given by its Transform.
It's highly configurable, supporting parameters like size, margin, padding, color, shadow and more.
Visibility ↗ source
Sets whether an Entity is visible (the default) or invisible.
Invisible objects still exist, and will exhibit behavior from any other attached components.
AvatarShape ↗ source
Contains information about the player's avatar, including their body shape, colors, wearables and transitory state.
This component is attached to entities in the avatar scene.
Game Components
Some basic components can be used by the scene and the runtime to exchange information. They leverage the ECS synchronization mechanism to guarantee consistency and ordering for any state changes or events.
CameraMode ↗ source
Can be used to determine whether the player has a first-person o third-person view.
PointerLock ↗ source
Can be used to determine whether the mouse pointer is automatically following the camera's point of focus (locked), or can move freely on the screen (unlocked).
It's attached to the CameraEntity, and its state can be read (but not written) from the scene.
PointerEvents ↗ source
Shows visual feedback when the pointer clicks or hovers over an Entity.
PointerEventsResult ↗ source
Contains information about recent input from the player, including keys and pointer actions.
It's attached to the RootEntity, and updated by the runtime with any new events on every frame.
Raycast ↗ source
Can be attached to an Entity to request a raycast from the game engine. The RaycastResult component will later be attached to the same entity.
The origin, direction and maximum length of the ray can be configured.
RaycastResult ↗ source
Attached by the runtime to Entities that have a Raycast component pending results.
It contains information about the original ray and identifies any Entities that were hit.
Media Components
Scenes can attach special components to display images, show video or play sounds.
AudioSource ↗ source
Plays an audio clip bundled with the scene, given the file's path in its manifest.
The sound originates from the associated entity's position. Its pitch, volume and looping behavior can be set, and the state of the audio player can be read.
AudioStream ↗ source
Similar to AudioSource, but the audio is streamed in real time from an external URL.
Despite being attached to a particular entity, the sound is not affected by its position. Its volume can be set, and the state of the audio player can be read.
NftShape ↗ source
Displays an NFT associated to an image or video asset.
It renders a 2D canvas with a configurable decorative frame.
Area Components
These components allow scenes to modify the default behavior of Entities within specified bounds.
AvatarModifierArea ↗ source
Changes the behavior of avatars within a space centered around an Entity.
It's defined with a 3D size vector, and can affect whether avatars are visible or clickable. Specific avatars can be excluded from this effect given their user's ID.
CameraModeArea ↗ source
Changes the camera mode (1st-person or 3rd-person) within a space centered around an Entity.
It's defined with a 3D size vector and a desired camera mode.
UI Components
The following components are used to create graphical interfaces that hover on top of the game world.
They are usually attached to sets of Entities that have hierarchical UiTransform components, related to one another via the parent attribute.
For example, a floating options window could be an Entity with a UiTransform and a UiBackground component, plus a Entity with a child UiTransform and a UiDropdown.
UiTransform ↗ source
Describes the size, positioning, margin and padding of a UI component.
It's based on the flexbox model and highly customizable.
UiBackground ↗ source
Describes a color or texture to use as background in a UI Entity.
UiDropdown ↗ source
Defines a list of mutually exclusive options to be displayed in a dropdown widget.
UiDropdownResult ↗ source
Contains the selected value from a UiDropdown, set by the runtime and read by the scene.
UiInput ↗ source
Defines a text input widget, with some margin for customization.
UiInputResult ↗ source
Contains the text value of a UiInput, set by the runtime and read by the scene.
UiText ↗ source
Defines a simple text view, with some margin for customization.
Last updated