Scripting

Scripting Your World

By Meta

Hands-On Challenge: Scripting Your World

TypeScript Conventions and Best Practices for Meta Worlds
API Reference
Meta Worlds Creator Manual GitHub⁠

Hands-On Challenge Overview

It’s time to bring your Worlds creations to life with scripted interactions! This challenge will guide you through creating an interactive balloon that pops when grabbed, plays effects, and then resets itself. You'll learn about event handling, controlling entity properties, playing audio/visual effects, and using timers. Some familiarity with TypeScript concepts will be helpful.
You’ll learn how to:
  • Set up entities in your scene (mesh, audio, particles).
  • Create a new Component script.
  • Define custom properties ("Props") for sound effects (SFX) and visual effects (VFX) that can be linked in the editor.
  • Use the "preStart()" method to initialize state and register event listeners (e.g., "onGrabStart").
  • Implement an event handler method to react to player interactions.
  • Modify entity properties like visibility and collidability.
  • Cast entity types (e.g., to "GrabbableEntity", "AudioGizmo", "ParticleGizmo").
  • Trigger audio and particle effects from your script.
  • Use "setTimeout" to create delayed actions for resetting the balloon.
  • Attach your Component to an entity and connect its properties in the editor.
Estimated Time: 1 hour

What You'll Need:

  • Access to the Meta Worlds Desktop Editor.
  • An existing world project or a new one to work in.
  • Basic familiarity with Worlds TypeScript and scripting APIs

Challenge Steps:

1. Set Up Your Scene with Assets
  • Open the Meta Worlds Desktop Editor and enter your world.
  • From the Asset Library, add the following to your scene:
    • A mesh entity for your balloon (e.g., a Sphere). Position it where you can easily interact with it.
    • An Audio Gizmo for the pop sound.
    • A Particle Gizmo for the confetti/pop effect.
  • You can place the gizmos near the balloon or at the world origin; their effect will be triggered by the script.
  • Select the balloon mesh and set its Motion to Interactive in its Properties panel.
2. Create Your "BalloonPop"
  • Open the Scripting panel.
  • Click to "Add new script" and name it "BalloonPop".
  • Open the script. It will have a basic structure.
3. Define Component Properties ("Props")
  • Inside your "BalloonPop" class, define properties for the sound and particle effects. These will allow you to link the gizmos from your scene in the editor.
  • It should look like this:
propDefinitions = {
  sfx: { type: hz.PropTypes.Entity },
  vfx: { type: hz.PropTypes.Entity },
}
4. Store Initial Position in "preStart()"
  • The "preStart()" method runs once before the component fully starts. We'll use it to store the balloon's initial position
  • Add the preStart() method.
  • Create a field variable to store the initial position. Name it initialPosition.
  • Store the initial position in preStart
  • It should look like this:
preStart() {	 
  this.initialPosition = this.entity.position.get();
}
5. Register Grab Event in "preStart()"
  • Now set up the grab listener. Add the event listener code to the preStart()
  • It should look like this:
this.connectCodeBlockEvent(this.entity, hz.CodeblockEvents.onGrabStart, this.handleBalloonGrab);
6. Implement the Pop and Reset Logic ("handleBalloonGrab()" method)
  • Create a new method in your class called "handleBalloonGrab". This method will contain the logic for what happens when the balloon is grabbed.
  • Try building it on your own by following the steps in the video.
  • Here’s what it might look like when you are done:
handleBalloonGrab(isRightHand: boolean, player: Player) {
  console.log("Balloon grabbed!");
  
  grabbable.as(hz.GrabbableEntity).forceRelease(player);
  this.entity.visible = false;
  this.entity.collidable = false;
  this.props.sfx.as(AudioGizmo)?.play();
  this.props.vfx.as(ParticleGizmo)?.play();
  
  this.async.setTimeout(() => {
    this.entity.visible = true;
    this.entity.collidable = true;
    this.entity.position.set(this.initialPosition);
    
    console.log("Balloon has been reset!");
  }, 3000);
}
7. Attach Component and Connect Properties in the Editor
  • Go back to your scene and select your balloon mesh entity.
  • In its Properties panel, find the "Attach Scripts" button and add your "BalloonPop".
  • You should now see "sfx" and "vfx" properties for your component.
  • Select your Audio Gizmo entity from the "sfx" property slot.
  • Select your Particle Gizmo entity from the "vfx" property slot.
8. Test Your Interactive Balloon
  • Enter Play mode for your world.
  • Approach the balloon and try to grab it.
  • It should:
    • Disappear.
    • Play the pop sound.
    • Show the confetti/pop particles.
    • Reappear at its original spot after 3 seconds (3000 milliseconds).
  • Open the Console to see your "console.log" messages.

Level Up:

  • Instead of resetting to the exact same spot, make it reappear in front of the player.
    You could try using code like this:
    player.position.get().add(player.position.forward.get())
  • Try attaching the script to more balloons or completely different objects like a cookie or a skeleton.

Need Help?