| source |
|---|
Represents a virtual world in Meta Horizon Worlds, which provides access to properties, events, and operations related to the world state; including events scripts can use to time operations based on state changes to the world.
export declare class World Returns the current world ID.
Signature
id: ReadableHorizonProperty<bigint>;The leaderboards for the players in the world.
Signature
leaderboards: ILeaderboards;The matchmaking system for queueing players into the world.
Signature
matchmaking: {
allowPlayerJoin(allow: boolean): Promise<void>;
};Remarks
allowPlayerJoin - Indicates whether players can join the world.
The human-readable name of the world.
Signature
name: ReadableHorizonProperty<string>;An event that broadcasts on every rendered frame before the physics engine updates the world state. This event is especially useful for timing animations and entity locations before physics calculations are performed.
Signature
static readonly onPrePhysicsUpdate: LocalEvent<{
deltaTime: number;
}>;Remarks
The World.onPrePhysicsUpdate event provides similar functionality, but after the physics engine performs calculations.For more information about subscribing to world update events, see the World Update Events guide.
An event that broadcasts on every rendered frame in the world, allowing synchronization between the state of the world and the rendering pipeline. You can use this event to time animations, physics, and entity transforms for optimal performance.
Signature
static readonly onUpdate: LocalEvent<{
deltaTime: number;
}>;Remarks
By subscribing to this event, a script can perform operations during the world update loop, such as spawning an asset.The World.onPrePhysicsUpdate event provides similar functionality, but before the physics engine performs calculations.For more information about subscribing to world update events, see the World Update Events guide.
A persistent storage object, which contains a set of functions that interact with player variables.For information about using player variables, see the Persistent Variables guide.
Signature
persistentStorage: IPersistentStorage;A persistent storage object, which contains a set of functions that interact with player variables.
Signature
persistentStorageWorld: IPersistentStorageWorld;Returns the current snapshot ID.
Signature
snapshotId: ReadableHorizonProperty<bigint>;Basic functions for teams based gameplay.
Signature
team: ITeam;Remarks
In horizon, every world comes with a team management logic. Players, at any moment during their session, can join, leave or change teams at will. But a player can only be in one team of a given team group.Team groups are ways to separate teams in different sets. This allows the creation of multiple gameplay bubbles with their own teams in one single world.
Basic UI functions for displaying popups and tooltips.
Signature
ui: IUI;Remarks
For an example, see the Lobby tutorial.
Removes a previously spawned asset from the world.
Signature
deleteAsset(entity: Entity, fullDelete?: boolean): Promise<undefined>;Parameters
entity: Entity
The previously spawned entity.
fullDelete: boolean
(Optional) if true, the entity must be the root object, thus deleting all sub-objects.
Returns
Promise<undefined>
A promise that resolves when the entity has been deleted.
Finds entities by their names.
Signature
findEntities(name: string, options?: FindEntitiesOptions): Entity[];Parameters
name: string
The name of the entities to find, case sensitive. Must not be empty. If empty, will log an error.
options: FindEntitiesOptions
(Optional) Options for the World.findEntities() method. rootEntity - Will only search for entities that are descendents of the given root entitymatchOperation - The match operation to run when searching for entities with given string
rootEntity defaults to undefined, which means the entire hierarchy will be searched
matchOperation defaults to EntityNameMatchOperation.Exact. Options are EntityNameMatchOperation.Exact, EntityNameMatchOperation.StartsWith, EntityNameMatchOperation.EndsWith, EntityNameMatchOperation.Contains, and EntityNameMatchOperation.Regex
Returns
Entity[]
An array of all of the entities matching the string and operation. If no entities are found, the array will be empty.
Examples
const floorTiles = this.world.findEntities('floor'); // returns all entities with the name 'floor'.
const trees = this.world.findEntities('tree', {rootEntity: groundEntity}); // returns all entities with the name tree that are descendants of the entity 'groundEntity'
const enemies = this.world.findEntities('enemy', {matchOperation: EntityNameMatchOperation.StartsWith}); // returns all entities whose name's start with 'enemy'
const cubes = this.world.findEntities('Cube', {matchOperation: EntityNameMatchOperation.EndsWith}); // returns all entities whose name's ends with 'Cube'
const walls = this.world.findEntities('Wall', {matchOperation: EntityNameMatchOperation.Contains}); // returns all entities whose name's contain the string 'Wall'
const apples = this.world.findEntities("^a...e$", {matchOperation: hz.EntityNameMatchOperation.Regex}); // returns all entities whose name matches the regex, in this case meaning it starts with a lower case a, ends with an e, and is five characters long
const applesFromTree = this.world.findEntities("^a...e$", {rootEntity, treeEntity, matchOperation: hz.EntityNameMatchOperation.Regex}); // returns all entities matching the regex that descend from treeEntity
const expectEmpty = this.world.findEntities(''); // name must not be empty. Logs an error and returns an empty arrayRemarks
For performance reasons do not do this in the update loop. Best used in start and cache the result.
Finds an entity by its name.
Signature
findEntity(name: string): Entity | undefined;Parameters
name: string
The name of the entity to find, case sensitive. Must not be empty
Returns
Entity | undefined
The entity with the specified name, or undefined if no such entity exists.
Examples
const floor = this.world.findEntity('floor'); // returns the entity with the name floor.
const expectUndefined = this.world.findEntity('oneOfMany'); // if multiple entites with same name exists, this logs an error to console and returns undefined
const expectUndefiend = this.world.findEntity(''); // name must not be empty. Logs an error and returns undefinedRemarks
For performance reasons do not do this in the update loop. Best used in start and cache the result. If there are multiple entities with the same name, will log an error and return undefined.
Gets all world entities containing the provided tags using the provided match operation.
Signature
getEntitiesWithTags(tags: string[], matchOperation?: EntityTagMatchOperation): Entity[];Parameters
tags: string[]
An array of tag names to match against. The comparison is case sensitive.
matchOperation: EntityTagMatchOperation
(Optional) The match operation to run when searching for entities with given tags. Defaults to EntityTagMatchOperation.HasAnyExact.
Returns
Entity[]
An array of all of the entities matching the tags and operation.
Examples
entityA.tags.set(['tag1', 'tag2', 'tag3']);
entityB.tags.set(['tag2', 'tag3', 'tag4']);
entitiesWithAnytags = this.world.getEntitiesWithTags(['tag1', 'tag2'], EntityTagMatchOperation.MatchAny); // returns entityA & entityB
entitiesWithAlltags = this.world.getEntitiesWithTags(['tag3', 'tag4'], EntityTagMatchOperation.MatchAll); // returns entityBRemarks
This is an expensive operation and should be used carefully.
Gets the player corresponding to the local Meta Horizon Worlds client running on the player's machine where this script is currently executing.
Signature
getLocalPlayer(): Player;Returns
The local player.
Remarks
This is particularly useful for Local Scripting to figure out which player's machine a local script is executing on. Note that if the local script is executing on the server, this will return the server player.
Gets the Player object for the given player index.
Signature
getPlayerFromIndex(playerIndex: number): Player | null;Parameters
playerIndex: number
The index of the player. Retrievable with the Player.index property.
Returns
Player | null
The player corresponding to that index, or null if no player exists at the index.
Gets all players currently in the world, not including the server player.
Signature
getPlayers(): Player[];Returns
Player[]
An array of Player objects in the world.
Gets the player corresponding to the server's Meta Horizon Worlds client.
Signature
getServerPlayer(): Player;Returns
The server player.
Remarks
This is particularly useful for Local Scripting to figure out if a script is executing on some client other than the server. Note that a server player is not physically present in the world and does not support a number of standard features (such as name.get() or being moved) that normal players do.
Resets the world's state. This sets all entities back to their initial position, cancels all event and event listeners, and restarts scripts in the world.
Signature
reset(): void;Returns
void
Changes the visible state of a shop configured as an overlay element
Signature
setShopOverlayVisible(player: Player, shopGizmo: Entity, visible: boolean): Promise<void>;Parameters
player: Player
the player who will be seeing the shop overlay change state
shopGizmo: Entity
the entity Gizmo of the shop
visible: boolean
the new state to set to the shop
Returns
Promise<void>
Asynchronously spawns an asset.
Signature
spawnAsset(asset: Asset, position: Vec3, rotation?: Quaternion, scale?: Vec3): Promise<Entity[]>;Parameters
asset: Asset
The asset to spawn.
position: Vec3
The position where the asset is spawned.
rotation: Quaternion
(Optional) The rotation of the spawned asset. If invalid, is replace with Quaternion.one (no rotation).
scale: Vec3
(Optional) The scale of the spawned asset.
Returns
Promise<Entity[]>
A promise resolving to all of the root entities within the asset.
Creates a string representation of the World object.
Signature
toString(): string;Returns
string
A string representation of the World object.
Called on every frame.
Signature
update(updateType: WorldUpdateType, deltaTime: number): undefined;Parameters
updateType: WorldUpdateType
The type of update.
deltaTime: number
The duration, in seconds, since the last frame.
Returns
undefined