Introduction#

What is a script?#

A script in Jamango! is a piece of code that runs in the game world, allowing you to define behaviors, interactions, and game mechanics. Scripts are written in TypeScript and can use the Jamango API to interact with the game world.

Entry Point Scripts#

Jamango uses two entry point scripts to organize your code:

• client.ts - Code that runs only on the client (players' devices). Use for UI updates, input handling, and client-specific visual effects.
• server.ts - Code that runs only on the dedicated server. Use for game logic, world state management, and authoritative operations like chat messages.

Both files can import other TypeScript files in your project using relative imports. Only these entry points are executed automatically - other files must be imported to run.

Importing the API#

In order to use the Jamango API, start by importing the functions. There are two possible ways for you to do this:

Import every function and use them via J:

tsCopy
import * as J from "jamango";

Import specific functions and use them directly:

tsCopy
import { onGameStart, spawnProp } from "jamango";

Core Concepts#

Positions and velocities are typically expressed as arrays of numbers. A x=1, y=5, z=3 vector can simply be expressed as [1, 5, 3]. The vec3 library contains functions that operate on vectors:

tsCopy
import * as J from "jamango";

// Create vectors A and B
const a = [10, 5, 3];
const b = [2, 0, -1];

// Get the distance between the points A and B
const distance = J.vec3.distance(a, b);

Get the asset ID of anything you've built in the world editor by using the assets object:

tsCopy
const coinAsset = J.assets.props.Coin.id

Spawn instances of entities by using your asset ID. The spawn functions will return an entity ID:

tsCopy
const coin = J.spawnProp(coinAsset)

With the entity ID of your coin, you can now make it go flying!

tsCopy
J.setEntityVelocity(coin, [0, 10, 0])

Using Jamango! with AI Code Assistants#

If you want to code Jamango! in your own local IDE, or use AI code-assist tools such as Cursor or Windsurf, you can sync your world's scripts to a folder on your computer straight from the browser editor — no extra tooling to install.

Step 1: Open the script editor in your Jamango! world#

Load your world in creator mode and press J to open the script editor.

Step 2: Click "Connect folder"#

In the editor's top bar, click Connect folder. Choose an initial sync direction (Browser → Folder to copy your current scripts out to an empty folder), then pick a local folder and grant read/write access when your browser asks.

Step 3: Edit locally with your IDE and AI tools#

Your local folder is now the source of truth, and the browser editor becomes read-only — edit the files in your IDE and changes sync back to the game automatically. The editor writes everything an AI assistant needs into the folder alongside your scripts: the jamango API types under node_modules/, this README, and rules files (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .windsurfrules), so Cursor, Windsurf, Claude, and friends have the full API context out of the box.

AI Code Generation First Steps#

If you are using Cursor or Windsurf, here is an example prompt to test the AI's capability with Jamango!

AI Prompt Example: Dice spawning server script#

Please write the following test script:

• Using the Jamango API - please spawn a prop with the id: prop#6CA2D1B994904AFBB3699EB2AA67D62B every 1 second in a different location in the sky (Y: 40) near spawn (0,0,0).
• When the player interacts with this prop, please add upward velocity (and some forward velocity facing away from the player) to the prop like the player is tossing the dice in the air.
• Please also give the dice some angular velocity to make the effect interesting when the player 'tosses' the dice.
• Please limit this to 30 dice in the scene total.
• Please send a chat message on every successful dice toss.
• Please review the Jamango API to consider the most appropriate implementation.

Cursor/Windsurf will automatically write code for you to review and accept or reject.

Schema System (J.schema)#

Jamango's schema system provides a type-safe way to define and validate data structures. It's particularly useful for defining traits, network messages, and configuration objects.

Basic Types#

1. Primitives#

tsCopy
// Boolean
J.schema.boolean({
  defaultValue: true,
  label: "Is Active",
  description: "Whether the feature is enabled"
});

// Number with range and step
J.schema.number({
  defaultValue: 10,
Show all 25 lines

2. Vectors and Matrices#

tsCopy
// 2D position
J.schema.vec2({
  defaultValue: [0, 0],
  control: "position"
});

// 3D rotation
J.schema.vec3({
  defaultValue: [0, 1, 0],
  control: "direction"
Show all 28 lines

Complex Types#

3. Objects and Collections#

tsCopy
// Object with nested properties
J.schema.object({
  position: J.schema.vec3(),
  rotation: J.schema.quat(),
  scale: J.schema.number({ defaultValue: 1 })
});

// List of items
J.schema.list(
  J.schema.string(),
Show all 19 lines

4. Union Types#

tsCopy
// Discriminated union
J.schema.union("type", [
  J.schema.object({
    type: J.schema.literal("weapon"),
    damage: J.schema.number()
  }),
  J.schema.object({
    type: J.schema.literal("potion"),
    healAmount: J.schema.number()
  })
Show all 11 lines

Real-world Examples#

Player Trait#

tsCopy
const PlayerTrait = J.defineTrait("Player", J.schema.object({
  health: J.schema.number({ 
    min: 0, 
    max: 100, 
    defaultValue: 100 
  }),
  level: J.schema.number({ 
    min: 1, 
    defaultValue: 1 
  }),
Show all 15 lines

Moving Platform Trait#

tsCopy
const MovingPlatformTrait = J.defineTrait("MovingPlatform", J.schema.object({
  speed: J.schema.vec3({ 
    label: "Movement Speed",
    defaultValue: [1, 0, 0] 
  }),
  range: J.schema.vec3({ 
    label: "Movement Range",
    defaultValue: [5, 0, 0] 
  }),
  pauseDuration: J.schema.number({ 
Show all 15 lines

Asset-based Trait Example#

• You can use "prop" | "avatar" | "block" | "audio" | "particleSystem" | "environmentPreset" | "animation" values when identifying the asset type for the asset function parameter.

tsCopy
// Define a trait for a prop that can change its appearance
const PropTrait = J.defineTrait(
    "Prop",
    J.schema.object({
        // Required asset reference (e.g., "prop:wooden_crate")
        assetId: J.schema.asset({
            label: "3D Model",
            description: "The 3D model to use for this prop",
            assetTypes: ["prop"], // Restrict to prop assets
            defaultValue: "prop:wooden_crate", // Default prop
Show all 69 lines

Common Schema Options#

All schema types support these common options:

• label?: string - Display name for the field
• description?: string - Description of the field
• optional?: boolean - Makes the field optional
• nullable?: boolean - Allows null values
• hidden?: boolean - Hides the field from UI

We will release more guides in the near future on best approaches and warnings on how best to use AI code assist in Jamango!

Tutorial - Your First Collection Mechanic#

We're going to build a simple script that spawns 10 dice at random positions that can be picked up.

Before we get going there are only two pre-requisite steps to complete this tutorial:

1. Create a new World. Let's use the "Flat" world to start.
2. Good news: every world comes with a built-in "Dice" prop, so you don't need to create one! Just make sure you have it.

If there's no dice in your world, you can create your own prop and just replace the name in the code with your own prop name later. To create a prop simply make a selection with the pencil, right-click and choose "Create Prop".

Part 1 – Spawning Dice#

You can now press H and open the script editor. All of the code you add today will be written in server.ts just for the purposes of this tutorial. However it is possible to write code in client.ts or make your own scripts. You just need to make sure to properly import these scripts in both execution scripts.

server.ts

tsCopy
// import all of the Jamango! API, which will below be accessible with the "J" variable.
import * as J from "jamango";

// create a "on game start" hook
J.onGameStart(() => {
  // store the id of the Dice prop (built-in to every world)
  const propAsset = J.assets.props["Dice"].id;

  // i is the current iteration, 10 is the amount of dice to spawn
  for (let i = 0; i < 10; i++) {
Show all 19 lines

Part 2: Making Dice Collectable#

Now that dice are randomly spawning in the world, let's make them collectable. You can define Traits to attach logic to entities, or simply to identify them. We can pick any name - let's define a Player trait for players, and a Collectable trait for our dice.

We can then use these traits to create a collision listener that activates when a Player touches the Collectable.

tsCopy
import * as J from "jamango";

// define a "player" and a "collectable" trait
const PlayerTrait = J.defineTrait("Player");
const CollectableTrait = J.defineTrait("Collectable");

// when players join the game, give them the "player" trait
J.onPlayerJoin((playerId) => {
  J.setTrait(playerId, PlayerTrait);
});
Show all 41 lines

Part 3: Tracking Collection Count#

Traits are very useful for many game mechanics - this is because they can also contain data.

We can use the Player trait to store a "dice" value, and increment it every time we pick up a die. Let's update the trait definition for players with this new information:

tsCopy
const PlayerTrait = J.defineTrait("Player", J.schema.object({ dice: J.schema.number() }));

Now, when a player joins - we can set their initial dice value. We're going to set it to zero for now. Let's update the code:

tsCopy
// when players join the game, give them the "player" trait
J.onPlayerJoin((playerId) => {
  J.setTrait(playerId, PlayerTrait, { dice: 0 });
});

Next, let's increase the player's dice counter when dice are collected. To do this, we get the trait data from the player, and increase the value. We can do this right inside the collision listener:

tsCopy
J.onEntityCollisionStart(
  {
    source: [CollectableTrait],
    target: [PlayerTrait],
  },
  (sourceId, targetId) => {
    // remove the die
    J.removeEntity(sourceId);

    // increase the players trait value
Show all 21 lines

Part 4: Final Complete Script#

Now you've put it all together – great job! There's lots more you can do now – whether you want to add a sound effect when you pick up a coin, or update the behaviour of the dice to make them float up and down, or make them rotate - the world is your oyster with Traits and the Jamango! API.

Here's a final version of the script:

tsCopy
import * as J from "jamango";

// define a "player" and a "collectable" trait
const PlayerTrait = J.defineTrait("Player", J.schema.object({ dice: J.schema.number() }));
const CollectableTrait = J.defineTrait("Collectable");

// when players join the game, give them the "player" trait with dice counter
J.onPlayerJoin((playerId) => {
  J.setTrait(playerId, PlayerTrait, { dice: 0 });
});
Show all 49 lines

Part 5: Querying All Players#

Another useful function is getAllWithTraits. For example - when the game ends, we could easily get all players, and send a chat message with their dice count:

tsCopy
const players = J.getAllWithTraits([PlayerTrait]);
for (const [id, player] of players) {
  const name = J.getPlayerUsername(id);
  J.sendChatMessage(`${name} has ${player.dice} dice!`);
}

Attaching Traits to Entities with the Wrench#

In this tutorial you learned how to programmatically spawn entities and attach traits to them. However, you can also attach traits to props or characters that you have placed in edit mode using the wrench.

In order to see your traits when using the wrench, you should add some display metadata to the trait definition. We can also change our trait to contain some data, such as a "value" that could control how much score it gives a player.

tsCopy
const CollectableTrait = J.defineTrait(
  "Collectable",
  J.schema.object({ value: J.schema.number({ label: "Value" }) }),
  {
    name: "Collectable",
    description: "Makes an entity collectable",
    color: "#ffe100",
    icon: "🎲",
  },
);

To now add this trait onto something in-world:

1. Press E and drag a "Dice" prop into your action bar.
2. Select the Dice and place it in the world by left clicking.
3. Activate the wrench and press "Inspect" on the prop.
4. Find the "Collectable" trait you defined and click on it
5. Fill out the form generated from your schema to set the value.

We hope this helps you understand traits! Here are some more examples for simple game mechanics:

Examples / Snippets#

Bouncy Entity Collision#

Here's how you could make a player fly upwards after colliding with any prop or area that has the "Bouncy" trait.

tsCopy
const BouncyTrait = J.defineTrait("Bouncy");
const PlayerTrait = J.defineTrait("Player");

J.onPlayerJoin((playerId) => {
  J.setTrait(playerId, PlayerTrait);
});

J.onEntityCollisionStart(
  {
    source: [BouncyTrait],
Show all 16 lines

Bouncy Block Type Collision#

tsCopy
const BouncyTrait = J.defineTrait("bouncy");
const PlayerTrait = J.defineTrait("player");

J.onPlayerJoin((playerId) => {
    J.setTrait(playerId, PlayerTrait);
});

J.onGameStart(() => {
    J.setTrait(J.assets.blocks["My Bouncy Block Type"].id, BouncyTrait);
});
Show all 20 lines

Obby Checkpoints and Hazards#

This is a script allowing you to store player progression in an obby - and reset the player if they collide with a hazard!

tsCopy
import * as J from "jamango";

// define a trait to store checkpoints for players
const PlayerCheckpointTrait = J.defineTrait("playerCheckpoint", J.schema.object({
    spawn: J.schema.vec3(),
    checkpoint: J.schema.number(),
}));

// define a trait for checkpoint areas. the trait value is the checkpoint level, so that
// walking over previous checkpoints does nothing.
Show all 56 lines

Respawning Trapdoor Block#

Blocks can contain traits as well - let any "TrapBlock" disappear after a player collision, and respawn after some time!

tsCopy
const PlayerTrait = J.defineTrait("Player");
const TrapdoorBlockTrait = J.defineTrait("TrapBlock");

J.onPlayerJoin((playerId) => {
  J.setTrait(playerId, PlayerTrait);
});

J.onGameStart(() => {
  J.setTrait(J.assets.blocks.Trapdoor.id, TrapdoorBlockTrait);
});
Show all 33 lines

Moving Platform (all directions)#

tsCopy
import * as J from "jamango";

const MovingPlatform = J.defineTrait("MovingPlatform", J.schema.object({
  speed: J.schema.vec3(),
  range: J.schema.vec3(),
  goBack: J.schema.boolean(),
  pauseDuration: J.schema.number(),
  permanentRemove: J.schema.boolean({ optional: true }),
}));
Show all 145 lines

Swimming (Global Water Level)#

tsCopy
const PlayerTrait = J.defineTrait("PlayerTrait");

J.onPlayerJoin((playerId) => {
  J.setTrait(playerId, PlayerTrait);
});

const WATER_LEVEL = -1;

J.onGameTick(() => {
  for (const [playerId] of J.getAllWithTraits([PlayerTrait])) {
Show all 16 lines

Balloons Tower Defence Balloon Movement Script#

tsCopy
import * as J from "jamango";

export const PATH: J.Vec3[] = [
  [-45, 8, -264],
  [-52, 8, -264],
  [-51, 8, -272],
  [-47, 8, -272],
  [-47, 8, -283],
];
Show all 152 lines

Best Practices#

Code Execution#

Jamango code runs in both edit mode and play mode. In edit mode, J.on* hooks are not called, but code is still executed so that traits defined with J.defineTrait are understood by the editor.

To ensure your code runs correctly, follow these guidelines:

• Put all gameplay logic inside hooks (e.g., J.onGameStart)
• Never store data on globals e.g. globalThis, document
• Always use J.uiElement for custom UI, this is reset properly when changing between edit and play mode
• Don't use setTimeout/setInterval, prefer checking J.getWorldTime() in J.onGameTick instead
• Constants and variables in module scope are ok!

tsCopy
// ❌ BAD - using setInterval, can't be properly cleaned up
const SPAWN_INTERVAL_MS = 1000;

setInterval(() => {
  J.spawnProp(J.assets.props["Dice"].id);
  // ...
}, SPAWN_INTERVAL_MS);

tsCopy
// ✅ GOOD - runs only in play mode
const SPAWN_INTERVAL = 1; // seconds

let lastSpawnTime = 0;

J.onGameTick((_, time) => {
  if (time - lastSpawnTime > SPAWN_INTERVAL) {
    J.spawnProp(J.assets.props["Dice"].id);
    // ...
Show all 13 lines

API Reference#

J.net.isServer: boolean#

Shared modules can inspect whether they are running in the dedicated server or browser client bundle:

tsCopy
if (J.net.isServer) {
  // Server-only behavior
} else {
  // Client-only behavior
}

Networking Commands#

J.net.defineCommand<TData>(name: string) => Command<TData>#

• Environment: both

Defines a custom network command for sending data between clients and server. Returns a command object that can be used with send, sendToAll, and listen.

tsCopy
// Define a command with TypeScript data
const MyCommand = J.net.defineCommand<{ value: number; message: string }>("myCommand");

J.net.send<TCommand>(command: TCommand, data: TCommand["_data"], target?: EntityId | EntityId[]) => void#

• Environment: both

Sends a command to specific targets (clients or server). If no target is specified, sends to the server.

tsCopy
// Send to server from client
J.net.send(MyCommand, { value: 10, message: "Hello" });

// Send to specific player from server
J.net.send(MyCommand, { value: 20, message: "Response" }, playerId);

// Send to multiple players
J.net.send(MyCommand, { value: 30, message: "Broadcast" }, [playerId1, playerId2]);

J.net.sendToAll<TCommand>(command: TCommand, data: TCommand["_data"], except?: EntityId) => void#

• Environment: both

Sends a command to all clients except optionally one (usually the sender).

tsCopy
// Send to all clients
J.net.sendToAll(MyCommand, { value: 100, message: "Everyone" });

// Send to all except one player
J.net.sendToAll(MyCommand, { value: 200, message: "Others" }, excludedPlayerId);

J.net.listen<TCommand>(command: TCommand, handler: (data: TCommand["_data"], playerId?: EntityId) => void) => () => void#

• Environment: both

Listens for a command and returns an unsubscribe function. The handler receives the data and optionally the sender's player ID.

tsCopy
// Listen for a command
const unsubscribe = J.net.listen(MyCommand, (data, playerId) => {
  console.log("Received command:", data);
  if (playerId) {
    console.log("From player:", playerId);
  }
});

// Stop listening when done
unsubscribe();

Scene Tree#

J.sceneTree: Record<string, SceneTreeNode>#

• Environment: both

Access to scene tree nodes defined in the world editor. Each node contains position, rotation, scale, and type information.

tsCopy
// Access a scene tree node by name
const node = J.sceneTree["MySpawnPoint"];
if (node) {
  console.log("Node position:", node.position);
  console.log("Node type:", node.type); // SCENE_NODE_TYPE_PROP, SCENE_NODE_TYPE_CHARACTER, or SCENE_NODE_TYPE_AREA
}

J.getSceneTreeNodeEntity(sceneTreeNodeId: string) => EntityId | undefined#

• Environment: both

Gets the entity ID for a scene tree node. Returns undefined if the node doesn't exist or hasn't spawned an entity.

tsCopy
// Get the entity for a scene tree node
const entityId = J.getSceneTreeNodeEntity("MySpawnPoint");
if (entityId) {
  // Use the entity ID
  J.setEntityPosition(entityId, [0, 10, 0]);
}

getWorldTime() => number#

• Environment: both

Returns the current world time in seconds since the game started.

getWorldBounds() => WorldBounds#

• Environment: both

Returns the world bounds that define the playable area. The bounds are an axis-aligned bounding box (AABB) in world coordinates.

isInWorldBounds(pos: Vec3) => boolean#

• Environment: both

Checks if a position is within the world bounds. Returns true if the position is inside the playable area, false otherwise.

tsCopy
J.onGameTick((dt, t) => {
    // get the global world respawn position
    const spawn = J.getWorldSpawn();
    const entities = J.getAllCharacters();
    for (const id of entities) {
        // set any character back to spawn in case they fall out of bounds
        if (!J.isInWorldBounds(J.getEntityPosition(id))) {
            J.setEntityPosition(id, spawn.position, true);
        }
    }
Show all 11 lines

getWorldSpawn() => WorldSpawn#

• Environment: both

Returns the world's spawn point configuration, including the spawn position and rotation angle.

CharacterItem type#

tsCopy
type CharacterItem = {
  asset: string;
  transform: {
		position: Vec3;
		quaternion: Quat;
		scale: number;
	};
	animations: ItemAnimations;
}

ItemAnimations enum#

tsCopy
enum ItemAnimations {
	ONE_HANDED_TOOL,
	ONE_HANDED_MELEE,
	ONE_HANDED_RANGED_WEAPON,
	TWO_HANDED_RANGED_WEAPON
}

getCharacterItem(id: EntityId) => CharacterItem | undefined#

Gets the item equipped by a character entity.

setCharacterItem(id: EntityId, item: CharacterItem | undefined) => void#

Sets the item equipped by a character entity. Pass undefined to unequip the item.

tsCopy
J.onPlayerJoin((playerId) => {
  const swordItem: J.CharacterItem = {
    asset: "prop#7E8C391CCEB04E30BECDC9DBFAC5B5B1", //your prop id goes here
    transform: {
      position: [0, 0, 0],
      quaternion: [0, 0, 0, 1],
      scale: 1,
    },
    animations: J.ItemAnimations.ONE_HANDED_MELEE
  };
Show all 12 lines

setFirstPersonItemTransform(position: Vec3, quaternion: Quat, scale: number, lerpSpeed?: number) => void#

• Environment: client

This is used to set the transform of the first-person item (the item that appears in front of the camera when in first-person view). You can use this to create custom first-person item animations, like drawing back a bow, swinging a sword, reloading a gun, etc.

While a transform is set, you are in complete control of the first-person item position, rotation, and scale. The builtin item bobbing effects will be disabled.

clearFirstPersonItemTransform() => void#

• Environment: client

Resets the first-person item transform, and resumes the builtin item bobbing effects.

setWorldSettings(settings: Partial<WorldSettings>) => void#

• Environment: client and server

Sets world settings such as chat enabled/disabled, others in future.

tsCopy
J.onGameStart(() => {
  J.setWorldSettings({ chatEnabled: false });
});

getWorldSettings() => WorldSettings#

• Environment: client and server

Returns whether the chat is enabled in the world.

setUISettings(options: Partial<UISettings>) => void#

• Environment: client

Sets the UI settings for the client. You can pass a partial object to only update specific options.

tsCopy
// hide all builtin UI elements
J.setUISettings({
    mobileRightButtons: false,
    mobileInteractButton: false,
    mobileEmoteButton: false,
});

getUISettings() => UISettings#

• Environment: client

Returns the current UI settings for the client.

getRenderSettings() => RenderSettings#

• Environment: client

Returns the local player's current render settings:

tsCopy
type RenderSettings = {
  renderDistance: number;
  entityRenderDistance: number;
  pixelRatio: number;
  fxaa: boolean;
  shadows: boolean;
  simpleWater: boolean;
};

These settings are local to each player. Use J.net if the server needs a client to report its settings.

setRenderSettings(settings: Partial<RenderSettings>) => void#

• Environment: client

Overrides the local player's render settings for the current game session. Only the supplied fields are changed, and the player's saved settings are not modified.

tsCopy
const settings = J.getRenderSettings();

if (!settings.shadows) {
  J.setRenderSettings({
    simpleWater: true,
  });
}

setCrosshair(visible?: boolean, spread?: number) => void#

• Environment: client Controls the crosshair display and spread offset. This function only works on the client side.

• visible - Controls whether the crosshair is visible or hidden. Default is true (visible).

• spread - Controls the crosshair spread (how far apart the crosshair lines are). Default is 0 (no spread).

tsCopy
// Hide the crosshair
J.setCrosshair(false);

// Show crosshair with some spread
J.setCrosshair(true, 0.2);

setBlockSelector(visible?: boolean) => void#

• Environment: client

Controls the block selector display. The block selector is the box that highlights which block you are aiming at. This function only works on the client side.

• visible - Controls whether the block selector is visible or hidden. Default is true (visible).

Ribbons#

Ribbons are client-only visual geometry for paths, directional markers, and rings. A ribbon is not an entity: it has no position, traits, physics, scene-tree node, or networking. Its numeric RibbonId is only valid with the ribbon functions below. Every client that should display a ribbon must create it from client.ts.

Ribbons render procedural stripes without textures. Pattern spacing follows world distance along the ribbon, including around bends. The RibbonStyle values:

• backgroundColor / stripeColor - RGBA values from 0 to 1.
• stripeAngle - normalized from 0 to 1.
  • 0: flat, perpendicular stripes.
  • 0.5: approximately 45° stripes, or a 90° tip with stripeArrow: true.
  • 1: maximally angled, internally capped before becoming infinite.
• stripeWidth - normalized from 0 to 1.
  • 0.1: stripe occupies 10% of each repetition.
  • 1: stripe color completely covers the background.
• stripeArrow - false: straight angled stripes. true: mirrors the stripe angle across the ribbon center, producing chevrons/arrows.
• stripeSpacing - repeat distance in world units.
• scrollSpeed - world units per second along the point order; 0 is stationary, negative values reverse. Scrolling runs entirely in the fragment shader.
• occludedOpacity - multiplies both alpha values when the ribbon is behind opaque geometry; use 0 to hide occluded parts.

tsCopy
// Flat warning stripes: | | | |
stripeAngle: 0,
stripeArrow: false,

// Diagonal warning stripes: / / / /
stripeAngle: 0.5,
stripeArrow: false,

// Arrow pattern: > > > >
stripeAngle: 0.5,
Show all 11 lines

createRibbon(sectionCapacity: number, geometry: RibbonGeometry, style: RibbonStyle) => RibbonId#

• Environment: client

Creates a visible ribbon. sectionCapacity reserves the maximum number of path points or explicit sections that later geometry updates may use, up to 512 per ribbon. At most 64 ribbons and 4096 reserved sections can exist at the same time.

The high-level path geometry expands center points into a fixed-width band using the required normal. Rebuild and set the geometry each frame to keep a ribbon attached to a moving entity:

tsCopy
let playerPathRibbon: J.RibbonId;

function getPlayerPathGeometry(): J.RibbonGeometry {
  const playerId = J.getLocalPlayer();
  const position = J.getEntityInterpolatedPosition(playerId)!;

  return {
    kind: "path",
    points: [position, RECTANGLE_CENTER],
    thickness: 1,
Show all 57 lines

The low-level sections geometry accepts exact left and right world-space vertices. Use it for ribbons conforming to uneven surfaces or changing width:

tsCopy
const exactRibbon = J.createRibbon(
  3,
  {
    kind: "sections",
    sections: [
      { left: [-1, 0.02, 0], right: [1, 0.02, 0] },
      { left: [-1, 0.2, 2], right: [1, 0.2, 2] },
      { left: [0, 0.02, 4], right: [2, 0.02, 4] },
    ],
    closed: false,
Show all 22 lines

Set closed: true to connect the last section back to the first. Closed ribbons require at least three sections.

setRibbonGeometry(ribbonId: RibbonId, geometry: RibbonGeometry) => void#

• Environment: client

Replaces the ribbon's world-space geometry. The new geometry must fit its creation-time sectionCapacity. Updating points is how a ribbon follows an entity; entity transform functions do not apply to ribbons.

setRibbonStyle(ribbonId: RibbonId, style: RibbonStyle) => void#

• Environment: client

Replaces all stripe pattern, color, scrolling, and occlusion values. Style changes update shader data without changing ribbon positions.

setRibbonVisible(ribbonId: RibbonId, visible: boolean) => void#

• Environment: client

Shows or hides a ribbon without releasing its reserved geometry.

removeRibbon(ribbonId: RibbonId) => void#

• Environment: client

Removes the ribbon and releases its renderer allocation. Ribbon IDs become invalid after removal and all ribbons are removed when client game code reloads.

getCamera() => { position: Vec3; quaternion: Quat; fov: number; aspect: number; distance: number; }#

• Environment: client

Returns the current camera position, quaternion, vertical field of view in degrees, aspect ratio (width / height of the render viewport), and distance — how far behind the character the camera is set to sit, in world units, where 0 means first person. distance is the configured value, not the shortened one the camera falls back to when a wall is in the way.

setCameraFree(position: Vec3, rotation: Quat) => void#

• Environment: client

Sets the camera to a free-floating position with custom rotation, detached from the local player. This allows you to create cinematic camera movements, security cameras, or other custom camera behaviors.

• position - The 3D world position where the camera should be placed
• rotation - The quaternion rotation for the camera orientation

tsCopy
// Set a fixed camera position looking at a specific area
J.setCameraFree([10, 5, 10], [0, 0, 0, 1]);

// Create a camera that follows an entity
const cameraOffset = J.vec3.fromValues(0, 4, 10);
const cameraLocalMatrix = J.mat4.fromTranslation(J.mat4.create(), cameraOffset);
const rot = J.quat.create();
const pos = J.vec3.create();
const _scale = J.vec3.create();
const cameraWorldMatrix = J.mat4.create();
Show all 21 lines

setLocalPlayerCamera() => void#

• Environment: client

Reattaches the camera to the local player, undoing setCameraFree. It does not change the distance, range or offset, so a camera you configured before going free comes back the way you left it.

tsCopy
// Return to normal player camera after using free camera
J.setLocalPlayerCamera();

setCameraDistance(distance: number) => void#

• Environment: client

Moves the camera to a distance behind the character, in world units. There is no separate first/third person setting: 0 is first person, and any other value is third person. Values between 0 and 1 are pushed out to 1 so the camera never ends up inside the character's head.

The distance is clamped to the range set by setCameraDistanceRange, and the player's own scrolling moves it within that range afterwards, so this sets the current zoom rather than locking it.

tsCopy
// drop into first person
J.setCameraDistance(0);

// pull back to a wide third-person view
J.setCameraDistance(8);

setCameraDistanceRange(min: number, max: number) => void#

• Environment: client

Limits how far the player may zoom with the scroll wheel (pinch on touch). Both values follow the same rule as setCameraDistance: 0 means first person, anything else is pushed out to at least 1. The current distance is clamped into the new range immediately.

• min - closest the player may zoom in. 0 lets them reach first person
• max - furthest the player may zoom out

tsCopy
// first person only, zooming disabled
J.setCameraDistanceRange(0, 0);

// third person only, locked at a fixed distance
J.setCameraDistanceRange(5, 5);

// let the player zoom across the full range (the default)
J.setCameraDistanceRange(0, 20);

setCameraOffset(right: number, up: number) => void#

• Environment: client

Shifts the point the camera orbits, in world units. Use it for an over-the-shoulder camera, or to raise the view above the character's eyes.

right follows the look direction, so a positive value keeps the camera over the character's right shoulder as they turn. up stacks on top of the character's eye height. Both apply in first and third person, and the offset is included in the wall collision check, so an offset camera still gets pushed in rather than clipping through geometry.

tsCopy
// over-the-shoulder third person
J.setCameraDistance(3);
J.setCameraOffset(0.8, 0.3);

// back to centred
J.setCameraOffset(0, 0);

getPlayerUsername(playerId: number) => string | undefined#

• Environment: both

Returns the username for a player entity ID, or undefined if the entity is not a player or the entity is not in the world.

tsCopy
J.onPlayerJoin((playerId) => {
  const username = J.getPlayerUsername(playerId)!;
  J.sendChatMessage(`Welcome to the game, ${username}!`);
});

getPlayerPhotoUrl(playerId: number) => string | undefined#

• Environment: both

Returns the photo url for a player entity ID, or undefined if the entity is not a player or the entity is not in the world.

setCharacterNameplate(characterId: number, visible?: boolean, textColor?: Vec3, text?: string) => void#

• Environment: client

Sets the nameplate's options for a character entity ID (players or NPCs). Nameplates are visible by default. It only works on Client.

The text parameter allows overriding the displayed nameplate text. If null or not provided, players will show their peer username automatically, while NPCs will have no nameplate.

tsCopy
// client.ts
J.onPlayerJoin((playerId) => {
  // enable nameplate and set green color
  J.setCharacterNameplate(playerId, true, [0, 1, 0]);

  // override player nameplate text
  J.setCharacterNameplate(playerId, true, undefined, "🎮 Player");
});

// Set custom nameplate for NPC
Show all 15 lines

getWorldPeerCount() => number#

• Environment: both

Returns the number of peers connected to the world.

tsCopy
J.onPlayerJoin(() => {
  const peerCount = J.getWorldPeerCount();
  J.sendChatMessage(`player joined! ${peerCount} players in game!`);
});

sendChatMessage(message: string, textColor?: string, toPlayerIds?: number[]) => void#

• Environment: both

Sends a chat message to all players or specific players. If toPlayerIds is not provided, the message is sent to all players. Called from client.ts, the message is only shown locally to that player and toPlayerIds is ignored.

tsCopy
// broadcast a message to all players when a player joins
J.onPlayerJoin((playerId) => {
  const username = J.getPlayerUsername(playerId)!;
  J.sendChatMessage(`Player ${username} has joined the game!`, "#00FF00");
});

// send a private message to a specific player
J.onPlayerJoin((playerId) => {
  J.sendChatMessage(`Psst, welcome to the game!`, "#0000FF", [playerId]);
});
Show all 13 lines

setPlayerPermissions: (playerId: EntityId, permissions: Partial<PlayerPermissions> => void#

• Environment: both

Sets a player's permissions.

tsCopy
// player setup
J.onPlayerJoin((playerId) => {
  // set permissions
  J.setPlayerPermissions(playerId, {
    canFly: false,
    canForceRespawn: false,
    canUseIndividualBlocks: false,
    canInteract: true,
  });
});

getPlayerPermissions: (playerId: EntityId) => PlayerPermissions | undefined#

• Environment: both

Gets a player's permissions.

setCharacterMovementProperties: (id: EntityId, properties: Partial<CharacterMovementProperties>) => void#

Sets the movement properties for a character entity.

tsCopy
J.onPlayerJoin((playerId) => {
  // set custom movement properties for the character
  J.setCharacterMovementProperties(playerId, {
    walkSpeed: 6,
  });
});

getCharacterMovementProperties: (id: EntityId) => CharacterMovementProperties | undefined#

• Environment: both

Gets the movement properties for a character entity. Returns undefined if the entity doesn't exist or is not a character.

setBlock(position: Vec3, shape: number, type: string) => void#

Sets the block at the specified coordinates with the given shape and type.

tsCopy
// clear the block at (0, 0, 0)
J.setBlock([0, 0, 0], J.BLOCK_SHAPE_AIR, "block#ABCDEFGHIJKLMNOPQRSTUVWX");

// set a block at (0, 0, 0)
J.setBlock([0, 0, 0], J.BLOCK_SHAPE_CUBE, "block#ABCDEFGHIJKLMNOPQRSTUVWX");

setBlocks(positions: Vec3[], shapes: number[], types: string[]) => void#

Sets many blocks at once, given as three parallel arrays (entry i of each array describes one block). Much faster than calling setBlock in a loop: the whole batch is applied and sent over the network as a single update. Use this whenever you change more than a handful of blocks (walls, floors, generated structures).

tsCopy
// build a 10x10 stone floor at y = 0
const positions = [];
const shapes = [];
const types = [];
for (let x = 0; x < 10; x++) {
  for (let z = 0; z < 10; z++) {
    positions.push([x, 0, z]);
    shapes.push(J.BLOCK_SHAPE_CUBE);
    types.push("block#ABCDEFGHIJKLMNOPQRSTUVWX");
  }
Show all 12 lines

getBlockShape(position: Vec3) => number#

• Environment: both

Gets the shape of the block at the specified coordinates.

getBlockType(position: Vec3) => string#

• Environment: both

Gets the type of the block at the specified coordinates.

getEntityPosition(id: number) => Vec3 | undefined#

• Environment: both

Gets the position of the entity with the given ID.

setEntityPosition(id: number, position: Vec3, teleport?: boolean) => void#

• Environment: both

Sets the position of the entity with the given ID.

teleport (default true) marks the move as a discontinuous jump: the entity snaps to the new position locally and every other client snaps as well instead of interpolating towards it. This is what you want for spawn placement, respawns and teleports. Pass false for continuous movement you drive every tick (moving platforms, custom motion), so clients keep interpolating smoothly between updates.

Teleporting a player character also overrides the position that player's own client reports until it has applied the teleport.

tsCopy
const prop = J.spawnProp(visual);
J.setEntityPosition(prop, pos); // snap into place
J.onGameTick(() => J.setEntityPosition(platform, nextPos, false)); // smooth per-tick motion

getEntityQuaternion(id: number) => Quat | undefined#

• Environment: both

Gets the rotation (quaternion) of the specified entity.

setEntityQuaternion(id: number, quaternion: Quat, teleport?: boolean) => void#

• Environment: both

Sets the rotation (quaternion) of the specified entity. teleport behaves exactly as in setEntityPosition: the default true snaps the rotation everywhere, false lets clients interpolate towards it for continuous per-tick rotation.

getEntityMatrix(entityId: EntityId) => Mat4 | undefined#

• Environment: both

Gets the complete transformation matrix of an entity, combining position, rotation, and scale. Returns undefined if the entity doesn't exist.

tsCopy
const matrix = J.getEntityMatrix(entityId);
if (matrix) {
  // Use matrix for advanced transformations
  const position = J.mat4.getTranslation([0, 0, 0], matrix);
  const rotation = J.mat4.getRotation([0, 0, 0, 1], matrix);
}

Character mesh attachments#

• Environment: client — not networked. Every client that should see the attachment must call these functions.

Attach a mesh to one of the character's body slots (addCharacterMeshAttachmentProp / addCharacterMeshAttachmentGlb), or to the local first-person view (addFirstPersonMeshAttachmentProp / addFirstPersonMeshAttachmentGlb, camera-relative, shown only while the local camera is first-person on that character). Prop variants take a prop, block-structure or block id; Glb variants take an inline { id, colors? } spec. Each returns a handle for setCharacterMeshAttachment / updateFirstPersonMeshAttachment and remove…, or -1 on failure.

Slots apply per-rig retargeting so the same offset works across all rigs (defaultMale, gnome, ogre, …). Available slots: "head" | "chest" | "waist" | "armLeft" | "armRight" | "handLeft" | "handRight" | "legLeft" | "legRight" | "footLeft" | "footRight"

After scale, attachments take optional tint, glow, outline (color) and outlineSize, with the same meaning as setEntityTint, setEntityGlow and setEntityOutline. Omit them for none; attachments don't take on the character's values.

Full equip/unequip pattern#

tsCopy
const rot = J.quat.setAxisAngle(J.quat.create(), [1, 0, 0], -1.5);
let handle3p = -1;
let handleFp = -1;

function equip(characterId: J.EntityId) {
    // yellow outline, no tint or glow
    handle3p = J.addCharacterMeshAttachmentGlb(characterId, { id: "item_smg" }, "handRight", [0, 0, 0], rot, 1.3, undefined, 0, [1, 0.8, 0, 1], 0.05);
    if (characterId === J.getLocalPlayer()) {
        handleFp = J.addFirstPersonMeshAttachmentGlb(characterId, { id: "item_smg" }, [0.5, -0.7, -0.7], [0, 0, 0, 1], 1);
    }
Show all 20 lines

Available item GLB ids: item_smg, item_sword, item_medShield — any id from the items_grp in the character GLB. Avatar component ids (e.g. nova_chest, aero_head) also work.

getCharacterSlotWorldMatrix(characterId: EntityId, slot: CharacterSlotId, localMatrix: Mat4) => Mat4 | undefined#

• Environment: client

Resolves a slot-local matrix into world space using the same per-rig retargeting attachments use. Returns undefined if the character has no visual or the slot is not bound on the active rig.

tsCopy
// muzzle is a 10cm forward offset on the right hand
const muzzleLocal = J.mat4.fromTranslation(J.mat4.create(), [0, 0, 0.1]);
const muzzleWorld = J.getCharacterSlotWorldMatrix(characterId, "handRight", muzzleLocal);
if (muzzleWorld) {
  const origin = J.mat4.getTranslation([0, 0, 0], muzzleWorld);
  J.spawnProjectile("#ff0", 50, characterId, null, origin, aimDirection);
}

getCharacterFirstPersonWorldMatrix(characterId: EntityId, localMatrix: Mat4) => Mat4 | undefined#

• Environment: client

Resolves a camera-local matrix into world space. Returns undefined when the local view is not first-person on that character.

First-person muzzle position#

tsCopy
// Muzzle position for shell ejection / muzzle flash (first-person only)
const fpLocal = J.mat4.fromTranslation(J.mat4.create(), [0.5, -0.3, -1.8]);
J.mat4.rotateY(fpLocal, fpLocal, -Math.PI / 2);

const m = J.getCharacterFirstPersonWorldMatrix(characterId, fpLocal);
if (m) {
    const pos: J.Vec3 = [m[12], m[13], m[14]]; // world position from matrix column 3
    const flash = J.spawnProp(FLASH_ASSET);
    J.setEntityPosition(flash, pos, false);
}

getEntityInterpolatedPosition(entityId: EntityId) => Vec3 | undefined#

• Environment: both

Gets the interpolated position (smoothed for rendering) of an entity. This differs from getEntityPosition as it includes client-side smoothing for visual continuity.

tsCopy
const interpolatedPos = J.getEntityInterpolatedPosition(entityId);
if (interpolatedPos) {
  // Use for smooth visual effects
  J.spawnParticlesAtPosition(interpolatedPos, "particle#12345");
}

getEntityInterpolatedQuaternion(entityId: EntityId) => Quat | undefined#

• Environment: both

Gets the interpolated quaternion (smoothed for rendering) of an entity. This provides smooth rotation values for visual effects.

tsCopy
const interpolatedQuat = J.getEntityInterpolatedQuaternion(entityId);
if (interpolatedQuat) {
  // Use for smooth visual calculations
  const forward = J.vec3.transformQuat([0, 0, 1], [0, 0, 1], interpolatedQuat);
}

getEntityVelocity(id: number) => Vec3 | undefined#

• Environment: both

Gets the current velocity of the entity.

addEntityVelocity(id: number, velocity: Vec3) => void#

• Environment: both

Adds to the entity's current velocity.

setEntityVelocity(id: number, velocity: Vec3) => void#

• Environment: both

Sets the velocity of the entity.

getEntityAngularVelocity(id: number) => Vec3 | undefined#

• Environment: both

Gets the angular velocity of the entity.

addEntityAngularVelocity(id: number, angularVelocity: Vec3) => void#

• Environment: both

Adds to the entity's angular velocity.

setEntityAngularVelocity(id: number, angularVelocity: Vec3) => void#

• Environment: both

Sets the angular velocity of the entity.

moveKinematicEntity(id: number, targetPosition: Vec3, targetQuaternion: Quat) => void#

• Environment: both

Sets the linear and angular velocity of a kinematic entity such that it reaches the target position and quaternion in the next physics tick.

This API is intended to be called every tick to set new velocities. If you stop calling this method and want an entity to stop moving entirely, you should call setEntityVelocity and setEntityAngularVelocity with zero vectors.

addEntityImpulse(id: number, impulse: Vec3) => void#

• Environment: both

Applies an impulse to the entity. Supports props.

addEntityImpulseAtPoint(id: number, impulse: Vec3, point: Vec3) => void#

• Environment: both

Applies an impulse to the entity at a specific point. Supports props.

addEntityAngularImpulse(id: number, angularImpulse: Vec3) => void#

• Environment: both

Applies an angular impulse to the entity. Supports props.

getEntityMass(id: number) => number | undefined#

• Environment: both

Gets the mass of the entity. Supports characters and props.

getEntityVelocityAtPoint(id: number, point: Vec3) => Vec3 | undefined#

• Environment: both

Gets the velocity of the entity at a specific point in world space. Supports props.

addEntityForce(entityId: EntityId, force: Vec3, point: Vec3) => void#

• Environment: both

Applies a continuous force to an entity at a specific point. Unlike impulses, forces are applied continuously over time. Use this for constant effects like gravity wells, wind, or pushing objects.

tsCopy
// Apply upward force at the center of a prop
J.addEntityForce(propId, [0, 50, 0], [0, 0, 0]);

// Apply force at an offset point to create torque
J.addEntityForce(propId, [100, 0, 0], [0, 2, 0]);

getEntityInverseInertia(entityId: EntityId) => Mat4 | undefined#

• Environment: both

Gets the inverse inertia tensor matrix of an entity. This represents how resistant the entity is to rotational acceleration. Returns undefined if the entity doesn't exist or doesn't have physics.

tsCopy
const inertia = J.getEntityInverseInertia(propId);
if (inertia) {
  // Use the inertia matrix for physics calculations
}

getEntityBodyActive(id: number) => boolean | undefined#

• Environment: both

Gets whether the entity's physics body is currently active. Supports props.

An entity may become "inactive" or "go to sleep" if it has been stationary for a while.

Usually applying an impulse, or changing the entity's velocity will automatically reactivate the body. In rare cases you may want to manually activate the body using activateEntityBody however.

activateEntityBody(id: number) => void#

• Environment: both

Activates the entity's physics body. Supports props.

getEntityScale(id: number) => number | undefined#

• Environment: both

Gets the scale of the entity.

getEntityBlockCollision(id: number) => Vec3[]#

• Environment: both

Gets the positions of blocks that the entity is currently colliding with. Returns an empty array if the entity doesn't exist or is not a physical entity.

tsCopy
// spawn a prop that can collide with blocks
const propId = J.spawnProp("prop#ABCDE12345");

// check which blocks the entity is colliding with
const collisions = J.getEntityBlockCollision(propId);
collisions.forEach((position) => {
  console.log(`Entity is colliding with block at (${position[0]}, ${position[1]}, ${position[2]})`);

  // change each colliding block to a red block
  J.setBlock(position, J.BLOCK_SHAPE_CUBE, "block#ABCDE12345");
Show all 11 lines

setEntityGravityFactor(entityId: EntityId, gravityFactor: number) => void#

• Environment: both

Sets how much gravity affects an entity. 0 = no gravity, 1 = normal gravity, 2 = double gravity. Use this for anti-gravity zones, moon physics, or custom gravity effects.

tsCopy
// Make an entity float (no gravity)
J.setEntityGravityFactor(propId, 0);

// Make an entity heavy (double gravity)
J.setEntityGravityFactor(propId, 2);

// Moon gravity (1/6 Earth gravity)
J.setEntityGravityFactor(propId, 0.166);

setEntityScale(id: number, scale: number) => void#

• Environment: both

Sets the scale of the entity.

setEntityTint(id: number, tint: Vec4) => void#

• Environment: client

Sets the tint color for a prop or character entity. The tint is applied as a color overlay that is mixed with the final color based on the alpha component. Works on prop and character (creature/player) entities; other entity kinds are ignored. On characters and GLB-component props the tint color is quantized to 4 bits per channel (fine for flashes/overlays).

tsCopy
// set a R = 50%, G = 30%, B = 20% tint, mixed in by 50%
J.setEntityTint(propId, [0.5, 0.3, 0.2, 0.5]);

// make an entity appear completely blue (full blue with 100% mix)
J.setEntityTint(entityId, [0.0, 0.0, 1.0, 1.0]);

// remove tinting (color is irrelevant, as it is mixed by 0%)
J.setEntityTint(entityId, [1.0, 1.0, 1.0, 0.0]);

setEntityGlow(id: number, glow: number) => void#

• Environment: client

Sets the glow multiplier for a prop or character entity. The glow value is a float from 0 to 1 that controls how much the entity ignores darkness and shadows. Changing this can allow your entity to visually stand out. Works on prop and character (creature/player) entities; other entity kinds are ignored. Default is 0.

tsCopy
// make an entity have no glow (fully affected by lighting)
J.setEntityGlow(entityId, 0.0);

// make the entity glow fully (ignore lighting completely)
J.setEntityGlow(entityId, 1.0);

setEntityOutline(id: number, size: number, color: Vec4) => void#

• Environment: client

Sets the outline size and color for a prop or character entity. size is clamped from 0 to 1, and the color components are clamped from 0 to 1 when rendered. A size of 0.25 draws a thick outline; larger sizes are only useful on small objects. Set the size or color alpha to 0 to remove the outline. Outlines are local visual state, so each client that should see one must set it from client.ts.

tsCopy
// add a blue outline
J.setEntityOutline(entityId, 0.035, [0.15, 0.75, 1.0, 1.0]);

// remove the outline
J.setEntityOutline(entityId, 0, [0, 0, 0, 0]);

setEntityVisible(id: number, isVisible: boolean) => void#

• Environment: client

Sets the visibility of an entity. When set to false, the entity will be hidden from view. This is a client-side only concept - the entity still exists and functions normally on the server, but is not rendered on the client.

tsCopy
// spawn entity
const propId = J.spawnProp(J.assets.props.MyCoin.id);

// hide entity
J.setEntityVisible(propId, false);

setEntityVisualOffset(id: number, offset: Vec3) => void#

• Environment: client

Applies a visual-only position offset to an entity's rendered position. This offset is purely cosmetic and does not affect physics, collisions, or networking. Perfect for juice effects like floating, bobbing, or screen shake.

tsCopy
// make a prop float up and down
J.onGameRender(() => {
  const bobAmount = Math.sin(J.getWorldTime() * 0.003) * 0.2;
  J.setEntityVisualOffset(propId, [0, bobAmount, 0]);
});

// offset a character slightly to the right
J.setEntityVisualOffset(characterId, [0.5, 0, 0]);

// clear the offset
Show all 11 lines

getEntityVisualOffset(id: number) => Vec3 | undefined#

• Environment: client

Gets the current visual offset applied to an entity. Returns undefined if the entity does not exist.

tsCopy
const offset = J.getEntityVisualOffset(propId);
if (offset) {
  console.log(`Offset: x=${offset[0]}, y=${offset[1]}, z=${offset[2]}`);
}

setEntityVisualQuaternion(id: number, quaternion: Quat) => void#

• Environment: client

Applies a visual-only rotation (as a quaternion) on top of the entity's actual rotation. This rotation is purely cosmetic and does not affect physics, collisions, or networking. Perfect for spin effects, wobbles, or other visual rotations.

The visual quaternion is relative, and composed in the entity's local space:

renderedRotation = entityRotation x visualQuaternion

so it turns the entity around its own axes, not the world's. To face a fixed world direction, pass inverse(entityRotation) x desiredWorldRotation.

It stays applied every frame until you change it. Set it back to identity [0, 0, 0, 1] to turn it off; an effect that blends out to identity releases itself, no cleanup call needed.

tsCopy
// create a spinning effect (you'll need to update this each frame)
J.onGameRender(() => {
  const rotation = (J.getWorldTime() * 0.001) % (Math.PI * 2);
  const halfRotation = rotation * 0.5;
  J.setEntityVisualQuaternion(propId, [0, Math.sin(halfRotation), 0, Math.cos(halfRotation)]);
});

// apply a 45-degree tilt
const halfTilt = Math.PI / 8;
J.setEntityVisualQuaternion(propId, [0, 0, Math.sin(halfTilt), Math.cos(halfTilt)]);
Show all 13 lines

getEntityVisualQuaternion(id: number) => Quat | undefined#

• Environment: client

Gets the current visual quaternion applied to an entity. Returns undefined if the entity does not exist.

tsCopy
const quat = J.getEntityVisualQuaternion(propId);
if (quat) {
  console.log(`Rotation: x=${quat[0]}, y=${quat[1]}, z=${quat[2]}, w=${quat[3]}`);
}

setEntityVisualScale(id: number, scale: Vec3) => void#

• Environment: client

Applies a visual-only scale multiplier to an entity. The scale is applied component-wise (x, y, z) on top of the entity's actual scale. This is purely cosmetic and does not affect physics, collisions, or networking. Perfect for squash & stretch effects, impact animations, or other visual feedback.

tsCopy
// make a prop appear 50% larger visually (without affecting physics)
J.setEntityVisualScale(propId, [1.5, 1.5, 1.5]);

// non-uniform scale for a pancake effect
J.setEntityVisualScale(propId, [1.5, 0.2, 1.5]);

// clear the visual scale
J.setEntityVisualScale(propId, [1, 1, 1]);

getEntityVisualScale(id: number) => Vec3 | undefined#

• Environment: client

Gets the current visual scale applied to an entity. Returns undefined if the entity does not exist.

tsCopy
const scale = J.getEntityVisualScale(propId);
if (scale) {
  console.log(`Scale: x=${scale[0]}, y=${scale[1]}, z=${scale[2]}`);
}

entityLookAt(id: number, target: Vec3) => void#

• Environment: both

Makes an entity look at a specific position. For character entities, uses spherical coordinates for camera control. For other entities, rotates them to face the target point.

tsCopy
// spawn entities
const characterId = J.spawnCharacter("avatar#ABCDE12345");
const propId = J.spawnProp("prop#ABCDE12345");

// make the character look at a specific position (uses camera control)
J.entityLookAt(characterId, [10, 5, 20]);

// make a prop face a specific position (rotates the prop)
J.entityLookAt(propId, [0, 0, 10]);
Show all 13 lines

characterJump(characterId: EntityId, velocity: number, force: boolean, teleport: boolean) => void#

• Environment: both

Makes a character entity jump with the specified velocity. Only works on character entities (players and NPCs). With teleport the new velocity is applied to a player even if that player's client reports otherwise; without it a player's own simulation may override the jump.

tsCopy
// make all players jump with high velocity
const players = J.getAllPlayers();
players.forEach((playerId) => {
  J.characterJump(playerId, 15.0, true, false);
});

characterUse: (id: EntityId, primary: boolean, secondary: boolean) => void#

• Environment: both

Makes a character entity use an item or perform an action. The primary and secondary parameters indicate which action to perform.

tsCopy
J.onGameStart(() => {
  // spawn a character
  const characterId = J.spawnCharacter(J.assets.avatars.MyAvatar.id);

  // make the character perform a primary use action
  J.characterUse(characterId, true, false);

  // make the character perform a secondary use action
  J.characterUse(characterId, false, true);
});

getCharacterCrouching: (characterId: EntityId) => boolean#

• Environment: both

Returns whether the character is currently crouching.

setCharacterCrouching: (characterId: EntityId, crouching: boolean) => void#

• Environment: both

Sets whether the character is crouching. This only works on NPC character entities.

setCharacterMoveTarget: (id: EntityId, targets: Vec3[]) => void#

• Environment: both

Sets the movement targets for a character entity. The character will move towards these targets in order.

tsCopy
J.onGameStart(() => {
  // spawn a character
  const characterId = J.spawnCharacter(J.assets.avatars.MyAvatar.id);

  // set movement targets for the character
  const targets: J.Vec3[] = [
    [10, 0, 10],
    [20, 0, 20],
    [30, 0, 30],
  ];
Show all 12 lines

clearCharacterMoveTarget: (id: EntityId) => void#

• Environment: both

Clears the movement targets for a character entity. The character will stop moving towards any targets.

tsCopy
// clear the movement targets for a character
J.clearCharacterMoveTarget(characterId);

setCharacterLookAtTarget: (id: EntityId, target: Vec3) => void#

• Environment: both

Sets the "look at" target for a character.

If a character also has a "move target" it will continue looking at the "look at target" while moving to the next "move target".

clearCharacterLookAtTarget: (id: EntityId) => void#

• Environment: both

Clears the "look at" target for a character.

characterPlayAnimation: (id: EntityId, clip: string, opts?: { mode?: "loop" | "once" | "hold"; speed?: number; fadeIn?: number; cancelOnMove?: boolean }) => void#

• Environment: both

Plays a GLB animation on a character controlled by the current runtime. Clients control their local player and client-created characters; the server controls server-created NPCs. Calling this for a replayed character throws. The controller's animation state replicates to every observer, and replaying the same clip starts it again. The clip's playback mode is derived from the clip name:

• clips with no suffix are base clips — they occupy the character's single base slot, replacing whichever locomotion or emote clip would otherwise play. Playing a new base clip automatically clears any previous base clip.
• clips ending in _add are additive — they blend on top of the base (and other additives) as a delta from the bind pose. Useful for hit reactions, lean, impulses, etc.
• clips ending in _over are override — they play concurrently with the base at full weight. _over clips are authored with partial-bone tracks, so e.g. twoHanded_idle_over only affects arms while legs keep following locomotion.

Every clip name present in the GLB is available via J.assets.animations.<name>.id (locomotion, emotes, _add, and _over — anything the mixer can resolve).

Options:

• mode — what the clip does when it reaches its end:

  • "loop" — restart from the beginning, indefinitely.
  • "once" — play through once, then clear the clip. A base clip returns the base slot to locomotion; additive/override layers stop.
  • "hold" — play through once, then freeze on the final frame until the clip is explicitly stopped (characterStopAnimation / clearCharacterAnimations) or replaced. Ideal for death poses, knockouts, etc.

  Defaults to "loop" for base/override clips and "once" for additive clips.

• speed — playback rate multiplier (default 1). Negative values start at the end and play backwards; 0 pauses the animation.

• fadeIn — crossfade-in duration when the clip starts. Defaults to 0.1s for base clips, 0 for additive/override.

• cancelOnMove — when true, the controller drops the animation when its resolved locomotion leaves idle. Useful for emote-style base clips.

tsCopy
// server.ts can animate a server-controlled NPC.
const npcId = J.spawnCharacter("avatar#example");

// looping dance emote, auto-cancel when the player moves
J.characterPlayAnimation(npcId, J.assets.animations.emotes_danceBasic.id, {
  cancelOnMove: true,
});

// one-shot hit reaction on top of whatever locomotion is playing
J.characterPlayAnimation(npcId, "locomotion_default_hit_add");
Show all 25 lines

characterSetAnimationSpeed: (id: EntityId, clip: string, speed: number) => void#

• Environment: both

Changes the playback speed of an active animation without restarting it. Use a negative speed to reverse direction, 0 to pause, and a positive speed to play forwards. Has no effect if the clip is not active.

tsCopy
J.characterSetAnimationSpeed(npcId, J.assets.animations.emotes_danceBasic.id, -1);

characterStopAnimation: (id: EntityId, clip: string, opts?: { fadeOut?: number }) => void#

• Environment: both

Stops a specific animation clip on a character. Has no effect if the clip isn't currently playing. For base clips, stopping the clip returns the base slot to whatever locomotion resolves to next frame.

tsCopy
J.characterStopAnimation(playerId, "twoHanded_idle_over", { fadeOut: 0.2 });

clearCharacterAnimations: (id: EntityId) => void#

• Environment: both

Stops every animation currently playing on the character — base, additive, and override. Locomotion takes over the base slot again on the next frame.

tsCopy
J.clearCharacterAnimations(playerId);

getCharacterViewRay(id: number) => { origin: Vec3; direction: Vec3; hitEntityId: number | undefined; hitBlock: Vec3 | undefined } | undefined#

• Environment: both

Gets the current view ray of the character.

getCharacterInput: (id: EntityId) => object | undefined#

• Environment: both

Gets the input object for a character entity. The input object contains all current input states including movement, camera orientation, and action states.

tsCopy
const playerId = J.getLocalPlayer();
const input = J.getCharacterInput(playerId)!;
console.log("Player input:", input);
// access input properties like input.nipple, input.camera, etc.

getPointer: () => object#

• Environment: client

Returns the screen-space pointer state — the mouse on desktop, the primary touch on mobile: { x, y, isDown, justPressed, justReleased, locked, touch }. Positions are CSS pixels with a top-left origin, the same coordinate space as the onGameUiCanvas context and getScreenPosition. justPressed and justReleased are true only on the frame the press or release happened, and on a release frame x/y still hold the release position, so release-based click checks work. While locked (pointer lock, i.e. gameplay mouselook) there is no cursor, so skip hit-testing. On mobile touch is true and x/y are -1, -1 while no touch is active.

This is primarily relevant for interactive canvas UI drawn with onGameUiCanvas — poll it every frame and hit-test your rects against it. HTML-based UI usually doesn't need it: elements under uiElement receive normal DOM pointer events directly.

tsCopy
J.onGameUiCanvas((ctx, width, height) => {
  const p = J.getPointer();
  const x = width - 120, y = height - 60, w = 100, h = 40;
  const hover = !p.locked && p.x >= x && p.x < x + w && p.y >= y && p.y < y + h;
  ctx.fillStyle = hover ? "#3d8f27" : "#2e6e1c";
  ctx.fillRect(x, y, w, h);
  if (hover && p.justPressed) buyItem();
});