GuideMaintainer authored

Teleport, kick and other player actions

Move, revive, dismount, slow down, kick, relabel and message a player from the server.

The verbs on Player move a player, change their pace, kick them, relabel their nametag and send events to their client.

Events.on("playerCommand", (player, command) => {
  if (command !== "home") return;

  if (!player.teleport({ x: -1423.5, y: 2871.2, z: 118.0 }, "Home")) {
    Chat.sendToPlayer(player, "Could not reach your client to move you.");
  }
});

Move a player

Call	Use it for
`player.spawn(position, rotation?)`	Anywhere the ground may not be loaded on their machine. Holds the body until there is ground under it.
`player.teleport(position, label?)`	Short hops. Uses your height exactly. The label shows in their teleport panel.

Do not write player.position to move someone. Join, spawn and respawn has the details.

Two bodies in one spot get shoved apart in a random direction, so the default gamemode’s /tp lands two metres in front of the target:

function moveNextTo(player: Player, target: Player): boolean {
  if (!target.ready) return false; // their position has not arrived yet

  const look = target.lookDirection;
  const flat = Math.hypot(look.x, look.y) || 1;
  const destination = new Vector3(
    target.position.x + (look.x / flat) * 2,
    target.position.y + (look.y / flat) * 2,
    target.position.z,
  );
  return player.teleport(destination, target.nickname);
}

Revive a player

player.revive() only means something after playerDied. It returns false if they are disconnected, have not died, or a revival is already on its way. See Respawn after a death.

Take someone off a horse

player.dismount() takes them out of the saddle on every client and returns the Horse, or null if they were on foot. player.mount(horse) requests the normal get-on animation; player.mount(horse, { instant: true }) requests an immediate seat. Stand the player near the horse first. Both are client requests: horseMounting can still refuse them, and horseMount confirms the result. A player who streams in later sees the rider already seated. See Horses.

Set walking pace

player.setMovementMode(mode) has two independent switches:

Key	Effect
`walkByDefault`	Walking is the pace they return to, after a sprint too. Their walk toggle still works.
`walkEnforced`	No running or sprinting at all. Holds the engine’s own run and sprint permissions, so no key gets around it. Lifting it hands back what the body had.

player.setMovementMode({ walkEnforced: true }); // inside the town walls
player.setMovementMode({});                     // leaving town: lift the rule

Other players are not told; they see the pace this body’s animation reports. On a gamepad the stick’s deflection decides pace, and walkByDefault does not override it.

Kick a player

player.kick("Idling too long");

kick disconnects at once, with an optional reason shown to them. playerDisconnect still fires, so your cleanup runs. It is safe from any handler, including playerSpawning.

Change a nametag

player.setNametagText("[Guard] " + player.nickname); // no argument or "" restores their name
player.setNametagColor(0xFFD4A017);                  // 0xAARRGGBB: opaque gold
player.setNametagHealthVisible(false);               // hide the health bar, keep the name
player.setNametagVisible(true);

Getters: getNametagText(), getNametagColor(), isNametagVisible(), isNametagHealthVisible(). Nametag colours are alpha first, the opposite of chat colours. Each player can still hide all nametags on their own screen; see HUD and nametags.

Send an event to their client

player.emit(name, json?) sends a named event to that player’s client resource. The payload is a JSON string; the client receives it parsed, and drops invalid JSON with an error in its log.

player.emit("my-mode:round.start", JSON.stringify({ round: 3, seconds: 180 }));

See Send data between server and client.

A player is also an Entity, so player.state (state bags) and player.setVirtualWorld(world) (virtual worlds) work too.

Hide a player’s body

The server can hide or show a player’s body:

player.setVisible(false);
// Later, when the effect ends:
player.setVisible(true);

This hides the body, clothes, armor, sheathed weapons and held items on the owner’s screen and other clients. Players who come into range later also see the body as hidden. player.visible reads the owning client’s reported state; the setter returns whether the request was sent.

The hidden player still has collision, can take damage, use weapons and die, and NPCs can still detect them. Nametags are separate: use player.setNametagVisible(false) if your mode should hide those too. The body stays hidden until another call or the player disconnects. Restore visibility when your effect ends.

Join, spawn and respawn, for spawn points and death
Read health, stats and skills, for what you can read back
Items: give, take and drop
Buffs and status effects