API

A ball in the world.

A brick in the world.

A cylinder in the world. Its symmetry axis is local Z.

A RigidGroup is a bunch of objects that move together. All Ball, Brick, and Cylinder child descendants of this are glued together and will move as one rigid body.

If you want to add animations, you must set followSkeletonId, use a SkAnimator to animate it, and add SkAttachment objects to glue objects to the SkJoints. There are some AI tools to automate this.

Use this as a Folder. There is no special behavior, it is simply for organization.

A mesh in the world.

To animate this mesh visually, you must set followSkeletonId and use a SkAnimator to animate it.

This is how you render text. All text must be attached to an object.

All measurements are in terms of world units, ie 1 block tall.

This lets you specify a center point that this object will rotate/scale relative to. The pivot moves, turns and scales with the object. Max one per object.

This only applies when using a PropertyAnimator on rotation, or one of the functions on objectService. It is ignored when manually setting rotation/size directly.

This smoothly changes a value on an object. Typically you should create this with an animationService.tweenTo().

This is equivalent to a PropertyAnimator with 2 keyframes. It is an easier, cheaper way to dynamically move a property if you don't know the values you want beforehand.

• All tween objects are automatically applied to their objects.
• tweenTo() creates a tween for you and deletes it once it finishes.
• They write the animated value into the real field every step.

This animates a Skeleton.

You can have many animators on the same skeleton. They will be blended in order of decreasing priority until each item's weight reaches a total of 100. See also: AnimationService.

Start and stop an animation with .play() and .pause() on this animator's clock, and fade it in and out with .smoothlyChangeWeight().

This is the root of a skeleton. Skeletons only apply to objects with the followSkeletonId field.

This should contain a child SkJoint for each joint in the skeleton. Hierarchies are allowed.

You can (1) animate it and (2) glue objects to it, using SkAnimation, SkAnimator, and SkAttachment.

This is how you define an animation.

It should contain a keyframe SkKeyframe child for each timestep in your animation.

Use this to glue an object in a RigidGroup to an SkJoint.

A child of Skeleton or SkJoint.

A child of SkAnimation.

For each desired joint in this keyframe, it should contain a SkKeyframePose child.

A child of SkKeyframe.

The pose of an individual joint.

Use this to smoothly animate one property on any object.

You can have multiple of these at once. They blend independently given a targetObjectId and property, so you can animate multiple fields at once.

• You can't use this to physically change subitems in a RigidGroup. Use a SkAnimator for that instead.
• If you're using this to create a moving platform, be sure it isn't pushable, or else it purposefully won't work - too confusing.
• It writes the animated value into the real field every step.

This defines the animation for a PropertyAnimator to play.

It should contain a keyframe PropertyKeyframe child for each timestep in your animation.

A child of PropertyAnimation.

A clock is a helper object that says how far along the animation is in a SkAnimator, PropertyAnimator, or SoundPlayer.

An image or "texture" that is shown on an object. Albedo is the main texture. The other fields are optional PBR properties.

You can never create or delete a Player object yourself. It is automatically created and deleted when a player joins and leaves. It is important for you to set the head and character, or the player won't be able to see or move.

Every Script is either a Server or Client script.

• Client scripts run on every client.
• Server scripts run on the server.
• Some APIs are only exposed to one or the other; read the docs.
• Deleting a Script stops it. Its listeners, timers, tick() loops and GUI stop, and its exports can no longer be called.

Import/Export:

• It is valid to write import { functionName } from './scriptName'. Hiererarchies of object names are valid.
• Script names, paths, & contents are only read once when the script is created.

Server/Client communication:

• Write 'use server' at the top of a Server script to make all exports importable by Client scripts.
• Write 'use client' at the top of a Client script to make all exports importable by Server scripts.
• The first parameter to all client functions must be the player's user id.
• Exports must be async functions.
• Exports must be validly callable by the other side.
• You should validate server function inputs and client function returns, as these are untrusted.

UI:

• We expose React-like syntax to draw UI on the screen. It is drawn by a real browser engine, so every Tailwind CSS v4 class works, including arbitrary values like w-[42%], and text defaults to black and 16px as on any web page.
• Use <div> for layout and text. Pointer input on a div reaches both the div (its hover styles, onClick and onHover) and the game.
• Use <button> with onClick for clickable UI. A button keeps the pointer to itself, so clicking it does not click the game. The innermost element with an onClick handles the click.
• You may only use <div>, <button>, text, arrays, null, className, onClick, and onHover primitive props.
• Style with className only. Do not use style props or unsupported HTML tags.
• Each shown GUI covers the whole screen, so w-full and h-full mean the whole screen. Place your content with Tailwind, like absolute top-4 left-4 for a corner, absolute bottom-6 left-1/2 -translate-x-1/2 for the bottom middle, or absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 for the center. Without that it sits in the top left corner. If you use screen-filling wrappers, you can use pointer-events-none to keep them from blocking other GUIs that mount, and pointer-events-auto on the content inside.
• Build a meter bar as a fixed-size track with a percent-width fill inside it, never as a row of recolored squares. Round the percent to a whole number so the class string does not change every frame.

const HealthMeter = ({ fraction }: { fraction: number }) => {  const percent = Math.round(Math.min(1, Math.max(0, fraction)) * 100)  return <div className="w-48 h-4 rounded-full bg-black/50 p-1 overflow-hidden">    <div className={`h-full rounded-full bg-emerald-400 w-[${percent}%]`} />  </div>}

• useState() works like usual.
• createState() works for state that comes from outside react, eg for 'use client' functions. This is similar to useSyncExternalStore.
• Write createState(initialValue). The .get() function automatically subscribes the relevant React components to re-render when .set() is called. .set() is intended to be defined inside a 'use client' function and called from the server.

Libraries:

• You can use setTimeout() and setInterval(). Scripts also expose console, URL, TextEncoder/TextDecoder, structuredClone, atob/btoa, Event/EventTarget, and AbortController.
• There is no fetch, no WebSocket, no storage, and no crypto (use Math.random()).

Managing Objects:

• Only the server can create and modify objects.
• All objects in the world are replicated to all users. You cannot create an object on just one client.

Controls the sun location and sky settings.

Use await stopScript() to stop all further execution of a script.

Use await tick() to await the next tick of the game loop. Always use this in places like infinite while loops, otherwise the script will stall and be killed.

To deal with players joining or leaving, use the object service.

• Join: game.objectService.addObjectCreatedListener((player) => { ... }, "player")
• Leave: game.objectService.addObjectDeletedListener((playerObjectId) => { ... }, "player").

This service exposes methods for reading and modifying objects.

All of the functions here are recursive: scale, rotate, move, setObjectWalkthrough, etc., meaning they apply to the object and all of its children.

If you only want to operate on one object and not its children, simply write object.propery = value, and don't use the functions here.

If you call these in a Client script the changes are only applied locally (not broadcast).

What castRay, castObjectShape, and getGroundSupport hit.

This service exposes methods for smoothly transitioning animation values.

This service exposes methods for controlling Clock objects on SkAnimator, PropertyAnimator, and SoundPlayer.

• collisionService fires even when isWalkthrough=true.
• For RigidGroups, collisionService fires using the subitem(s) involved in the collision.

Only callable by a Client Script.

A function that returns the changes you want to make to the character. This is called per physics step. You can't await here.

To time things across steps, add up dtSecs. getTime() is also accurate here.

Only callable by a Client Script.

The guiKey can be anything; it is a string you pick to identify the GUI root.

Only callable by a Client Script.

Only callable by a Client Script.

This is the equivalent to a React Node.

The typical usage is <MyComponent />.

You can also use strings, numbers, booleans, null, and undefined.

Common vector math functions for Vec3s. Every function returns a new vector.

Example usage: const velocity = vec3.scale(vec3.normalize(direction), speed).

The 'Assets' page contains a bunch of public objects anyone can use in their game. If you make an object, mesh, script, skybox, etc that other people might find useful to use in their game, we encourage you to upload it there. Assets can be deleted and changed at any time. If you update an asset, it won't update in games that have already downloaded it.

The 'Catalog' page is full of objects that people can buy and wear as hats. As a developer, you can think of it as the 'Assets' page, but with meshes only. Catalog items can't be deleted because people can buy them, but they can be made private.

The 'Data' page (hard to find, but you can get to it on some assets) is blob storage for sounds, textures, and meshes. Lots of places reference it, including most assets and catalog items. Data is immutable once created, but it can be deleted.

Every file can be at most 16 MiB.

• Mesh: a .glb with embedded textures, at most 8 MiB.
• Texture: a PNG, JPEG, or WebP image, at most 2048 pixels per side.
• Sound: Ogg Vorbis, MP3, WAV, or FLAC.
• Material: a color image, plus optional normal, roughness, and metalness images, each following the Texture rules and at most 64 MiB together.
• Skybox: a PNG, JPEG, or WebP panorama exactly twice as wide as it is tall, at most 4096 x 2048.
• Object: An object published from the world. Can't come from a file; use the chat to do this, it's a special tool.

Scripts usually deal with this object type.

It contains all the fields of either a Ball, Brick, Clock, Cylinder, Label, LocalGroup, SkJoint, SkAnimation, SkAnimator, SkAttachment, SkKeyframe, SkKeyframePose, Material, Mesh, Pivot, Player, PropertyAnimation, PropertyAnimator, PropertyKeyframe, RigidGroup, Script, Skeleton, SoundPlayer, Tween, or WorldLighting.

This object is a proxy, meaning every time you read a value from it, you get the current value in the world. You can also set fields on it, and they will affect the real object in the world. If the object is deleted, the id remains readable, but other fields will throw an error. Use getObjectById(), or a try/catch, if you think the object might be deleted.

And it contains the following additional fields:

If paused: animationTimeSecs is the duration into the animation to show.

If playing: localStartMs is the timestamp at which the animation started to play. The other field timeLocation says whether this timestamp is relative to the server's clock or the client's clock.

This only applies to Material objects whose albedoTextureDataId have transparency. Default is Opaque.

• Opaque means to render the underlying object as solid, meaning show the base color in the transparent areas.
• Mask makes the underlying object either opaque or invisible in areas, based on the transparency cutoff.
• Blend uses the texture alpha multiplied by the object opacity for smooth transparency.

This is a helper type. It contains all the fields of either a Ball, Brick, Clock, Cylinder, Group, SkJoint, SkAnimation, SkAnimator, SkAttachment, SkKeyframe, SkKeyframePose, Material, Mesh, Pivot, Player, PropertyAnimation, PropertyAnimator, PropertyKeyframe, RigidGroup, Script, Skeleton, SoundPlayer, Tween, or WorldLighting, plus a type field saying which one it is.

Every object in the world gets a unique id that you can use to reference it. It's just a number. These object ids may change between compile time and runtime. We automatically convert most object ids, but you should not hard-code object ids into scripts as we can't parse those until runtime.

"Data" generally means large assets that are uploaded and given an id, like mesh data and texture data. Objects reference them using their data id.

The unique id of the user. This will never change, so you should use it when tracking players. It is preferred over the player's username or the Player object's id.

This is called "location", but really means both position and rotation. In other words, the full information needed to place the object in 3D at snapshot in time. Can be global or local depending on context.

Speed information of an object. The derivative of Location3D.

A helper type.

RGB color.

A helper type.

A helper type.

A helper type.

A helper type.