---
title: Packet flags
description: 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](/packets/play/synchronizeplayerposition) uses bits to mark which coordinates are relative, [PlayerAbilities](/packets/play/playerabilities-clientbound) 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.

```ts
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.

```ts
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.

```ts
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](/packets/play/synchronizeplayerposition) and [TeleportEntity](/packets/play/teleportentity). Sent as a 32-bit integer. A set bit means the field is added to the current value instead of replacing it.

| Name | Bit | Meaning |
| --- | --- | --- |
| `x` | `0x01` | X is relative |
| `y` | `0x02` | Y is relative |
| `z` | `0x04` | Z is relative |
| `yaw` | `0x08` | Yaw is relative |
| `pitch` | `0x10` | Pitch is relative |
| `velocityX` | `0x20` | Velocity X is added to the current velocity |
| `velocityY` | `0x40` | Velocity Y is added to the current velocity |
| `velocityZ` | `0x80` | Velocity Z is added to the current velocity |
| `rotateVelocity` | `0x100` | Rotate the current velocity by the yaw and pitch change before adding |

### `PLAYER_ABILITY_FLAGS`

Clientbound [PlayerAbilities](/packets/play/playerabilities-clientbound). The serverbound [PlayerAbilities](/packets/play/playerabilities-serverbound) packet only carries `flying`; use `CLIENT_ABILITY_FLAGS` / `clientAbilityFlags` for it.

| Name | Bit |
| --- | --- |
| `invulnerable` | `0x01` |
| `flying` | `0x02` |
| `allowFlying` | `0x04` |
| `creativeMode` | `0x08` |

### `MOVEMENT_FLAGS`

Serverbound [MovePlayerPos](/packets/play/moveplayerpos), [MovePlayerPosRot](/packets/play/moveplayerposrot), [MovePlayerRot](/packets/play/moveplayerrot) and [MovePlayerStatusOnly](/packets/play/moveplayerstatusonly). These writers also accept `{ onGround, hasHorizontalCollision }` directly.

| Name | Bit |
| --- | --- |
| `onGround` | `0x01` |
| `horizontalCollision` | `0x02` |

### `MOB_EFFECT_FLAGS`

[UpdateMobEffect](/packets/play/updatemobeffect).

| Name | Bit | Meaning |
| --- | --- | --- |
| `ambient` | `0x01` | Beacon-style effect: fainter particles |
| `showParticles` | `0x02` | Render particles |
| `showIcon` | `0x04` | Show the icon in the HUD |
| `blend` | `0x08` | Fade the effect's visuals in and out |

### `BOSS_EVENT_FLAGS`

[BossEvent](/packets/play/bossevent), for the Add (`0`) and Update Flags (`5`) actions.

| Name | Bit |
| --- | --- |
| `darkenSky` | `0x01` |
| `playMusic` | `0x02` |
| `createFog` | `0x04` |

### `COMMAND_BLOCK_FLAGS`

Serverbound [ProgramCommandBlock](/packets/play/programcommandblock).

| Name | Bit |
| --- | --- |
| `trackOutput` | `0x01` |
| `conditional` | `0x02` |
| `automatic` | `0x04` |

### `STOP_SOUND_FLAGS`

[StopSound](/packets/play/stopsound). Each bit says which optional field follows; the writer only encodes `source` and `sound` when the matching bit is set.

| Name | Bit |
| --- | --- |
| `hasSource` | `0x01` |
| `hasSound` | `0x02` |

### `SKIN_PART_FLAGS`

Serverbound [ClientInformation](/packets/play/clientinformation) `skinParts` (read back as `displayedSkinParts`), and the same byte in player [entity metadata](/docs/entity-metadata).

| Name | Bit |
| --- | --- |
| `cape` | `0x01` |
| `jacket` | `0x02` |
| `leftSleeve` | `0x04` |
| `rightSleeve` | `0x08` |
| `leftPants` | `0x10` |
| `rightPants` | `0x20` |
| `hat` | `0x40` |

## 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.