actualize docs

lil-jon-crunk · lil-jon-crunk · commit a64a2ec61405 · 2026-04-27T06:50:36.000+03:00
diff --git a/content/en/3.server/3.server-properties.md b/content/en/3.server/3.server-properties.md
@@ -6,6 +6,8 @@ Main server config file: `config/ServerProperties.json`.
 
 ```json
 {
+  "TelemetryEnabled": true,
+  "TelemetryToken": "replace-with-stable-random-token",
   "VoiceCraftConfig": {
     "Language": "en-US",
     "Port": 9050,
@@ -21,8 +23,8 @@ Main server config file: `config/ServerProperties.json`.
     "MaxClients": 1,
     "MaxTimeoutMs": 10000,
     "DataTunnelCommand": "voicecraft:data_tunnel",
-    "CommandsPerTick": 5,
-    "MaxStringLengthPerCommand": 1000,
+    "CommandsPerTick": 3,
+    "MaxByteLengthPerCommand": 300,
     "DisabledPacketTypes": []
   },
   "McHttpConfig": {
@@ -51,6 +53,21 @@ Main server config file: `config/ServerProperties.json`.
 }
 ```
 
+## Telemetry
+
+- `TelemetryEnabled`:
+  enables anonymous startup, heartbeat, and crash diagnostics from `VoiceCraft.Server`.
+- `TelemetryToken`:
+  stable pseudonymous fingerprint used to group telemetry events from one server installation.
+
+If you do not want telemetry, set:
+
+```json
+{
+  "TelemetryEnabled": false
+}
+```
+
 ## VoiceCraftConfig
 
 - `Language`:
@@ -86,8 +103,8 @@ Used for websocket / command-tunnel Bedrock flows.
   command name used for the data tunnel, usually `voicecraft:data_tunnel`.
 - `CommandsPerTick`:
   how many command packets are forwarded per tick.
-- `MaxStringLengthPerCommand`:
-  payload budget per command invocation.
+- `MaxByteLengthPerCommand`:
+  payload budget (bytes) per command invocation.
 - `DisabledPacketTypes`:
   packet types blocked on this transport.
 
diff --git a/content/en/4.minecraft/2.mcwss-singleplayer.md b/content/en/4.minecraft/2.mcwss-singleplayer.md
@@ -35,8 +35,8 @@ Typical setup:
     "MaxClients": 1,
     "MaxTimeoutMs": 10000,
     "DataTunnelCommand": "voicecraft:data_tunnel",
-    "CommandsPerTick": 5,
-    "MaxStringLengthPerCommand": 1000,
+    "CommandsPerTick": 3,
+    "MaxByteLengthPerCommand": 300,
     "DisabledPacketTypes": []
   }
 }
@@ -88,12 +88,17 @@ This must stay aligned with `McWssConfig.DataTunnelCommand`.
 
 If you rename one side and not the other, the bridge breaks.
 
+The command currently carries:
+
+- optional max string length argument
+- packed payload data argument
+
 ## Tuning
 
 If you see lag or packet instability:
 
 - lower `CommandsPerTick`
-- review `MaxStringLengthPerCommand`
+- review `MaxByteLengthPerCommand`
 - avoid large burst updates
 - test with fewer active entities
 
diff --git a/content/en/5.operations/7.troubleshooting-matrix.md b/content/en/5.operations/7.troubleshooting-matrix.md
@@ -53,7 +53,7 @@ Check:
 Check:
 
 1. `CommandsPerTick`
-2. `MaxStringLengthPerCommand`
+2. `MaxByteLengthPerCommand`
 3. entity churn and packet burst size
 4. whether `McHttp` would be a better fit
 
diff --git a/content/en/6.ecosystem/4.voicecraft-addon.md b/content/en/6.ecosystem/4.voicecraft-addon.md
@@ -37,7 +37,7 @@ Across packages:
 
 - `voicecraft:vcconnect <token>`
   permission: `Host`
-- `voicecraft:data_tunnel [data]`
+- `voicecraft:data_tunnel [max_string_length] [data]`
   permission: `Host`
 
 ## What the Basic package gives you
@@ -87,7 +87,6 @@ Effects are sent through `McApiSetEffectRequestPacket`.
 
 ## Current limitations
 
-- `Kick` in the Basic player action menu is not implemented yet
 - `Core.McWss` stability depends on command and payload limits
 
 ## Recommended setup: BDS
diff --git a/content/ru/3.server/3.server-properties.md b/content/ru/3.server/3.server-properties.md
@@ -6,6 +6,8 @@
 
 ```json
 {
+  "TelemetryEnabled": true,
+  "TelemetryToken": "replace-with-stable-random-token",
   "VoiceCraftConfig": {
     "Language": "en-US",
     "Port": 9050,
@@ -21,8 +23,8 @@
     "MaxClients": 1,
     "MaxTimeoutMs": 10000,
     "DataTunnelCommand": "voicecraft:data_tunnel",
-    "CommandsPerTick": 5,
-    "MaxStringLengthPerCommand": 1000,
+    "CommandsPerTick": 3,
+    "MaxByteLengthPerCommand": 300,
     "DisabledPacketTypes": []
   },
   "McHttpConfig": {
@@ -51,16 +53,37 @@
 }
 ```
 
+## Телеметрия
+
+- `TelemetryEnabled`:
+  включает анонимные события запуска, heartbeat и crash-диагностику от `VoiceCraft.Server`.
+- `TelemetryToken`:
+  стабильный псевдонимный идентификатор, по которому группируются события с одной установки сервера.
+
+Если телеметрия не нужна:
+
+```json
+{
+  "TelemetryEnabled": false
+}
+```
+
 ## VoiceCraftConfig
 
-- `Language`
-- `Port`
-- `MaxClients`
-- `Motd`
-- `PositioningType`
+- `Language`:
+  язык логов сервера.
+- `Port`:
+  UDP-порт основного VoiceCraft-сервера.
+- `MaxClients`:
+  максимум подключений VoiceCraft-клиентов.
+- `Motd`:
+  текст для ping/info ответов.
+- `PositioningType`:
+  режим позиционирования:
   - `0 = Server`
   - `1 = Client`
-- `EnableVisibilityDisplay`
+- `EnableVisibilityDisplay`:
+  отправлять ли клиентам индикаторы видимости.
 
 ## McWssConfig
 
@@ -73,7 +96,7 @@
 - `MaxTimeoutMs`
 - `DataTunnelCommand`
 - `CommandsPerTick`
-- `MaxStringLengthPerCommand`
+- `MaxByteLengthPerCommand`
 - `DisabledPacketTypes`
 
 ## McHttpConfig
@@ -102,7 +125,7 @@
 Ключевые отличия от `McHttp` / `McWss`:
 
 - `Hostname` это обычный host, а не URI
-- `Port` задаётся отдельным полем
+- `Port` задается отдельным полем
 - именно этот transport важен для `GeyserVoice`
 
 ## DefaultAudioEffectsConfig
diff --git a/content/ru/4.minecraft/2.mcwss-singleplayer.md b/content/ru/4.minecraft/2.mcwss-singleplayer.md
@@ -1,26 +1,64 @@
 # McWss для одиночных миров
 
-`McWss` это websocket / command-tunnel transport, который в основном используется для локальных миров и лёгких Bedrock-сценариев.
+`McWss` это websocket / command-tunnel transport, который в основном используется для локальных миров и легких Bedrock-сценариев.
 
 ## Когда использовать
 
-- локальный Bedrock мир
-- singleplayer
-- тестирование addon logic
+Используйте `McWss`, если:
 
-## Ограничения
+- вы играете в локальном Bedrock-мире
+- нужен быстрый singleplayer setup
+- вы тестируете addon-логику без отдельного BDS
+
+## Важные ограничения
 
 - обычно менее стабилен, чем `McHttp`
 - сильно зависит от command throughput и размера payload
+- не является основным выбором для больших публичных прод-серверов
 
 ## Требования
 
 1. `VoiceCraft.Server` с `McWssConfig.Enabled = true`
 2. `VoiceCraft.Addon.Core.McWss.zip`
+3. Bedrock-версия с поддержкой нужной websocket / script-функциональности
+
+## Конфиг VoiceCraft сервера
+
+Типовой пример:
+
+```json
+{
+  "McWssConfig": {
+    "Enabled": true,
+    "LoginToken": "replace-with-token",
+    "Hostname": "ws://127.0.0.1:9051/",
+    "MaxClients": 1,
+    "MaxTimeoutMs": 10000,
+    "DataTunnelCommand": "voicecraft:data_tunnel",
+    "CommandsPerTick": 3,
+    "MaxByteLengthPerCommand": 300,
+    "DisabledPacketTypes": []
+  }
+}
+```
+
+## Установка
+
+### Вариант 1: импорт как `.mcaddon`
 
-## Подключение
+1. Переименуйте архив в `VoiceCraft.Addon.Core.McWss.mcaddon`.
+2. Откройте его, чтобы Minecraft импортировал addon.
+3. Включите behavior pack и resource pack в нужном мире.
 
-### Шаг 1: websocket connect
+### Вариант 2: ручное копирование
+
+1. Распакуйте архив.
+2. Скопируйте `RP` и `BP` в директории Bedrock.
+3. Включите оба пака в целевом мире.
+
+## Схема подключения
+
+### Шаг 1: подключить websocket мира
 
 ```text
 /connect <VOICECRAFT_HOST>:<MCWSS_PORT>
@@ -32,7 +70,7 @@
 /connect 127.0.0.1:9051
 ```
 
-### Шаг 2: авторизация аддона
+### Шаг 2: авторизовать addon
 
 ```text
 /voicecraft:vcconnect <LOGIN_TOKEN>
@@ -42,8 +80,32 @@
 
 ## Data tunnel
 
-Аддон использует:
+Addon использует:
 
 - `voicecraft:data_tunnel`
 
 Имя должно совпадать с `McWssConfig.DataTunnelCommand`.
+
+Если изменить только одну сторону, мост перестанет работать.
+
+Сейчас команда передает:
+
+- опциональный аргумент max string length
+- аргумент с упакованным payload
+
+## Тюнинг
+
+Если видите лаги или нестабильность пакетов:
+
+- снижайте `CommandsPerTick`
+- проверяйте `MaxByteLengthPerCommand`
+- избегайте больших burst-обновлений
+- тестируйте на меньшем числе активных сущностей
+
+## Когда лучше перейти на другой transport
+
+Переходите на `McHttp`, если:
+
+- вы используете реальный Bedrock Dedicated Server
+- нужна более чистая production-схема
+- command tunnel становится узким местом
diff --git a/content/ru/5.operations/7.troubleshooting-matrix.md b/content/ru/5.operations/7.troubleshooting-matrix.md
@@ -1,22 +1,68 @@
-# Troubleshooting matrix
+# Матрица проблем
 
-Используйте эту страницу, когда нужен symptom-based разбор, а не общий checklist.
+Используйте эту страницу для symptom-based диагностики, когда нужен быстрый путь от симптома к проверкам.
 
 ## Симптом: клиент подключается, но никто никого не слышит
 
 Проверьте:
 
 1. совпадает ли `PositioningType`
-2. завершён ли bind flow
+2. завершен ли bind flow
 3. получают ли сущности world и position updates
-4. не включён ли локальный mute / deafen
-5. не замьючен ли пользователь сервером
+4. не включен ли локальный mute/deafen у клиента
+5. не замьючен/оглушен ли клиент сервером
 
-## Симптом: GeyserVoice установлен, но bridge не работает
+## Симптом: addon подключается, но bind не работает
 
 Проверьте:
 
-1. включён ли `McTcp`
-2. совпадают ли `host`, `port`, `login-token`
-3. осознанно ли настроен direct или proxy mode
-4. если включён `auto-start`, успевает ли runtime стать ready
+1. корректен ли token
+2. создается ли ожидаемая сущность
+3. правильный ли binding key вводит игрок
+4. срабатывают ли bind script events
+
+## Симптом: GeyserVoice установлен, но Java-bridge не поднимается
+
+Проверьте:
+
+1. включен ли `McTcp` на VoiceCraft
+2. совпадают ли `host`, `port` и `login-token`
+3. осознанно ли выбран direct или proxy mode
+4. если включен `auto-start`, успевает ли runtime стать ready в timeout
+
+## Симптом: direct Paper mode работает после ручного реконнекта, но ломается на старте
+
+Проверьте:
+
+1. `config.voicecraft.auto-start`
+2. `install-directory`
+3. `ready-timeout-ms`
+4. кто владеет запуском runtime-процесса
+
+## Симптом: proxy mode работает на одном backend, но ломается при server switch
+
+Проверьте:
+
+1. proxy действительно является source of truth
+2. backend-ноды не пытаются сами владеть VoiceCraft-подключением
+3. snapshot forwarding не ломается на переключении
+4. world ID namespacing остается консистентным
+
+## Симптом: `McWss` нестабилен
+
+Проверьте:
+
+1. `CommandsPerTick`
+2. `MaxByteLengthPerCommand`
+3. объем entity churn и packet bursts
+4. не лучше ли перейти на `McHttp`
+
+## Симптом: VoiceCraft сервер стартует, но transport-клиент не может подключиться
+
+Проверьте:
+
+1. host binding
+2. открытый порт
+3. firewall
+4. выбран ли правильный transport
+5. не переписывают ли runtime overrides ожидаемые значения
diff --git a/content/ru/6.ecosystem/4.voicecraft-addon.md b/content/ru/6.ecosystem/4.voicecraft-addon.md
