# Core concepts

Source: https://tehoclient.dev/concepts
SDK: 1.0.0

## The handshake

Every Teho build, from 1.7.10 to 26.3, runs the same four steps when it enters the play state on your server:

1. The client registers the `teho:api` plugin channel.
2. It sends `Hello` with its protocol version, client version, Minecraft version, platform and the capabilities it can render.
3. The server answers with `Welcome`, listing the capabilities it will use and its `server-name`.
4. From then on the client accepts feature messages for those capabilities, and nothing else.

The SDK runs this for you. `TehoPlayerReadyEvent` (or `TehoListener.onReady`) fires after step 3.

If a player turned the API off for your server, the client registers nothing and sends nothing, so your server cannot tell they use Teho at all.


**A handshake is a claim, not proof**

Any client can send a `Hello` that says it is Teho. Use the handshake for UX only: never for anti-cheat, rewards or entitlement. When you need proof, request a signed identity or an attested build with [Verified clients](https://tehoclient.dev/modules/verify).


## Capabilities

Features are negotiated one by one. Each has an id with its own version, such as `hud:1` or `staff:1`, and a client only advertises an id once it can render it on that Minecraft version.

```java
TehoPlayer teho = TehoApi.get().player(uuid).orElseThrow();
if (teho.supports("ui:1")) {
    openShop(teho);
} else {
    openChestShop(player);
}
```

You rarely need that check. Every send returns a `boolean`, and returns `false` without sending anything if the player did not negotiate the capability, or if you switched it off under `features:` in `config.yml`.

| Getter | What it returns |
|---|---|
| `advertised()` | Every capability id the client sent in `Hello`. |
| `capabilities()` | The ids both sides agreed on in `Welcome`. |
| `supports(id)` | Whether one id is in `capabilities()`. |
| `privileges()` | Private capabilities your [private grant](https://tehoclient.dev/modules/private) unlocked for this player. |
| `protocol()`, `clientVersion()`, `minecraftVersion()`, `platform()` | Fields from `Hello`, such as `teho 0.4.2`, `1.21.11`, `fabric`. |

## Consent tiers

What a server may do without asking depends on what it touches.

| Tier | Covers | What the player controls |
|---|---|---|
| **A · Decorate** | HUD, world visuals, notifications, sounds, camera effects, server UI | On by default. Can be turned off per server, and there is a quiet mode that drops notifications. |
| **B · Restrict** | Disabling modules, capping settings, competitive mode, third-party mod policy | Always honoured on your server. The mods panel shows a banner and a lock on each affected mod, with your reason. |
| **C · Privileged** | Staff tools granted to specific players | A one-time prompt per server, which the player can revoke at any time. |
| **D · Share data** | Client info, mod lists, screenshots, identity and integrity proofs | Asked per server, field by field. Declined fields are simply missing from the reply. |

Every module page shows its tier next to its capability id.

## State is remembered for you

Waypoints, module rules, staff grants, cooldowns, timers and other state you set are stored per player in the SDK. If the client re-handshakes, for example after a proxy server switch, the SDK sends it all again so you do not have to track it.

The client keeps nothing. It clears everything your server applied on disconnect and on every new `Welcome`, and you can clear it yourself at any point:

```java
teho.reset();
```

## Limits the client enforces

These are hard caps on the client side. A frame that breaks one is dropped and logged once per session.

| What | Limit |
|---|---|
| Frame size | 32,000 bytes. Larger payloads are split into chunks automatically, up to 4 MB per stream and 8 open streams. |
| Strings | 1,024 bytes, or 8,192 for grants and certificates. |
| Notifications | 5 per 10 seconds, title 64 characters, body 256, shown for 1 to 15 seconds. |
| Waypoints | 64 per server. |
| Sidebar | 32 rows. Holograms 16 lines, shapes 1,024 points, cutscenes 256 frames, screens 400 nodes. |
| Assets | PNG and OBJ up to 2 MB, OGG up to 4 MB, 64 MB cached per server. |

## What players always see

- Everything you send is labelled with your `server-name` and disappears when they leave.
- Server waypoints are badged, hideable and never saved. Rules show as "Disabled by <server>" and never touch the player's own settings.
- Links open behind vanilla's confirmation screen. No message runs commands or code on the client.
- In Settings -> Servers, each server can be set to **On**, **Notifications off** or **Off**.