# Message reference

Source: https://tehoclient.dev/protocol/messages
SDK: 1.0.0

Every framed message, with its type id and the capability it belongs to. Fields are listed in field-number order, starting at 1. Nested types such as rows and entries are defined in `teho_api.proto`.

**C -> S** messages are sent by the client and **S -> C** by the server. `Reply` and `Chunk` go both ways.

## Core

Always available after the handshake.

| Type | Message | Direction |
|---|---|---|
| `0x01` | `Hello{protocol, client, minecraft, platform, capabilities[]}` | C -> S |
| `0x02` | `Welcome{protocol, session, enabled[], server_name, grant, verified}` | S -> C |
| `0x03` | `HelloRequest{}` | S -> C |
| `0x04` | `Reset{}` | S -> C |
| `0x05` | `Reply{request_id, ok, error, data}` | Both |
| `0x06` | `Event{kind, target, value, request_id}` | C -> S |
| `0x07` | `Chunk{stream, index, total, data}` | Both |
| `0x0D` | `ConsentResult{scope, granted, items[]}` | C -> S |
| `0x0E` | `PrivateStatus{capabilities[], error, server}` | C -> S |

## Assets

Capability `asset:1`.

| Type | Message | Direction |
|---|---|---|
| `0x08` | `AssetOffer{hash, kind, size}` | S -> C |
| `0x09` | `AssetWant{hashes[]}` | C -> S |
| `0x0C` | `AssetData{hash, kind, data}` | S -> C |

## Notifications

Capability `notify:1`.

| Type | Message | Direction |
|---|---|---|
| `0x10` | `Notify{id, title, body, accent, duration_ms, sound}` | S -> C |
| `0x11` | `Dismiss{id}` | S -> C |

## Waypoints

Capability `waypoint:1`.

| Type | Message | Direction |
|---|---|---|
| `0x20` | `WaypointSet{id, name, x, y, z, dimension, color, focus}` | S -> C |
| `0x21` | `WaypointRemove{id}` | S -> C |
| `0x22` | `WaypointClear{}` | S -> C |

## Module rules

Capability `modules:1`.

| Type | Message | Direction |
|---|---|---|
| `0x30` | `ModuleRules{disabled[], disabled_categories[], reason, competitive, allowed[]}` | S -> C |
| `0x31` | `SettingCaps{caps[]}` | S -> C |
| `0x32` | `CombatRules{legacy_swing, legacy_blockhit, no_hit_delay_visual, miss_penalty_visual, legacy_hit_color}` | S -> C |
| `0x33` | `ThirdPartyPolicy{deny[], reason, report}` | S -> C |
| `0x34` | `PolicyReport{granted, violations[]}` | C -> S |

## Staff tools

Capability `staff:1`.

| Type | Message | Direction |
|---|---|---|
| `0x40` | `StaffGrant{tools[], reason, xray_blocks[], radius, storage_blocks[], entity_types[]}` | S -> C |
| `0x41` | `StaffRevoke{tools[]}` | S -> C |
| `0x42` | `StaffState{tool, active}` | C -> S |
| `0x43` | `EspStyle{entries[]}` | S -> C |
| `0x44` | `StaffSupport{tools[]}` | C -> S |
| `0x45` | `Highlight{id, kind, entity, x, y, z, x2, y2, z2, color, label, style, tracer, ttl_ms, dimension}` | S -> C |
| `0x46` | `HighlightRemove{ids[]}` | S -> C |
| `0x47` | `Trail{player, points[], color, label, ttl_ms, dimension}` | S -> C |
| `0x48` | `InspectRequest{request_id, kind, target, x, y, z}` | C -> S |
| `0x49` | `InspectCard{request_id, title, subtitle, rows[], actions[], ttl_ms, target}` | S -> C |
| `0x4A` | `ActionWheel{actions[], title}` | S -> C |
| `0x4B` | `Alert{id, severity, title, body, player, x, y, z, dimension, ttl_ms}` | S -> C |
| `0x4C` | `TargetStats{player, rows[], ttl_ms}` | S -> C |
| `0x4D` | `Spectate{player, distance}` | S -> C |
| `0x4E` | `StaffAction{action, target_kind, target, x, y, z}` | C -> S |
| `0x4F` | `LagMap{cells[], dimension, ttl_ms}` | S -> C |

## HUD

Capability `hud:1`.

| Type | Message | Direction |
|---|---|---|
| `0x50` | `Cooldown{id, label, duration_ms, item, asset, color}` | S -> C |
| `0x51` | `CooldownClear{}` | S -> C |
| `0x52` | `Timer{id, label, mode, millis, paused, color}` | S -> C |
| `0x53` | `TimerRemove{id}` | S -> C |
| `0x54` | `SidebarSet{title, rows[], remove[], replace, accent, footer}` | S -> C |
| `0x55` | `SidebarClear{}` | S -> C |
| `0x56` | `Bar{id, text, progress, color, style, ttl_ms, item}` | S -> C |
| `0x57` | `BarRemove{ids[]}` | S -> C |
| `0x58` | `KillFeed{killer, victim, weapon, text, color, killer_id, victim_id, ttl_ms}` | S -> C |
| `0x59` | `ScreenTint{color, vignette, fade_ms, ttl_ms, strength}` | S -> C |
| `0x5A` | `Title{title, subtitle, animation, fade_in_ms, stay_ms, fade_out_ms, color, scale}` | S -> C |
| `0x5B` | `TntFuse{fuse_ticks}` | S -> C |

## Suspect tools

Capability `suspect:1`.

| Type | Message | Direction |
|---|---|---|
| `0x60` | `FreezeScreen{on, title, body}` | S -> C |
| `0x61` | `ScreenshotRequest{request_id, reason, max_width}` | S -> C |
| `0x62` | `ScreenshotResult{request_id, granted, png, width, height}` | C -> S |
| `0x63` | `ModListRequest{request_id, reason}` | S -> C |
| `0x64` | `ModList{request_id, granted, mods[], teho_modules[]}` | C -> S |

## NPC cosmetics

Capability `npc:1`.

| Type | Message | Direction |
|---|---|---|
| `0x70` | `NpcLook{npc, mode, slots[]}` | S -> C |
| `0x71` | `NpcEmote{npc, action, emote, loop}` | S -> C |
| `0x72` | `NpcClear{npcs[]}` | S -> C |

## World visuals

Capability `world:1`.

| Type | Message | Direction |
|---|---|---|
| `0x80` | `Beam{id, x, y, z, entity, color, height, width, pulse, dimension, ttl_ms}` | S -> C |
| `0x81` | `Hologram{id, x, y, z, entity, lines[], item, asset, scale, background, clickable, through_walls, dimension, ttl_ms, range}` | S -> C |
| `0x82` | `Shape{id, kind, points[], radius, height, color, fill, width, through_walls, label, dimension, ttl_ms}` | S -> C |
| `0x83` | `WorldRemove{kind, ids[]}` | S -> C |
| `0x84` | `EntityStyle{entity, glow, name, scale, rainbow, hide[], ttl_ms, hide_name}` | S -> C |
| `0x85` | `EntityStyleClear{entities[]}` | S -> C |
| `0x86` | `BorderStyle{color, hide_wall, reset}` | S -> C |
| `0x87` | `FireColor{entity, color, reset}` | S -> C |

## Players & teams

Capability `players:1`.

| Type | Message | Direction |
|---|---|---|
| `0x90` | `Nametag{player, above[], below[], prefix, suffix, badge, hide, badge_item}` | S -> C |
| `0x91` | `NametagClear{players[]}` | S -> C |
| `0x92` | `TabList{header[], footer[], entries[], hide_ping, replace, remove[], reset}` | S -> C |
| `0x93` | `Team{id, name, color, members[], markers, through_walls, health, compass}` | S -> C |
| `0x94` | `TeamRemove{ids[]}` | S -> C |
| `0x95` | `NickHint{nick, player}` | S -> C |

## Keybinds

Capability `keybind:1`.

| Type | Message | Direction |
|---|---|---|
| `0xA0` | `Keybinds{binds[], category}` | S -> C |
| `0xA1` | `KeyPress{id, pressed, held_ms}` | C -> S |

## Camera

Capability `camera:1`.

| Type | Message | Direction |
|---|---|---|
| `0xB0` | `CameraShake{intensity, duration_ms, frequency}` | S -> C |
| `0xB1` | `FovPunch{amount, duration_ms}` | S -> C |
| `0xB2` | `LookAt{x, y, z, entity, duration_ms, hold_ms}` | S -> C |
| `0xB3` | `Letterbox{on, size, fade_ms}` | S -> C |
| `0xB4` | `Cutscene{id, frames[], skippable, hide_hud, letterbox, loop, dimension}` | S -> C |
| `0xB5` | `CutsceneStop{id}` | S -> C |
| `0xB6` | `ScreenFade{color, in_ms, hold_ms, out_ms}` | S -> C |
| `0xB7` | `CutsceneEnded{id, skipped}` | C -> S |

## Audio

Capability `audio:1`.

| Type | Message | Direction |
|---|---|---|
| `0xC0` | `PlaySound{id, asset, sound, x, y, z, entity, positional, volume, pitch, loop, fade_in_ms, music}` | S -> C |
| `0xC1` | `StopSound{ids[], fade_out_ms}` | S -> C |

## Social

Capability `social:1`.

| Type | Message | Direction |
|---|---|---|
| `0xD0` | `Presence{game, map, state, started, party_size, party_max, joinable, clear}` | S -> C |
| `0xD1` | `InviteSheet{reason, party, address}` | S -> C |
| `0xD2` | `Transfer{host, port, token, title, reason}` | S -> C |
| `0xD3` | `ServerLinks{links[]}` | S -> C |

## Server UI

Capability `ui:1`.

| Type | Message | Direction |
|---|---|---|
| `0xE0` | `UiOpen{id, surface, title, nodes[], width, closeable, anchor}` | S -> C |
| `0xE1` | `UiPatch{id, nodes[], remove[], title}` | S -> C |
| `0xE2` | `UiClose{id}` | S -> C |
| `0xE3` | `UiEvent{id, node, action, value}` | C -> S |

## Client info

Capability `info:1`.

| Type | Message | Direction |
|---|---|---|
| `0xF0` | `InfoRequest{request_id, fields[], reason}` | S -> C |
| `0xF1` | `InfoReply{request_id, granted[], input, fps, frame_p50, frame_p99, render_distance, mods[], teho_modules[], locale, gui_scale, width, height, os, memory_mb}` | C -> S |

## Identity proof

Capability `assert:1`.

| Type | Message | Direction |
|---|---|---|
| `0x110` | `AssertRequest{request_id, nonce}` | S -> C |
| `0x111` | `AssertResult{request_id, token, error}` | C -> S |

## Integrity proof

Capability `attest:1`.

| Type | Message | Direction |
|---|---|---|
| `0x118` | `AttestRequest{request_id, nonce}` | S -> C |
| `0x119` | `AttestResult{request_id, token, error}` | C -> S |

## Resource packs

Capability `pack:1`.

| Type | Message | Direction |
|---|---|---|
| `0x120` | `PackHint{url, sha1, size, required, prompt, id}` | S -> C |
| `0x121` | `PackStatus{sha1, state, error}` | C -> S |

## Highlight clips

Capability `clips:1`.

| Type | Message | Direction |
|---|---|---|
| `0x130` | `ClipMark{id, title, before_ms, after_ms}` | S -> C |
| `0x131` | `ClipResult{id, saved, url, error}` | C -> S |

## Broadcast

Capability `broadcast:1`.

| Type | Message | Direction |
|---|---|---|
| `0x140` | `ObserverHud{on, title, subtitle, teams[]}` | S -> C |
| `0x141` | `CameraFollow{player, mode, distance, smooth}` | S -> C |

## Statues

Capability `statue:1`.

| Type | Message | Direction |
|---|---|---|
| `0x170` | `Statue{id, player, name, x, y, z, yaw, pose, scale, dimension, label, emote}` | S -> C |
| `0x171` | `StatueRemove{ids[]}` | S -> C |

## Branding

Capability `branding:1`.

| Type | Message | Direction |
|---|---|---|
| `0x180` | `Branding{accent, logo, banner, background, tagline, reset}` | S -> C |

## Showcase

Capability `showcase:1`.

| Type | Message | Direction |
|---|---|---|
| `0x190` | `ShowcaseOpen{title, items[], emote, focus, subtitle}` | S -> C |