From 5186c9b0e278458e23c047a7a50073348d818e15 Mon Sep 17 00:00:00 2001 From: SashegDev Date: Wed, 30 Sep 2026 12:53:09 +0000 Subject: [PATCH] docs: update README for the audio, display and persistence work The README still described decoupled sound range as planned and had no `/delta displaylead`, no mention of the config being writable, and a command list containing a `/delta reload` that does not exist. Also corrects two claims that no longer hold: - the Display tracking clamp is in org.spigotmc.TrackingRange, not ChunkMap.TrackedEntity. That was a deliberate choice: TrackingRange is git-tracked Paper source, so the decompiled Minecraft tree stays untouched. - the new Bukkit methods are default methods, so plugins referencing them keep working on stock Paper instead of failing with NoSuchMethodError. --- README.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 86 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index b9daeed63..9156b8e6d 100644 --- a/README.md +++ b/README.md @@ -28,24 +28,42 @@ Delta — **не форк с поломанным API**. Плагины видя Отличие только в отображении: `Brand-Name = Delta`, поэтому в F3 видно `server: Delta`. Это **единственное** пользовательское отличие. +Все новые классы лежат в `me.sashegdev.delta`. Методы Bukkit API, которых +Paper не хватает, добавлены как **default-методы** — так ничего не ломается +бинарно, и плагин, который на них ссылается, продолжает работать на стоковом +Paper через fallback. + ## Что добавлено ### `/delta` — инспекция и тюнинг + ``` /delta status текущие значения конфигурации /delta displayrange <блоки|0> дальность трекинга Display, 0 = стоковая -/delta reload перечитать конфиг +/delta displaylead <тики|0> предсказание позиции Display, 0 = стоковое +/delta clear сбросить Display-настройки к стоку +/delta help ``` -Периметр `delta.admin`. + +Периметр `delta.admin`. Всё, что меняется через `/delta`, **пишется в +`paper-global.yml`** и переживает рестарт. Paper не даёт публичного API для +записи глобального конфига, поэтому добавлен `saveGlobalSection()`: он пишет +только секцию `delta` и не трогает остальные узлы файла, так что сломать чужие +настройки невозможно. ### Бюджет Display-сущностей -В `ChunkMap.TrackedEntity#updatePlayer` добавлен кламп дальности трекинга для -`Display`. Display-сущности не имеют физики и коллизий, поэтому их отсечение по -дальности безопасно: клиент просто их не видит, серверное состояние остаётся -корректным. Это снимает основную нагрузку от способностей, спавнящих -десятки `BlockDisplay` с `viewRange=64`. -Отключено по умолчанию — включается в `paper-global.yml`: +Кламп дальности трекинга для `Display` живёт в +`org.spigotmc.TrackingRange#getEntityTrackingRange` — это git-отслеживаемый +исходник Paper, поэтому декомпилированный код Minecraft патчить не пришлось. + +Display-сущности не имеют физики и коллизий, поэтому их отсечение по дальности +безопасно: клиент просто их не видит, серверное состояние остаётся корректным. +Это снимает основную нагрузку от способностей, спавнящих десятки `BlockDisplay` +с `viewRange=64`. + +Отключено по умолчанию: + ```yaml delta: display-tracking-range-enabled: false @@ -55,11 +73,58 @@ delta: extended-particle-distance-enabled: false extended-particle-distance: 128.0 decoupled-sound-range-enabled: false + display: + predictive-lead-ticks: 3 + sound: + propagation-blocks-per-tick: 10.0 + decay-exponent: 4.0 + client-compensation: false + min-audible-gain: 0.004 ``` +### Звук: раздельные громкость и дальность + +В ванилле слышимая дальность выводится из громкости +(`SoundEvent#getRange = 16 * volume`). Единственный способ сделать звук +слышимым за 150 блоков — `volume=10`, и тогда всё клиппит в упор. Delta +разделывает эти параметры: + +```java +world.playSound(loc, sound, category, volume, pitch, range); +world.playSoundAttenuated(loc, sound, category, volume, pitch, range); +``` + +`playSoundAttenuated` отправляет **ровно один пакет на игрока**, отложенный до +тика прихода волны. Кадрового обновления громкости нет вообще — иначе при +десятке источников это N пакетов × M игроков каждый тик, то есть ровно тот +трафик, который здесь и убирается. + +Кривая нормализованная: `gain = volume * (1 - d/range)^exponent`. Ноль ровно на +`range`, поэтому параметр дистанции осмыслен. Физический `1/r` не годится: с +порогом слышимости он срезал бы всё дальше ~1000 блоков и `range` просто не +влиял бы на результат. Скорость волны — 10 блоков/тик, то есть 100 блоков за +0.5 с. + +### Плавность быстрых визуалов + +`DeltaDisplay` держит политику предсказывающей телепортации. Display двигается +пакетами позиции, и клиент интерполирует их у себя — на реальном пинге визуал +отстаёт и дёргается. Лечится не частыми пакетами (это ровно тот трафик, который +мы убираем), а сдвигом старта: визуал рождается сразу на N тиков вперёд по своей +же траектории, и `teleport_duration = N` говорит клиенту растянуть телепорт на +эти же N тиков. Клиент никогда не отстаёт, пакетов столько же. + +Диапазон 0–10 тиков. `teleport_duration` — уже стоковый Bukkit API, поэтому +Delta не добавляет плагинам новых методов: политика централизована, сдвиг +позиции делает сам плагин по траектории каждого визуала. + ### Баннер при старте -При запуске печатается блок с версией, коммитом, веткой, списком включённых -Delta-фич и предупреждением о статусе ядра. + +При запуске печатается блок с версией, коммитом, веткой, списком Delta-фич и +предупреждением о статусе ядра. Баннер выводится из статического инициализатора +`PaperBootstrap` **до** парсинга `paper-global.yml`, поэтому строки описывают +механизм, а фактические значения показывает `/delta status` — иначе баннер +печатал бы дефолты как будто это текущая конфигурация. ## Конфигурация сервера @@ -77,7 +142,10 @@ Delta-фич и предупреждением о статусе ядра. ./gradlew createMojmapPaperclipJar ``` -Артефакты: `paper-server/build/libs/paper-paperclip-*.jar` +Артефакт: `paper-server/build/libs/paper-paperclip-1.21.8-R0.1-SNAPSHOT-mojmap.jar` + +Имя `delta` в `fill { project("delta") }` влияет только на публикуемые в Maven +артефакты, локальный jar всегда остаётся `paper-*`. ## CI @@ -88,16 +156,19 @@ Gitea Actions, воркфлоу `.gitea/workflows/build.yml`. Раннер жи Node обязателен для `actions/checkout`, git identity — для `applyFeaturePatches`, который делает commit. +Воркфлоу делает обе фазы отдельными шагами: объединённый `createMojmapPaperclipJar` +падает на неявной зависимости. + ## Планируется -- Раздельные громкость и дальность звука (сейчас это один и тот же параметр — - чтобы было слышно за 150 блоков, приходится делать volume=10, и в упор всё - клиппит) - `force`/`alwaysShow` в публичном API частиц (сейчас недоступны плагинам) - Вынос симуляции «безопасных» чанков в worker-треды Moonrise — с чек-листом, исключающим BlockEntity и плагинные блоки, чтобы не сломать совместимость +- Калибровка `client-compensation` для затухающего звука: клиент сам гасит + позиционный звук, поэтому без компенсации итог тише расчётного. Формула + подгоняется по замеру, поэтому вынесена под отдельный тумблер ## Лицензия Код ядра наследует лицензию Paper ([GPLv3](LICENSE.md)). Все изменения в -`me.sashegdev.delta` — тоже GPLv3. \ No newline at end of file +`me.sashegdev.delta` — тоже GPLv3.