Docs

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.

A picture in the world. It follows an object and orients itself exactly like a Label.

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 object id (player.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. Every Tailwind CSS v4 class works, including arbitrary values like w-[42%], and text defaults to black and 16px as on any web page.
• You may only use <div>, <button>, text, arrays, null, className, onClick, onRightClick, onMouseDown, onMouseUp, and onHover primitive props.
• Use <div> for layout and text. Pointer input on a div reaches both the div (its hover styles and onHover) and the game, unless the div has onClick, onRightClick, onMouseDown or onMouseUp.
• Use <button> with onClick for clickable UI. A button, or a div with any of those four handlers, keeps presses to itself, so pressing it does not press the game. The innermost element with an onClick handles the click.
• onClick is only for the left button. onRightClick fires when the right button goes down and comes back up on the element. onMouseDown and onMouseUp get "left" or "right". onMouseUp fires on the element the button is let go over, even if it went down somewhere else. Each one goes to the innermost element that has it.
• 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 right-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 dynamic tailwind classes to whole numbers, because new class strings rebuild the stylesheet.

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-sm bg-black/50 p-1 overflow-hidden">    <div className={`h-full rounded-sm 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.
• Update UI that moves (meters, timers, charge bars) frequently, and use transition-[width] duration-[Nms] ease-linear with N about the time between updates (below we use 17ms or 1 tick), so the bar slides between values.

const now = createState(getTime())const runClock = async () => {  while (true) {    await tick()    now.set(getTime())  }}runClock()const ChargeMeter = ({ chargeStartTime }: { chargeStartTime: number }) => {  const percent = Math.round(Math.min(1, (now.get() - chargeStartTime) / 2000) * 100)  return <div className="w-48 h-4 bg-black/50 overflow-hidden">    <div className={`h-full bg-emerald-400 transition-[width] duration-[17ms] ease-linear w-[${percent}%]`} />  </div>}

• Avoid updating UI from setInterval; it makes bars jump.
• Do not put UI in the upper left portion of the screen; that is reserved for chat.

Libraries:

• You can use setTimeout() and setInterval(). Note that timers wait for the next tick to run, so they essentially only run on multiples of 16.6ms. Eg setTimeout(fn, 30) runs after ~33ms.
• You can use 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. The game ticks 60 times a second on both the server and clients. 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.
• It never fires between two objects that both have isWalkthrough=true.
• For RigidGroups, collisionService fires using the subitem(s) involved in the collision.

If you want to detect collisions accurately, use this service on the client, and call a 'use server' function that confirms the hit. On the server, collision detection of characters can be inaccurate.

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.

To upload an asset, ask the chat, or manually drag and drop a file into the editor.

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. A catalog item's creator can delete it on the website, and everyone who bought it loses it. It can also be unlisted: it leaves the Catalog page and can't be bought, but anyone with its id can still use it.

All catalog items (hats) have constraints and will be rejected if they do not follow them:

• Hats should be placed in coordinates as if the origin were the top center of the character's head.
• Assume a 1x1x1 head.
• Dimensions: The widest side must be MIN_HAT_WIDEST_SIDE=0.5 to MAX_HAT_WIDEST_SIDE=2.0 units. The bounding box's center must be within MAX_HAT_CENTER_OFFSET=0.25 units within X Y Z of the origin. The bounding box must fit within MIN_HAT_BOTTOM=-0.6 to MAX_HAT_BOTTOM=0.1 units up/down from the origin.

To make a new catalog item, the chat must first create an asset, and then convert that asset to a catalog item.

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. Assets can have at most 20,000 triangles and 60,000 vertices, and catalog items can have at most 10,000 triangles and 30,000 vertices.
• Texture: a PNG, JPEG, or WebP image, at most 2048 pixels per side.
• Sound: Ogg Vorbis, MP3, WAV, or FLAC. A sound under 10 seconds becomes an Sfx asset, and a longer one a Sound asset.
• 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.

Tile size is in world units, and tile offset is fractions of a tile. The origin for the tiling is the -Z top pole.

Tile size is in world units, and tile offset is fractions of a tile. The origin for the tiling is the +Z end of the -X side, and the top left corner of the square around each cap.

Tile size is in world units, and tile offset is fractions of a tile. The origin for the tiling is the top left corner (the top face's -X -Z corner and the bottom face's -X +Z corner).

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 user-id of the user's account. For example, kube.new/profile/[user-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.