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
#
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:
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.
In preparation for future upgrades, the field in AudioSource is called audio_clip_url, but in the current protocol version it’s actually the manifest-defined path.
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.