.dev

Start here3 min read

Core concepts

Handshake, capabilities, consent tiers, remembered state and limits.

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.

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.

GetterWhat 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 unlocked for this player.
protocol(), clientVersion(), minecraftVersion(), platform()Fields from Hello, such as teho 0.4.2, 1.21.11, fabric.

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

TierCoversWhat the player controls
A · DecorateHUD, world visuals, notifications, sounds, camera effects, server UIOn by default. Can be turned off per server, and there is a quiet mode that drops notifications.
B · RestrictDisabling modules, capping settings, competitive mode, third-party mod policyAlways honoured on your server. The mods panel shows a banner and a lock on each affected mod, with your reason.
C · PrivilegedStaff tools granted to specific playersA one-time prompt per server, which the player can revoke at any time.
D · Share dataClient info, mod lists, screenshots, identity and integrity proofsAsked 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.

WhatLimit
Frame size32,000 bytes. Larger payloads are split into chunks automatically, up to 4 MB per stream and 8 open streams.
Strings1,024 bytes, or 8,192 for grants and certificates.
Notifications5 per 10 seconds, title 64 characters, body 256, shown for 1 to 15 seconds.
Waypoints64 per server.
Sidebar32 rows. Holograms 16 lines, shapes 1,024 points, cutscenes 256 frames, screens 400 nodes.
AssetsPNG 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.