принято. вот обновлённое, сухое ТЗ для **HubMC Essentials** с учётом: **все кулдауны — только через HubGW**, без локального кеша; **/tp** ещё пишет историю телепортов.

# 1) Общие

* **MC/NeoForge:** 1.21.1 (Java 21)
* **ModID:** `hubmc_essentials`
* **Perms (LuckPerms):** `hubmc.cmd.*`, `hubmc.tier.(vip|premium|deluxe)`
* **HubGW:** `/api/v1`, заголовок `X-API-Key`, таймауты 2s/5s, 2 ретрая (429/5xx)

# 2) Кулдауны — только HubGW

* Проверка: `POST /cooldowns/check` (`player_uuid`, `cooldown_type`)
* Установка/пролонгация: `POST /cooldowns/` (`player_uuid`, `cooldown_type`, `cooldown_seconds` или `expires_at`)
* **Никаких локальных in-memory менеджеров.** При ошибке HubGW — **запретить действие** и показать пользователю короткое сообщение о недоступности.

## Нейминги `cooldown_type`

* `kit|<name>` — для наборов
* `rtp`, `back`, `tp|<target>` (или `tp|coords`)
* `heal`, `feed`, `repair`, `repair_all`, `near`, `clear`, `ec`, `hat`, `top`, `pot`, `time|day`, `time|night`, `time|morning`, `time|evening`

# 3) Команды

## Общие

* `/spec` `/spectator` — переключение spectator (локально). Perm: `hubmc.cmd.spec`
* `/sethome` — `PUT /homes/` (сохранить позицию). Perm: `hubmc.cmd.sethome`
* `/home` — `POST /homes/get` → TP. Perm: `hubmc.cmd.home`
* `/fly` — включить/выключить (локально). Perm: `hubmc.cmd.fly`
* `/vanish` — скрыть игрока (локально). Perm: `hubmc.cmd.vanish`
* `/invsee <nick>` — открыть инвентарь (локально, онлайн-игрок). Perm: `hubmc.cmd.invsee`
* `/enderchest <nick>` — открыть эндерсундук (локально, онлайн-игрок). Perm: `hubmc.cmd.enderchest`

### С кулдауном через HubGW:

* `/kit <name>` → **кулдаун** `kit|<name>` → при успехе выдать предметы → `POST /cooldowns/`. Perm: `hubmc.cmd.kit` + tier
* `/clear` → `cooldown_type="clear"`. Perm: `hubmc.cmd.clear`
* `/ec` → `cooldown_type="ec"`. Perm: `hubmc.cmd.ec`
* `/hat` → `cooldown_type="hat"`. Perm: `hubmc.cmd.hat`

## VIP

* `/heal` → `cooldown_type="heal"`. Perm: `hubmc.cmd.heal`
* `/feed` → `cooldown_type="feed"`. Perm: `hubmc.cmd.feed`
* `/repair` (в руке) → `cooldown_type="repair"`. Perm: `hubmc.cmd.repair`
* `/near` → `cooldown_type="near"`. Perm: `hubmc.cmd.near`
* `/back` → `cooldown_type="back"`. Perm: `hubmc.cmd.back`
* `/rtp` → `cooldown_type="rtp"`. Perm: `hubmc.cmd.rtp`
* `/kit vip` → `kit|vip`. Perm: `hubmc.cmd.kit` + `hubmc.tier.vip`

## Premium

* `/warp create` — `POST /warps/` (без кулдауна). Perm: `hubmc.cmd.warp.create`
* `/repair all` → `cooldown_type="repair_all"`. Perm: `hubmc.cmd.repair.all`
* `/workbench` — без кулдауна. Perm: `hubmc.cmd.workbench`
* `/kit premium`, `/kit storage` → `kit|premium` / `kit|storage`. Perm: `hubmc.cmd.kit` + `hubmc.tier.premium`

## Deluxe

* `/top` → `cooldown_type="top"`. Perm: `hubmc.cmd.top`
* `/pot` → `cooldown_type="pot"`. Perm: `hubmc.cmd.pot`
* `/day` `/night` `/morning` `/evening` → `cooldown_type="time|<preset>"`. Perm: `hubmc.cmd.time`
* `/weather clear|storm|thunder` — без кулдауна. Perm: `hubmc.cmd.weather`
* `/kit deluxe|create|storageplus` → `kit|deluxe` / `kit|create` / `kit|storageplus`. Perm: `hubmc.cmd.kit` + `hubmc.tier.deluxe`

## Переопределённая `/tp`

* Поддержка:

    * `/tp <player>`
    * `/tp <player1> <player2>` (требует `hubmc.cmd.tp.others`)
    * `/tp <x> <y> <z>` (требует `hubmc.cmd.tp.coords`)
* Права:

    * `hubmc.cmd.tp` — базовая
    * `hubmc.cmd.tp.others` — телепорт других
    * `hubmc.cmd.tp.coords` — по координатам
* Кулдаун HubGW:

    * к игроку: `cooldown_type="tp|<targetNick>"`
    * по координатам: `cooldown_type="tp|coords"`
    * проверка `POST /cooldowns/check` → при успехе выполнить TP → `POST /cooldowns/`
* **История TP (обязательно):** после успешной телепортации — `POST /teleport-history/`
  Поля: `player_uuid`, `from_world`, `from_x/y/z`, `to_world`, `to_x/y/z`, `tp_type` (one_of: `"to_player"|"to_player2"|"to_coords"`), `target_name` (ник цели, либо `"coords"`)

# 4) Ошибки/поведение

* Ошибка HubGW (401/5xx/timeout) на командах с кулдауном → **не выполнять действие**, сообщить: “Сервис недоступен, попробуйте позже”.
* 404 на `/homes/get` → “Дом не найден”.
* Сообщение при активном кулдауне: “Команда доступна через N сек.”

# 5) Permissions (итог)

```
hubmc.cmd.spec
hubmc.cmd.sethome
hubmc.cmd.home
hubmc.cmd.fly
hubmc.cmd.kit
hubmc.cmd.vanish
hubmc.cmd.invsee
hubmc.cmd.enderchest
hubmc.cmd.clear
hubmc.cmd.ec
hubmc.cmd.hat

hubmc.cmd.heal
hubmc.cmd.feed
hubmc.cmd.repair
hubmc.cmd.near
hubmc.cmd.back
hubmc.cmd.rtp

hubmc.cmd.warp.create
hubmc.cmd.repair.all
hubmc.cmd.workbench

hubmc.cmd.top
hubmc.cmd.pot
hubmc.cmd.time
hubmc.cmd.weather

hubmc.cmd.tp
hubmc.cmd.tp.others
hubmc.cmd.tp.coords

hubmc.tier.vip
hubmc.tier.premium
hubmc.tier.deluxe
```