Packet flags

Named bit flags for the packets that carry a raw flags number, with pack and unpack helpers.

Some packets carry a single number where each bit means something different. SynchronizePlayerPosition uses bits to mark which coordinates are relative, PlayerAbilities uses them for flying and invulnerability, and so on. The library sends these as plain numbers. helpers.packFlags builds the number from names, and helpers.unpackFlags turns a received number back into booleans.

import { helpers } from "mc-protocol";

// Move the player 5 blocks up, keep everything else.
// Unset velocity flags replace the velocity, so mark those relative too.
await client.sendPacket("SynchronizePlayerPosition", {
  teleportId: 1,
  x: 0, y: 5, z: 0,
  velocityX: 0, velocityY: 0, velocityZ: 0,
  flags: helpers.teleportFlags(["x", "y", "z", "yaw", "pitch", "velocityX", "velocityY", "velocityZ"]),
});

// Let the player fly.
await client.sendPacket("PlayerAbilities", {
  flags: helpers.playerAbilityFlags({ flying: true, allowFlying: true }),
  flyingSpeed: 0.05,
  walkingSpeed: 0.1,
});

// Read the flags a client sends back.
client.on("PlayerAbilities", (data) => {
  const { flying } = helpers.unpackFlags(helpers.PLAYER_ABILITY_FLAGS, data.flags);
});

packFlags(map, flags)

Returns the number for a packet’s flags field. map is one of the constant maps below. flags is either an array of names to set or an object of name: boolean. Unknown names throw a RangeError at runtime and are a type error at compile time. Map values must be single bits within 32 bits; the built-in maps are, and custom maps are checked. Names listed twice set their bit once.

helpers.packFlags(helpers.TELEPORT_FLAGS, ["x", "yaw"]);            // 0x09
helpers.packFlags(helpers.TELEPORT_FLAGS, { x: true, yaw: false }); // 0x01

Each map also has a shorthand: teleportFlags, playerAbilityFlags, clientAbilityFlags, movementFlags, mobEffectFlags, bossEventFlags, commandBlockFlags, stopSoundFlags and skinPartFlags. They take the same flags argument.

unpackFlags(map, value)

Returns an object with every name in the map set to true or false. Bits the map does not name are ignored. hasFlag(map, value, name) checks one bit.

helpers.unpackFlags(helpers.PLAYER_ABILITY_FLAGS, 0x06);
// { invulnerable: false, flying: true, allowFlying: true, creativeMode: false }
helpers.hasFlag(helpers.MOB_EFFECT_FLAGS, 0x08, "blend"); // true

Flag maps

The maps are frozen objects of name: bit. Each has a matching name union (TeleportFlag, PlayerAbilityFlag, …) for typing your own code. Values were checked against the 26.2 server.

TELEPORT_FLAGS

SynchronizePlayerPosition and TeleportEntity. Sent as a 32-bit integer. A set bit means the field is added to the current value instead of replacing it.

PLAYER_ABILITY_FLAGS

Clientbound PlayerAbilities. The serverbound PlayerAbilities packet only carries flying; use CLIENT_ABILITY_FLAGS / clientAbilityFlags for it.

MOVEMENT_FLAGS

Serverbound MovePlayerPos, MovePlayerPosRot, MovePlayerRot and MovePlayerStatusOnly. These writers also accept { onGround, hasHorizontalCollision } directly.

MOB_EFFECT_FLAGS

UpdateMobEffect.

BOSS_EVENT_FLAGS

BossEvent, for the Add (0) and Update Flags (5) actions.

COMMAND_BLOCK_FLAGS

Serverbound ProgramCommandBlock.

STOP_SOUND_FLAGS

StopSound. Each bit says which optional field follows; the writer only encodes source and sound when the matching bit is set.

SKIN_PART_FLAGS

Serverbound ClientInformation skinParts (read back as displayedSkinParts), and the same byte in player entity metadata.

Packets with named flags already

Some packets take an object of booleans directly and do not need this helper: PlayerInput, SetPlayerTeam, RecipeBookAdd and the UpdateAdvancements display flags. Check the packet page for the field shape.