# Velocity

Source: https://tehoclient.dev/install/velocity
SDK: 1.0.0

**Artifact:** `TehoAPI-Velocity.jar`
  
**Plugin id:** `tehoapi`
  
**Velocity:** 3.5+ and 4.x
  
**Java:** 21 or newer


The Velocity plugin makes the proxy the owner of the Teho session. Players handshake once with the network instead of once per backend, and your proxy can set network-wide state such as staff grants and rules.


**Do you need it?**

If every feature you use lives on the backends, you can skip the proxy plugin and put `TehoAPI.jar` on each backend only. Each backend then handshakes on its own when the player joins it. Install the Velocity plugin when you want one session across server switches or network-level features.


## Install

1. Download [`TehoAPI-Velocity.jar`](https://repo.tehoclient.dev/releases/dev/tehoclient/teho-api-velocity/1.0.0/teho-api-velocity-1.0.0-plugin.jar) and put it in the proxy's `plugins/` folder and start it once. It writes `plugins/tehoapi/config.yml`.
2. Put `TehoAPI.jar` on every Paper or Spigot backend.
3. Set the same secret on the proxy and on every backend. It must be at least 16 characters.

```yaml
server-name: "Skyline Network"

proxy:
  secret: "replace-with-a-long-random-string"
```

4. Make sure Velocity's modern player-info forwarding is on, so backend UUIDs match the proxy's.
5. Restart the proxy and the backends.

On startup the proxy logs `Teho Server API protocol … on teho:api (proxy), features […], signing backend handoffs`. The last part only appears once a secret is set.

## Proxy configuration

The proxy `config.yml` uses the same format as the backend one for these keys: `server-name`, `debug`, `features`, `welcome`, `staff.grants`, `staff.xray-blocks`, `rules.global`, `backend`, `verified`, `presence`, `links`, `resource-pack` and `combat`. Permissions for `staff.grants` come from your proxy permission plugin, for example LuckPerms on Velocity.

```yaml
staff:
  grants:
    - permission: tehoapi.staff.xray
      tools: [xray]
    - permission: tehoapi.staff.esp
      tools: [player_esp, nametags]
    - permission: tehoapi.staff.freecam
      tools: [freecam]

rules:
  global:
    disable: [hitbox]
```

## Use it from a Velocity plugin

```kotlin
repositories {
    maven("https://repo.tehoclient.dev/releases")
}

dependencies {
    compileOnly("dev.tehoclient:teho-api-velocity:1.0.0")
}
```

Then declare the dependency on the plugin id:

```java
@Plugin(id = "lobbycore", name = "LobbyCore", version = "1.0.0",
        dependencies = {@Dependency(id = "tehoapi")})
public final class LobbyCore {
    @Subscribe
    public void onReady(TehoPlayerReadyEvent event) {
        event.getTehoPlayer().notify(Notification.builder("network")
                .title("Welcome to Skyline")
                .body("Pick a mode in the compass")
                .accent(0x4DA9FF)
                .build());
    }
}
```

Velocity events live in `dev.tehoclient.api.velocity.event` and go through the `EventManager`, so subscribe with `@Subscribe`: `TehoPlayerReadyEvent`, `TehoConsentEvent`, `TehoStaffToolEvent` and `TehoClientEvent`. Each has `getPlayer()` and `getTehoPlayer()`.

To reach a player from elsewhere:

```java
VelocityTeho.player(player).ifPresent(teho -> teho.social().presence(
        Presence.builder("Skyline").state("In the lobby").startedNow().build()));
```

## Commands

`/tehoapi` works on the proxy with permission `tehoapi.admin` and the same subcommands as on backends. `waypoint` needs a world, so it only works on backends.

## Pick one layer per feature

Module rules and staff grants are full replaces on the client. If the proxy and a backend both set them, the last one wins. Let the proxy own network-wide staff tools and rules, and let backends own game features such as waypoints, HUD and notifications.

Read [Networks & proxies](https://tehoclient.dev/install/networks) for how the handoff works and what happens on a server switch.