ShapeBoard

Прочитайте это на Español. Табло для зон ЛЮБОЙ формы, а не только прямоугольных. Обведите зону копания, периметр или стройплощадку линией из маркерных блоков в небе, выполните одну команду — и ShapeBoard будет отслеживать каждый сломанный и поставленный блок внутри этой самой формы. Когда кто-то заходит внутрь, у него появляется боковая панель с таблицей лидеров. Когда выходит — исчезает. 100% серверная часть. Игрокам ничего устанавливать не нужно.

Посмотрите в действии

Полное видео со звуком: shapeboard-demo.mp4

Зачем

Инструменты вроде buildevents умеют отслеживать только прямоугольные области. Реальные проекты не прямоугольники: у периметров скруглённые углы, реки, которые хочется пропустить, странные выступы. Если отслеживать прямоугольник вокруг круглого периметра, люди, копающие за пределами реального проекта, всё равно попадут в ваш список лидеров. ShapeBoard следует точно по нарисованному контуру, так что подсчёт честный. Боковая панель также действительно индивидуальна для каждого игрока. Она отправляется адресными пакетами табло, поэтому её видят только те, кто стоит внутри формы. Команды не затрагиваются, цвета команд не меняются, и два игрока, случайно имеющие один цвет команды, не увидят табло друг друга. Всё, для чего ваш сервер использует команды и цвета, остаётся нетронутым.

Установка

1. Сервер Fabric с Fabric API, на любой версии Minecraft от 1.21 до 26.3.
2. Положите jar для вашей версии Minecraft в mods/ (в таблице ниже указано, какой именно).
3. Перезапустите. Готово: файла конфигурации для редактирования нет.

Какой jar

Для каждой версии свой jar, скомпилированный под эту версию. Имя всегда заканчивается версией Minecraft, для которой он предназначен.

Minecraft 26.1 и выше требуют Java 25: это требование игры, а не мода. Jar для одной версии откажется загружаться на другой, а не будет работать наполовину. Minecraft 26.3 требует Fabric Loader 0.19.5 или новее и Fabric API для 26.3.

Обновление существующего мира

Остановите сервер корректно и сделайте резервную копию мира. Замените старый jar ShapeBoard на jar для целевой версии Minecraft, обновите Fabric Loader и Fabric API при необходимости, затем снова запустите сервер. Держите в mods/ только один jar ShapeBoard. Существующие формы и итоги сохраняются, если вы оставляете тот же мир. Определения форм, снимки сканирования, базовые значения и настройки игроков хранятся в world/shapeboard/; индивидуальные счёты по сломанным и поставленным блокам — в ванильных данных табло мира. Сохраняйте и то, и другое при копировании мира. Формы не нужно создавать заново или сканировать повторно, чтобы возобновить подсчёт. Если level-name изменён, используйте этот каталог мира вместо world/.

Быстрый старт

Допустим, TVTvirus — админ и хочет отслеживать копание периметра на своём сервере:

1. Нарисуйте контур. Пролетите на высоте Y над постройкой (например, y150) и нарисуйте одну непрерывную линию из маркерного блока (например, чёрного бетона), повторяя форму проекта, пока она не замкнётся сама на себя. Подойдёт любая форма: круги, кляксы, дырки от бублика, срезанные углы. Небольшие разрывы до 6 блоков соединяются автоматически; из-за больших разрывов сканирование не удастся, и оно сообщит точные координаты открытых концов, чтобы вы могли их залатать.

2. Создайте форму. Встаньте в любом месте в пределах 64 блоков от линии (или передайте точные координаты из консоли) и выполните:

   /shapeboard create bigculo minecraft:black_concrete 150

   ShapeBoard пройдёт всю линию, замкнёт форму и сообщит площадь:

   [ShapeBoard] Shape 'bigculo' created in 45 ms: 797,680 columns inside,
   outline of 4,350 blocks. Objectives: bigculo_break / bigculo_place.

   Нужен просто прямоугольник? Пропустите рисование: задайте два противоположных угла и высоту потолка Y:

   /shapeboard createbox spawnzone 30640 4768 31631 6079 150

3. Дайте ей красивое имя. Именно его увидят игроки на боковой панели:

   /shapeboard rename bigculo Big Culo

4. Выберите, по чему ранжирует таблица лидеров. Этот шаг часто пропускают: боковая панель ранжирует по сломанным блокам, если не указано иное. И сломанные, и поставленные блоки всегда считаются, но таблицу ведёт только один из них.

   /shapeboard metric bigculo break    # копание (по умолчанию)
   /shapeboard metric bigculo place    # строительство и украшение
   /shapeboard metric bigculo both     # сумма

   Строите проект, а не копаете? Выполните строку с place, иначе таблица будет стоять на нуле, пока все работают. Сначала копаете, а строите потом? Оставьте metric на break для фазы копания, переключите на place в день начала строительства. Оба счётчика работали всё это время, так что ничего не потеряно, и любой может в любой момент посмотреть другой через /shapeboard view (см. Две таблицы, одна зона).

5. Вот и всё. С этого момента всё, что добыто или поставлено внутри формы и ниже линии маркеров, засчитывается в ванильные цели табло bigculo_break и bigculo_place. Любой, кто заходит внутрь, получает:

[ShapeBoard] Вы вошли в Big Culo. Блоки, которые вы здесь сломаете или поставите, идут в таблицу лидеров. [ShapeBoard] Введите /shapeboard hide, чтобы скрыть боковую панель, /shapeboard quiet — чтобы отключить эти сообщения.

Эти две строки показываются один раз, а не при каждом входе: та же зона молчит ещё 15 минут после этого, а `/shapeboard quiet` отключает их навсегда.
с живой боковой панелью топ-15. Если игрока нет в топ-15, но у него есть счёт, его собственная строка показывается в последнем слоте, чтобы он всегда видел своё место.
## Команды
| Команда | Кто | Что делает |
|---|---|---|
| `/shapeboard create <id> <block> <y> [x z]` | OP | Сканирует линию-маркер и создаёт фигуру. `x z` — необязательная начальная точка (обязательна из консоли) |
| `/shapeboard createbox <id> <x1> <z1> <x2> <z2> <y>` | OP | Прямоугольная зона вообще без отрисовки: два противоположных угла + Y потолка (считаются только блоки ниже него) |
| `/shapeboard rename <id> <name...>` | OP | Задать отображаемое имя, показываемое на боковой панели |
| `/shapeboard metric <id> <break\|place\|both>` | OP | По чему ранжирует таблица лидеров: сломанные блоки (по умолчанию), поставленные или их сумма. Идеально для зон строительства/украшения |
| `/shapeboard total <id> <on\|off>` | OP | Показывать строку **Total** вверху боковой панели с общим счётом всех (включено по умолчанию) |
| `/shapeboard delete <id>` | OP | Удалить фигуру (цели скорборда сохраняются) |
| `/shapeboard list` | все | Список фигур с площадью и информацией о маркере |
| `/shapeboard info <id>` | все | Подробности одной фигуры |
| `/shapeboard top [id]` | все | Топ-10 + итоги в чате |
| `/shapeboard hide` / `show` | все | Переключение боковой панели для игрока, запоминается между сессиями |
| `/shapeboard view <break\|place\|both\|reset>` | все | По чему ранжирует **ваша** боковая панель, независимо от настроек зоны. `reset` снова следует за зоной |
| `/shapeboard quiet [on\|off]` | все | Отключить сообщения о входе/выходе в чате. Боковая панель продолжает работать. Без аргумента переключает |
| `/shapeboard suffix <id> <word\|auto\|off>` | OP | Слово после отображаемого имени в заголовке боковой панели. `auto` превращается в Dig / Build / Both в зависимости от того, по чему идёт ранжирование |
| `/shapeboard prefix <id> <word\|off>` | OP | Слово перед отображаемым именем |
| `/shapeboard contains <id> <x> <z>` | OP | Отладка: входит ли этот столбец в фигуру? |
| `/shapeboard scan <id>` | OP | Посчитать блоки, ещё стоящие внутри фигуры (см. [Прогресс копания](#dig-progress)) |
| `/shapeboard progress [id]` | все | Полоса прогресса и оставшееся число блоков по последнему сканированию |
| `/shapeboard layer [y] [id]` | все | Один слой Y, измеренный относительно того, с чего этот слой начинался |
| `/shapeboard down <y> [id]` | все | Всё, что ещё стоит от верха сканирования вниз до этого Y: сколько осталось, пока фигура не будет расчищена до y |
| `/shapeboard blocks [id]` | все | Все типы блоков, ещё стоящие, начиная с самых частых (то, что вы будете вывозить) |
| `/shapeboard range <id> <ymin> <ymax>` | OP | Срез по Y, который охватывает сканирование (по умолчанию: выше слоя бедрока, вплоть до Y маркера) |
| `/shapeboard baseline <id> <blocks>\|fromscan` | OP | Сколько блоков было до начала копания. `fromscan` замораживает последнее сканирование, `0` = использовать чистый объём |
| `/shapeboard untracked <id> <name>` | OP | Записать копания, за которые никому не засчитали (копания до создания фигуры, взрывы, правки мира), под фейковым именем, синхронизируется после каждого сканирования. `off` убирает это |
## Две таблицы, одна зона
Зоне, которую сначала выкапывают, а потом застраивают, нужны две таблицы лидеров
в одном месте. Они уже есть: **разрушения и установки всегда считаются в
две отдельные цели**, `<id>_break` и `<id>_place`. `metric` лишь выбирает,
какую из них показывает боковая панель, так что ничего не нужно дублировать и
не нужно создавать вторую фигуру (перекрывающиеся фигуры всё равно не сработали бы:
столбец принадлежит первой фигуре, которая его содержит).

/shapeboard metric virusia break # фаза копания, все видят разрушения /shapeboard metric virusia place # день строительства, одна команда, та же зона

/shapeboard view place # любой игрок, в любое время, только для него /shapeboard view reset # обратно к тому, что показывает зона

`view` задаётся для каждого игрока и запоминается между сессиями, так что строитель может
следить за установками, пока копатели видят свою таблицу. Чтобы было очевидно, на какую
из них вы смотрите, задайте фигуре авто-суффикс:

/shapeboard rename virusia Virusia /shapeboard suffix virusia auto

Тогда заголовок боковой панели будет читаться как **Virusia Dig**, **Virusia Build** или **Virusia
Both**, в зависимости от того, по чему ранжирует этот зритель. Фиксированное слово тоже подойдёт
(`/shapeboard suffix virusia Build`), а `/shapeboard prefix` ставит слово перед именем.
## Прогресс копания
Счётчики разрушений отвечают на вопрос «кто накопал больше всех». Они не могут ответить «сколько осталось»,
потому что TNT и правки мира никому не засчитываются. `/shapeboard scan` отвечает
на это напрямую: он считает блоки, **ещё стоящие** внутри фигуры.

/shapeboard scan bigculo /shapeboard progress bigculo

— Прогресс Big Culo — ████████░░░░░░░░░░░░ 41.74% Прогресс: 280,374 / 671,744 блоков расчищено, 391,370 осталось Осталось выкопать: deepslate 202,334, stone 115,216, tuff 15,297, diorite 12,677

Блок считается «ещё не выкопанным», если он твёрдый, имеет коллизию и разрушаемый.
Воздух, вода, лава, листва, трава и прочий декор, а также бедрок пропускаются,
так что полоса достигает 100%, когда яма действительно закончена.
**Знаменатель.** По умолчанию это чистый объём среза по Y
(столбцы x высота). Это точно и не требует настройки, но природные пещеры и
воздух над рельефом считаются «уже выкопанными», поэтому полоса начинается выше нуля. Для
точного показателя измерьте, сколько блоков было там до начала, и задайте его:

/shapeboard baseline bigculo 148300000

Это число можно получить, просканировав ту же область на копии мира
до копания или на свежесгенерированном мире с тем же сидом.
**Чтобы таблица сходилась.** Счётчики по игрокам видят только то, что игроки

засчитывается. Блоки, выкопанные до появления фигуры, взрывы и правки мира
для них невидимы, поэтому сумма в таблице лидеров может быть заметно ниже того, что
намерило сканирование. Привяжите фальшивое имя к разнице — и она перестанет теряться:

/shapeboard untracked bigculo Untracked

Значение пересчитывается после каждого сканирования, так что таблица всегда сходится
с реальной ямой. `/shapeboard untracked <id> off` убирает его.
**Копка до целевого Y.** По слоям — `/shapeboard layer`, а всё, что выше заданной
глубины, сразу — `/shapeboard down`. Он суммирует все блоки, ещё стоящие от верха
сканирования вниз до этого Y, — а это как раз тот вопрос, который реально задают
команды («сколько осталось до y-20?»):

/shapeboard down -20 bigculo

— Big Culo · down to y-20 — ███████░░░░░░░░░░░░░ 38.60% Down to y-20: 210,455 / 545,180 blocks cleared, 334,725 remaining Layers: 43 of 96 cleared from y99 down to y-20, highest one left is y41.

Оба читают данные последнего сканирования, так что отвечают мгновенно и ничего не стоят.
**Стоимость.** Сканирование выполняется в рабочем потоке и читает данные чанков прямо
из хранилища, поэтому сервер продолжает тикать. Зона в 4 096 колонок занимает ~50 мс;
периметр в 800 000 колонок — несколько секунд. Перед этим мир сохраняется, так что
свежевыкопанные чанки всегда попадают в скан. Запускайте его из cron (раз в час или
раз в день), и `/shapeboard progress` будет отвечать мгновенно из сохранённого снимка.
## Как это работает
- **Сканирование:** начиная с блока-семени, ShapeBoard идёт по связанной линии
  маркерных блоков на этом самом Y (загружая только те чанки, через которые проходит
  линия), автоматически перекрывает разрывы до 6 блоков, затем запускает заливку
  снаружи. Всё, до чего заливка не добралась, находится внутри. Диагональная линия
  корректно блокирует заливку, так что контуры с углами в 45 градусов подходят.
- **Маска:** результат хранится как z-интервалы по каждому столбцу x в
  `world/shapeboard/shapes.json`. Проверка — это пара сравнений целых чисел, так что
  отслеживание ничего не стоит даже при десятках копающих игроков.
- **Подсчёт:** разрушения блоков считаются через событие break в Fabric, установка
  блоков — через крошечный миксин. Учитываются только столбцы внутри фигуры и ниже
  маркерного Y. Очки идут в обычные ванильные цели скорборда, так что всё остальное
  на вашем сервере (команды, датапаки, другие моды) может их читать.
- **Боковая панель:** каждый зритель получает клиентскую фальшивую цель через
  адресные пакеты (`shapeboard_view`), обновляемую только при изменении чисел. При
  выходе из зоны она убирается и восстанавливает ту цель боковой панели, которую
  показывал сервер. Имена игроков на таблице сохраняют цвета своих команд.
## FAQ
**Нужно ли что-то на клиенте?** Нет. Ванильные игроки видят всё.
**А как же TNT?** Блоки, разрушенные взрывами, никому не засчитываются (игра не
приписывает их игроку). Ручная копка и инструменты считаются как обычно.
**Считаются ли ковровые боты?** Их разрушения и установки считаются под именем
самого бота, так что копка с кучей ботов всё равно показывает, кто что сделал. Боты
никогда не получают боковые панели или сообщения в чате.
**Несколько фигур?** Да, создавайте сколько угодно. Игрок, стоящий внутри одной из
них, видит таблицу этой фигуры.
**А если в моём контуре дырка?** Сканирование не удастся и выведет координаты
открытых концов линии. Заделайте их (или оставьте до 6 блоков — они перекрываются
автоматически) и запустите create заново.
**Можно ли отслеживать зону постройки или декора без контура?** Да, двумя способами.
Если хватит прямоугольника, `/shapeboard createbox <id> <x1> <z1> <x2> <z2> <y>`
вообще не требует блоков. Для произвольной фигуры маркерная линия нужна только во
время сканирования: начертите временный контур любым дешёвым блоком на Y выше
постройки, запустите create, затем уберите блоки; фигура продолжит работать вечно
(маска хранится в `world/shapeboard/`). В любом случае задайте
`/shapeboard metric <id> place`, чтобы таблица лидеров ранжировала по
установленным блокам, а не по выкопанным (или `both` для суммы).
**Можно ли отслеживать зону, где уже копали?** Цели начинаются с нуля при создании
фигуры. Если у вас есть прежние числа в другой цели, скопируйте их туда через
`/scoreboard players operation`.
**Лагает ли сканирование сервер?** Оно загружает только те чанки, которых касается
сам контур, один раз, во время создания. Контур в 4 000 блоков занимает заметно
меньше секунды на загруженном мире.
## Сборка из исходников

./gradlew build

Jar-файл появится в `build/libs/`. Java 21+, всё остальное Gradle скачает сам. Так
собирается для 1.21 — версии, под которую написан исходный код.
Для любой другой версии Minecraft:

python3 tools/multiversion.py # все версии, в build/multiversion/ python3 tools/multiversion.py 26.2 # только одну python3 tools/multiversion.py 26.2 --errors # только компиляция, список всех ошибок

Одно дерево исходников, без ветки на каждую версию: различия между релизами
Minecraft — это переименования, и они лежат в таблице подстановок в начале
`tools/multiversion.py`. Серии 26 также нужен собственный тулчейн, поскольку
Minecraft перестал поставляться обфусцированным в 26.1 и маппингов больше не
существует, а тот скрипт сборки произведён от этого, а не лежит рядом с ним. Для
локальной сборки jar-файлов 26 нужен JDK 25 в дополнение к 21.
## Лицензия
MIT