I. Getting Started & Setup

• Q: How do I install/use TypeScript for Horizon Worlds?
  • A: You can use the web editor at horizon.meta.com/creator/ or the desktop editor by installing the Meta Link desktop app.
• Q: What should be in my .gitignore file?
  • A: .editor, .vscode, types, package.json, and tsconfig.json.
• Q: Is there a Mac version of the Desktop Editor?
  • A: No, you can use the web editor or a VM running Windows.
• Q: How do I find specific API details?
  • A: Use the search bar at https://horizon.meta.com/resources/scripting-api/ or use F12 to jump to the d.ts definition in VSCode.
• Q: How do I fix errors about a missing TS component?
  • A: Ensure your component declaration is generic like this: class MyComponent extends Component<typeof MyComponent> { ... }.

II. Core Concepts & Syntax

• Q: What's the difference between Number and number?

  • A: number is the primitive data type, Number is an object wrapper. Avoid capitalized versions of Number, String, and Boolean, etc.

• Q: What is deltaTime?

  • A: It's the time, in seconds, since the previous onUpdate cycle, useful for smooth motion.

• Q: What does thing.method.bind(thing) do?

  • A: It ensures the this keyword refers to the correct object within the function. It can also be used for partially applying arguments.

• Q: When do I need to use func.bind(this)?

  • A: Whenever you pass a function as an event handler, you need to bind it to keep the correct context. Or use the arrow function () => this.myfunction() which will do this binding for you.

• Q: When are local and network events fired?

  • A: Local events run immediately. Network events run "as soon as it can, but not immediately". CodeblockEvents run next cycle.

• Q: What are the valid types for function parameters for local and network events?

  • A: For Local and Network events you should use an object, as they all use json compatible format, ex. new LocalEvent<{myValue: number}>

• Q: What is a "Local execution" vs "Default execution"?

  • A: Default means that the scripts runs on the server. Local means the script runs on the client that owns the entity. You must assign an owner to a local script for it to run locally. A default script cannot do that.

• Q: What's the difference between using this.variable.set versus this.variable = ? *

  • A: set sends information to other headsets for that variable, while assignment will only modify the value locally. Properties and variables in Horizon Worlds require using set and get to properly sync the value.

• Q: What are EventSubscriptions?

  • A: They are returned by all connect*() calls and are used to disconnect.

• Q: Why am I getting a "Cannot read properties of undefined" error when using the as() method?

  • A: Use the methods correctly. Example: this.props.myTrigger.as(hz.TriggerGizmo).<my stuff> . Also, use the proper "type".

• Q: Why doesn't clearTimeout() or setTimeout work?

  • A: Use this.async.clearTimeout() and this.async.setTimeout() instead of global versions in horizon.

• Q: Why doesn't my codeblock event send a message to my Typescript component?

  • A: The type definition of the codeblock event must match the TS definition. A code block event with type string is not compatible with a TS event that expects an object such as { newStatus: string }.

• Q: What is the correct way to define a local event with a string as an argument?

  • A: You cannot, local events take an object as argument. This is why they are structured as such LocalEvent<{ newStatus: string }>

• Q: Are mobile inputs limited to using a GUI or can TS do swipes via touch position/delta?

  • A: You can use focused interaction mode to get touch and drag information on mobile, and multitouch will be available soon.

• Q: Can you get device rotation?

  • A: No API for it yet.

• Q: Is there an index of all the TypeScript API?

  • A: https://horizon.meta.com/resources/scripting-api/ and the d.ts files. VSCode has pop-up documentation when hovering over APIs.

• Q: Is there anything similar to setVisibilityForPlayers() but for collidability?

  • A: No, you cannot set collision per player with current APIs/tools

• Q: How can I force a player to exit a seat gizmo?

  • A: Not possible yet with current API.

• Q: Is there a TS equivalent to codeblock server player?

  • A: Use this.world.getServerPlayer() inside a component.

• Q: How do I rotate a UI element?

  • A: Use UI/.../TransformStyle, no clear doc on it.

• Q: How to use NetworkEvent parameters?

  • A: Use an object rather than an array. this.sendNetworkBroadcastEvent(gameEnd, {spawnLobby:this.props.spawnLobby})

• Q: Can I use the thumbstick on mobile?

  • A: No, you need to use focused interaction mode and calculate touch values.

• Q: How do I use Object PPVs and PPV groups?

  • A: Use colons :. e.g. TSPPVs:playerInfo not dots TSPPVs.playerInfo

• Q: What is the difference between AudioGizmo vs Sound Recorder Gizmo?

  • A: A SoundRecorderGizmo is a subclass of AudioGizmo, there doesn't appear to be a specific TS API for it.

• Q: How do I make an object rotate smoothly over time?

  • A: Must calculate the correct rotation and duration over time and update every frame.

• Q: If local scripts can't access PPVs, then how would I display a player's PPV data on their screen overlay UI using a script with execution to local?

  • A: You can have per-player bindings, or send a message from the local script to a default script to get info that can send to the local script for processing. Also locally scripted custom UI is visible only to the owner of the entity.

• Q: How can I get the camera to zoom or move in focused interaction mode?

  • A: Must use it in conjunction with the attach camera api you have to change the position and rotation offsets of the camera. Use a proxy object that acts like a dolly or an offset.

• Q: When an item is grabbed I am setting a camera view, but it says the typescript is missing.

  • A: Need to make the script local, and import the necessary module, as well as use the method as(), not the keyword as. this.props.raycastEntity.as(hz.RaycastGizmo);

• Q: How do I get a player's Persistent variables?

  • A: Use this.world.persistentStorage.getPlayerVariable(player, "group:variable")

• Q: In Type Script, what is an EventSubscription?

  • A: It is what all the connect*() calls return, which you can use to disconnect.

• Q: How to create a rotate by over time TS Utility reference

  • A: Needs to use the past and quaterion as an offset to compute destination. Rotate To takes in the final rotation, where as rotate By takes in the offset.

• Q: How can I get touch swipes in a custom UI on mobile?

  • A: You have to use the focused interaction mode on the custom UI element.

• Q: I am getting this error : Error: Exception encountered running bridge method 'SetLeaderboardScore': SetLeaderboardScore argument at position 1 was the server player, which is not supported in this method.

  • A: Use this.world.getLocalPlayer() to get the player that is running a specific local script. Make sure the script is local as well. Also setScoreForPlayer must get a player from the game not serverplayer.

• Q: What is the purpose of this.entity.owner.set(...)?

  • A: It transfers the ownership of the current entity from the server or any other player, to the specific client mentioned. This means that when a local script is attached to the entity it will now run in the client headset, as opposed to the server.

• Q: How can I create an object, and then set it's position and then add a collision box?

  • A: you must declare an entity with motion type animated to move it via the position.set(). Also collision won't be detected if you move the object with transform functions and not by using physics.

• Q: How can I make a button that stays put?

  • A: Set the object PhysicalEntity.locked property to true.

• Q: How can I do multiple actions based on a single trigger?

  • A: You can use the action as a callback to other functions.

• Q: What is the best approach to setting up buttons?

  • A: Make one custom component with all required properties and link the props to multiple components.

• Q: When should I use a LocalEvent and when should I use a NetworkEvent?

  • A: Use LocalEvent when communicating scripts in the same object and NetworkEvent for all communication across different devices.

• Q: I get Error Executing Script Module: Failed to load module 'redacted' being imported by 'HorizonRuntime'.

  • A: The editor may be set to an incorrect API version. Or you're not doing class MyComponent extends Component<typeof MyComponent>

• Q: Can I access the camera position in focus mode?

  • A: You can use the localCamera to get the camera position and rotation.

• Q: Is there a way to change the camera zoom in a UI with the mouse?

• A: You have to use the attachCamera to add a reference to camera then you can adjust its position.

• Q: What's the right way to use this.async.setTimeout

  • A: Always make sure you save the variable into a different variable then you can clear the timer after or before the timeout. Always create a timer using this.async.setTimeout(() => { /* timer function code here*/}, time), and clear it using this.async.clearTimeout(timerId) using the variable returned on setTimout.

• Q: If a player leaves a world what happens to their local scripts?

  • A: You are not guaranteed to get an opportunity to run code in the local scripts when the player exits. Also the ownership will revert back to the server player.

• Q: Is there a way to prevent the player from looking into areas that are outside of the room?

  • A: You can add a trigger that pushes the player back into the room, if it is not an avatar specific feature. Or can add a double wall to prevent it, or block the avatar as a physics object with no gravitiy.

• Q: What does object.bind(obj) do?

  • A: It creates a new function that uses the given object as the this parameter.

• Q: How do I make a button that is a part of a canvas, and can also be clicked? * A: It must be an interactive object to be clickable.

• Q: How can I get an animation from code to play only on the left hand?

  • A: The left hand currently can't be animated.

• Q: I cannot get my code to run for my game controller

  • A: Make sure your local script is running with a proper owner other wise it's running on the server player, which is not allowed. Also make sure you have selected the correct trigger/object for the code to run on.

• Q: I need to have a codeblock that will send data to a Typescript object. What are my options?

  • A: You can create a CodeBlockEvent in TS, and use the proper syntax as specified in the API.

• Q: I need to have a "sleep" command that can be cancelled in Typescript, How can I do that?

  • A: Instead of relying on setTimeOut, you need to capture a timerId and use that value to clearTimeOut, also the "sleep" function will still call other code inside the function after a time out if not designed to stop with a cancel parameter.

• Q: Why does my code work in the desktop editor but when I use it in published it's doing something different

  • A: Make sure your code is set to local or has the proper owner, also some of the functions on desktop, do not fully simulate what it does on headset. You should develop and test in the published world as much as possible.

• Q: How do I implement an animation loop and transition between animations?

  • A: Create all animations in editor, then setup a system with a onUpdate event and set transition time to a value depending on what you need. You can use an enum for which state to use in your animation.

• Q: Is there a way to set the intensity of VFX via TS script?

  • A: Not currently possible via API, they have pre-programmed intensity.

• Q: Why doesn't my OnPlayerCollision fire after a teleport?

  • A: You may be teleporting the player out of the trigger as soon as it collides with the trigger. You should try adding a slight delay to fix this. Collision events also fire multiple times. You may have to debounce or rate limit collision events by using a boolean or timer to limit it to one event fire.

• Q: Why does my object sometimes not detect the onCollision event

  • A: You must assign a physics material to the object. A collider must be a physics collider, and not an animated object.

• Q: How can I detect a hit with an animated object with raycasting?

  • A: Use a collider inside the animated object to detect collisions with a raycast.

• Q: Why does my onPlayerEnterWorld event not trigger when I press play in Desktop Editor?

  • A: This event should only fire on join and not when in play mode.

• Q: How to import a JSON to read my game parameters?

  • A: Import it as a TextAsset and the use JSON.parse to read it.

• Q: What do I do when a script wont let me set props?

  • A: Make sure you have the correct component declaration, such as <typeof MyComponent> which will help you create the correct props.

• Q: How do I make something a "draggable" object?

  • A: Make the object "interactive" which is under its motion.

• Q: How do I send a Network event, or a Local event to different clients?

  • A: You need to create it with the correct types. You can not send an array, but you can an Object or SerializableState. You also have to check for correct syntax and types for network messages (both sender and receiver) or it won't get through correctly.

• Q: How to create custom "lookAt" function?

  • A: The correct way is to use Quaternion.lookRotation and pass it target.sub(objectPosition)

• Q: I need to send a float variable to another script.

  • A: Use new LocalEvent<{ value: number }>

• Q: How do I move an object with a script over time without physics?

  • A: Use the onUpdate event to move it every frame.

• Q: Can I get device rotation with Typescript? * A: No APIs available for mobile device rotation.

• Q: How can I control the camera using typescript

  • A: The API for cameras are only available on the local clients.

• Q: Is it possible to force an avatar to always have an aim animation when using a pistol?

  • A: This is not possible, as there are limited animation available.

• Q: How can I move a camera forward in focused mode?

  • A: Use the "attach camera api" with a new variable representing the position of the camera

• Q: What does it mean when a TS error says that it's not assignable to type 'SerializableState'?

  • A: You are trying to send data with Network Events that is not a standard JSON type. Check if your parameters are inside an object {param1: "hello", param2: 1} and not ["hello", 1], for array parameters, send one array with all the parameters inside or create a property that defines an object with the key that matches the one in your reciever.

• Q: Why are all my Typescript Properties not showing up?

  • A: you must use correct syntax static propsDefinition = { myProp : { type: PropTypes.Number } } and you can not do any code logic within this object definition.

• Q: Why are my Objects with scripts that use Properties of type "number", "string" or "boolean" showing up as errors?

  • A: You must set the correct syntax. static propsDefinition = { myString : { type: PropTypes.String }}, and use lowercase types of String, Number and Boolean, and not the capitalized versions.

• Q: How to implement per player UI binding? * A: Use binding which allows you to set different values for a single property.

• Q: How do you get code completion with TypeScript? * A: You have to have VS code open to edit the code, and be using the TS desktop editor or VS code. You do not get it from Microsoft Visual Studio.

• Q: Can I disable system controls and take complete control of user input?

  • A: You can use new PlayerInput methods. PlayerInput.disableSystemControls() PlayerInput.enableSystemControls(), PlayerInput.triggerInputActionDown(), PlayerInput.triggerInputActionUp().

• Q: I'm having a hard time with collision. What should I do?

  • A: Try to use colliders that have the same shape and size as the asset.

• Q: How can I rotate an object around another object, and still rotate that object in space?

  • A: Use Quaternion.mulVec3(myRotation, Vec3.forward) in combination with setting position offset.

• Q: What's the difference between this.entity.position and this.entity.transform.position.get()?

  • A: They return the same value. entity.position is shorter to write. You would use transform for local position or other local based properties.

• Q: How do I make a button that stays put and does not get moved by grab interactions?

  • A: Set the object's PhysicalEntity.locked property to true. You may also want to force release on grab and return to original position, as the lock may not work perfectly.

• Q: If a local script uses this.world.getLocalPlayer() how do you set the owner of the object to the current player?

  • A: By transferring the ownership, you can access that value using the this.world.getLocalPlayer(). If it's set to the serverplayer that means the ownership did not move to the client running the local script.

• Q: How to dynamically apply a texture to a 3d object using Typescript?

  • A: Use setTexture() on an entity with MeshEntity, where you can change the texture. Make sure you use UIO material and not _BR materials.

• Q: Does setCameraModeAttach() need to be a local script?

  • A: Yes, all camera methods can only be called on the local client.

• Q: What does "disposableObject" mean in local events?

  • A: It is a design flaw in the v1 api that they fixed in v2.

• Q: How do I make an object visible to only one player?

  • A: You can do so by setting the ownership of the local script on the object to that player. Alternatively you can use entity.setVisibilityForPlayers([player], PlayerVisibilityMode.VisibleTo).

• Q: What are the different ways to move an object in Type Script?

  • A: Use physics.push or physics.setVelocity() if using physics, if not then you can change entity.position.set() for non-physics objects.

• Q: How can I make a UI Element appear in front of the player and then move the camera to look at it?

  • A: You can move a proxy object and set the camera offset from that object.

• Q: How to make a menu or list that is scrollable?

  • A: The default UI system does not support scrollable lists, you need to build a custom UI and code in that feature.

• Q: How to correctly use .then with a spawnAsset method?

  • A: spawnAsset always returns a promise array of entites, even if it only returns one.

• Q: Does a this.world.spawnAsset().then() callback execute the second it spawns?

  • A: No. You have to use await or then to get the values after they are spawned. The .then only triggers when the spawn operation has completed, and passes in the spawned asset for further manipulation.

• Q: Is there a ClearTimeout method for a sleep function

  • A: no you have to capture the timeID and clear it separately.

• Q: How do I apply a physics material to the player to simulate ice physics?

  • A: You cannot apply physics to a player directly, you must instead change the player locomotion to feel like they are skating with physics forces.

• Q: How to set up a codeblock event and listen to it from TS?

  • A: In TS define the CodeBlockEvent as: static MyCodeBlockEvent = new CodeBlockEvent<[paramType]>('MyCodeBlockEvent', [PropType.String]) In CB make a "Send event to entity block" and send it to your component. Then listen to it using this.connectCodeBlockEvent(this.entity, MyCodeBlockEvent, (param) => { console.log("received")});

• Q: How can I avoid duplicated collision events on object?

  • A: Add a bool value that defaults to false, then on a collision event set the value to true, then set a timer that will set the value back to false after a certain time. This way your code will only execute once for every new collision.

• Q: Is it possible to use an arrow function as a type declaration in a LocalEvent?

  • A: No. They are not assignable to a LocalEventData type.

• Q: How to convert a local script to a default script?

  • A: You cannot do that, you must create a new script in default mode, and copy your previous local script code.

• Q: What is the "server player" for a local script?

  • A: Is a placeholder that runs all the default scripts, and if a local script is not assigned to a proper user, then the scripts run on this fake player.

• Q: How can I access other entity properties in TS?

  • A: You can get them via this.entity.properties by calling the property, the property must be declared first in propsDefinition as a type PropTypes.Entity to access these objects. Or use the method as() as such this.props.myObject.as(MyObjectType). You cannot get component from a different entity by name.

• Q: Is there a way to create a custom "lookAt" rotation method for my avatar?

  • A: No. You need a combination of Quaternion.lookRotation with a Vec3 to get that rotation, and setAvatarGripPoseOverride to set the animation.

• Q: If I use a method with async, does it also need to have async on the event connection?

  • A: No it does not.

• Q: I want to display a value that might be null/undefined. What do I do?

  • A: Use the ? conditional call, so the code is only executed when it is valid/defined. Such as: this.props.testValue?.toString();

• Q: I am having a issue with setting properties with a custom type in TypeScript.

  • A: You are setting the variable rather than using the setter and getter of the Properties API. You must set it as such this.myVariable.set(newValue).

• Q: Why are my Textures not showing correctly?

  • A: Make sure your texture material has the correct suffix (e.g., _UIO for custom UI)

• Q: Is there a way to get a random number in TS?

  • A: Use Math.random()

• Q: Why do I get errors from PlayerInput in TS code?

  • A: Ensure you have created a DisposableObject variable first, and have included it in the definition as per the documentation.

• Q: What should the preStart() and start() methods do?

  • A: preStart() is called before the world loads. start() is called after a world loads.

• Q: How to get my custom object and reference properties of its components in other scripts using typescript?

  • A: You have to get the objects with this.world.getEntitiesWithTags() and then access the data via type casting myobject.as(MyCustomObject).myProperty.get()

• Q: How do I set the value of properties from the UI?

  • A: Using the static properties definitions on a component static propsDefinition = { myBool : { type: PropTypes.Boolean, default: false } }

• Q: How do I change the color of a Trimesh object with code?

  • A: You must create a material with the UIO suffix and apply that material to the object to be able to change its color.

• Q: How can I use setAvatarGripPoseOverride for the left hand?

  • A: You can't, the left hand is only for visual representation.

• Q: What's the correct way to make an object follow me using Typescript?

  • A: Use this.world.getLocalPlayer() and set the objects position with this.entity.position.set() in a onUpdate function.

• Q: Is there a way to make an object follow you and still move using Physics?

  • A: Use entity.velocity.set() in combination with entity.forcePush().

• Q: I have a small script I'm attaching directly to an AudioGizmo and it works, but If I try the same thing with a Sound Recorder Gizmo I would imagine it would work; but it does not. Why?

  • A: The SoundRecorderGizmo is a subclass of AudioGizmo and not different, might be a bug and you should create a ticket.

• Q: Is it possible to have a codeblock to make an object follow you? * A: It is possible, and you can do so with an update method that changes the position of that object to the position of the player. You need to get the player position first using world.getLocalPlayer() and setting the world position of the object each frame.

• Q: What is a 'gyroscope based looking around system'?

  • A: Using your device orientation to navigate the camera. There is no API for this, file a feature request for phone orientation input.

• Q: How do I use NetworkEvent with an Entity parameter? * A: You have to include the type in an object: sendNetworkBroadcastEvent(gameEnd, {spawnLobby: this.props.spawnLobby});

• Q: I want to create a timer and cancel it on multiple occasions.

  • A: Create a promise and resolve it in the setTimeOut or cancel using clearTimeout. Return a promise object with the value on callback, and a cancel function.

• Q: Is there a feature request channel?

  • A: Use #🆘┃private-bug-reporting channel to request features.

• Q: What does this.entity.as(hz.TextGizmo) do?

  • A: It will cast/convert the entity to the TextGizmo so you can use the text property, must use it if you are trying to access other gizmos and cast them using .as(). You can chain them for complex objects, like .as(Physics).as(Collider).

• Q: If local scripts can't access PPVs. Then how would I display a player's ppv data on their screen overlay UI using a script with execution to local?

  • A: You can have per-player bindings, or send a message from the local script to a default script to get info that can send to the local script for processing. Also locally scripted custom UI is visible only to the owner of the entity.

• Q: How do I check collisions on animated objects

  • A: You must define a collision box for your objects, you can’t rely on an animation to trigger collisions

• Q: What does “OnPlayerCollision” do and when is it called?

  • A: It's used to check when two collision objects touch each other, you need to set which type of objects it will track in the object parameters. This also sends several callbacks in the same frame when colliding.

• Q: What is the type returned from the raycast?

  • A: It is a union type, you must check for the hitResult.targetType to see what object the raycast hit before you access the properties of it using casting.

• Q: How do you find out where a script execution is running in Typescript?

  • A: Compare this.world.getLocalPlayer() with this.world.getServerPlayer(). If the Local Player equals the ServerPlayer, then it is running on server side, otherwise it's running on client side.

• Q: Does anyone know how to make the NPC work from the asset library.

  • A: Look at the documentation for AvatarAIAgent at https://developers.meta.com/horizon-worlds/learn/documentation/desktop-editor/npcs/scripted-avatar-npcs/getting-started-with-scripted-avatar-npcs