From d0f5c906221d87b178fa985604bc2f0d680de5b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=98=D0=9D?= Date: Thu, 28 May 2026 00:58:50 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=82=D1=83=D1=82=D0=BE=D1=80=D0=B8?= =?UTF-8?q?=D0=B0=D0=BB=D1=8B=20first-PR=20+=20debug=20Babylon=20+=20Code?= =?UTF-8?q?=20of=20Conduct?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CODE_OF_CONDUCT.md | 43 +++++++++++ docs/TUTORIAL_DEBUG_BABYLON.md | 128 +++++++++++++++++++++++++++++++++ docs/TUTORIAL_FIRST_PR.md | 117 ++++++++++++++++++++++++++++++ 3 files changed, 288 insertions(+) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 docs/TUTORIAL_DEBUG_BABYLON.md create mode 100644 docs/TUTORIAL_FIRST_PR.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..aa806c2 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,43 @@ +# Кодекс поведения сообщества + +Мы строим инклюзивное и уважительное сообщество разработчиков. Этот документ описывает наши ожидания. + +## Наша позиция + +Как контрибьюторы, мейнтейнеры и участники сообщества проекта Рублокса, мы обязуемся сделать участие в нашем сообществе свободным от харрасмента опытом для всех — независимо от возраста, размера тела, физических особенностей, пола, гендерной идентичности и самовыражения, опыта, образования, социально-экономического статуса, национальности, внешности, расы, религии или сексуальной идентичности. + +## Наши стандарты + +Примеры поведения которое **способствует** позитивной среде: + +- Доброжелательность и уважение к мнению других +- Конструктивная критика по существу, а не по личности +- Готовность помочь новичкам разобраться +- Признание чужих ошибок как нормальной части процесса +- Концентрация на том что лучше для сообщества + +Примеры **неприемлемого** поведения: + +- Использование сексуализированных образов или речи +- Тролллинг, провокации, оскорбления, личные или политические атаки +- Публичный или приватный харрасмент +- Публикация чужих приватных данных (адреса, телефоны) без явного разрешения +- Любое поведение которое разумно считается неуместным в профессиональной среде + +## Ответственность мейнтейнеров + +Мейнтейнеры проекта (МИН) отвечают за разъяснение стандартов поведения и принятие соразмерных мер при нарушениях. + +Мейнтейнеры имеют право и обязанность удалять, редактировать или отклонять комментарии, коммиты, код, правки вики, issues и другие вклады, которые не соответствуют этому Кодексу, а также временно или постоянно банить любого участника за поведение, которое они считают неуместным, угрожающим, оскорбительным или вредным. + +## Применимость + +Этот Кодекс применяется как в пределах проекта (репозитории, чаты, issues, PR), так и в публичных пространствах когда участник представляет проект или сообщество (например на конференциях, в соцсетях с указанием принадлежности к проекту). + +## Принуждение к исполнению + +Случаи оскорбительного, харрасментного или иного неприемлемого поведения можно сообщить мейнтейнерам по адресу **`maksimivankov26@yandex.ru`**. Все жалобы будут рассмотрены и расследованы, и приведут к ответу который сочтён необходимым и соответствующим обстоятельствам. Мейнтейнеры обязаны сохранять конфиденциальность относительно репортёра инцидента. + +## Атрибуция + +Этот Кодекс адаптирован из [Contributor Covenant](https://www.contributor-covenant.org/), версия 2.1, доступного по адресу https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. diff --git a/docs/TUTORIAL_DEBUG_BABYLON.md b/docs/TUTORIAL_DEBUG_BABYLON.md new file mode 100644 index 0000000..89fb899 --- /dev/null +++ b/docs/TUTORIAL_DEBUG_BABYLON.md @@ -0,0 +1,128 @@ +# Туториал: отладка Babylon-сцены + +Полезные приёмы когда «что-то не рендерится» или «тормозит». + +## 1. Inspector (визуальный debug) + +В Console браузера: +```js +window.__scene.debugLayer.show({ embedMode: true }); +``` + +Откроется панель Babylon Inspector справа: +- **Scene** — список всех мешей, лампочек, материалов +- **Stats** — FPS, число draw calls, мегабайты в VRAM +- **Performance** — graph загрузки CPU/GPU + +Чтобы скрыть: `__scene.debugLayer.hide()`. + +## 2. Подсветить меш + +В Inspector кликни по мешу — он подсветится зелёным wireframe-ом на сцене. Видно где он, какого размера, не «улетел ли в космос». + +В коде: +```js +const mesh = scene.getMeshByName('Cube1'); +mesh.showBoundingBox = true; // покажет AABB +mesh.material.wireframe = true; // рендер каркасом +``` + +## 3. Логи FPS / draw calls + +```js +scene.onAfterRenderObservable.add(() => { + if (scene.getEngine().performanceMonitor.averageFPS < 30) { + console.warn('FPS dropped:', { + fps: scene.getEngine().performanceMonitor.averageFPS, + drawCalls: scene.getEngine().drawCalls, + activeMeshes: scene.getActiveMeshes().length, + }); + } +}); +``` + +## 4. Профайлинг кадра + +В Chrome DevTools → Performance → Record (10 сек игры). Смотри: +- **Scripting** > 10мс — твой JS тормозит. Гляни Bottom-Up — самые тяжёлые функции. +- **Rendering** > 5мс — GPU не справляется. Уменьши число мешей или текстур. +- **Painting** — обычно мало в WebGL. + +## 5. Babylon Spector.js + +Глубокая отладка одного кадра WebGL. Установи расширение [Spector.js](https://spector.babylonjs.com/). Кнопка «Capture frame» → видишь каждый draw call, каждую текстуру, каждый shader. + +Полезно когда: +- Странные артефакты (одна модель «мерцает») +- Текстура не накладывается (видишь pink/purple) +- Не понятно почему столько draw calls + +## 6. Прозрачные / невидимые меши + +Часто меш «есть, но не видно». Чек-лист: +```js +const m = scene.getMeshByName('Foo'); +console.log({ + isEnabled: m.isEnabled(), + isVisible: m.isVisible, + visibility: m.visibility, // 0 = прозрачный, 1 = непрозрачный + position: m.position, + scaling: m.scaling, // не 0? + material: !!m.material, + hasTexture: !!(m.material && m.material.diffuseTexture), + textureLoaded: m.material?.diffuseTexture?.isReady(), +}); +``` + +## 7. Утечки памяти + +Каждый `scene.createMesh` без последующего `mesh.dispose()` — утечка. Проверь через Inspector → Statistics → Allocated GPU memory растёт со временем = течь. + +Типичные источники: +- GLB загружен через `SceneLoader.ImportMesh` без `AssetContainer` — материалы и текстуры не освобождаются. +- `setInterval` создающий новые меши и не убирающий старые. +- Listener'ы `onClick/onPointer` накапливаются, держат refs. + +## 8. Console команды для быстрой отладки + +```js +// Сколько мешей сейчас на сцене +__scene.meshes.length + +// Топ-10 по числу вершин +__scene.meshes.slice().sort((a,b)=> b.getTotalVertices() - a.getTotalVertices()).slice(0,10).map(m=>[m.name, m.getTotalVertices()]) + +// Удалить все debug-marker'ы +__scene.meshes.filter(m=>m.name.startsWith('__debug_')).forEach(m=>m.dispose()) + +// Заморозить материалы (не пересчитывать uniforms каждый кадр) +__scene.materials.forEach(m=>m.freeze()) +// ! не делать если материалы меняются в runtime — иначе зависнут на текущем значении + +// FPS-overlay на сцене +new BABYLON.FreeCamera('debug', new BABYLON.Vector3(0,5,-10), __scene); +``` + +## 9. Что не делать (часто ломает FPS) + +- `scene.render()` руками — Babylon сам в RAF +- `blockMaterialDirtyMechanism = true` — лагает новые меши (debris, эффекты) +- `createOrUpdateSelectionOctree()` каждый кадр — пересчёт O(N²) +- `mesh.getBoundingInfo()` в hot path — есть кеш `mesh._boundingInfo` +- `setInterval(... , 16)` — используй `scene.registerBeforeRender(fn)` (тогда привязано к рендер-циклу Babylon) + +## 10. Мобильная отладка + +Открой Chrome на десктопе → DevTools → ⋮ → More tools → Remote devices. Подключи Android через USB, открой плеер на нём — твой DevTools покажет console/network/dom мобильной вкладки. + +iOS аналогично через Safari → Develop → . + +## Что почитать + +- https://doc.babylonjs.com/features/featuresDeepDive/inspector +- https://spector.babylonjs.com/ +- [reference_kubikon_scripting_api.md](../../disaster-recovery/...) — приватный референс API для скриптов + +## Вопросы + +В канал `#разработка` на https://team.rublox.pro. diff --git a/docs/TUTORIAL_FIRST_PR.md b/docs/TUTORIAL_FIRST_PR.md new file mode 100644 index 0000000..4fcdc28 --- /dev/null +++ b/docs/TUTORIAL_FIRST_PR.md @@ -0,0 +1,117 @@ +# Туториал: твой первый Pull Request за 30 минут + +Гайд для нового контрибьютора плеера Рублокса. Закончив, у тебя будет смерженный PR и зачисленные баллы разработчика. + +## Что нужно перед началом + +1. **Аккаунт в Gitea**: войди в https://team.rublox.pro и кликни «Войти через team» в Gitea (https://git.rublox.pro). OAuth создаст тебе профиль с ник = твой `firstName` из team. +2. **Роль `developer`**: попроси Лида выдать через https://team.rublox.pro/developer (или через API `POST /api-team/developer/grant/<твой-uid>`). +3. **CLA подписан**: открой https://team.rublox.pro/developer, вкладка «CLA», кнопка «Я согласен, подписать». +4. **SSH-ключ в Gitea**: вкладка «SSH-ключи». Если ключа нет — создай: `ssh-keygen -t ed25519 -C "твой-email"` и скопируй содержимое `~/.ssh/id_ed25519.pub`. +5. **Node.js 18+**: `node --version` должно показать `v18.x` или выше. + +## Шаг 1: Клонируй репо (2 минуты) + +```bash +git clone ssh://git@git.rublox.pro:2222/rublox/player.git +cd player +``` + +Если ssh не работает (нет ключа в Gitea) — используй HTTPS: +```bash +git clone https://git.rublox.pro/rublox/player.git +``` + +## Шаг 2: Запусти локально (3 минуты) + +```bash +npm install # ~250 МБ, занимает 1-2 мин +cp .env.example .env # дефолты подходят +npm run dev +``` + +Открой http://localhost:5173 — увидишь приветственный экран. Без JWT/ticket'a реальные игры не загрузятся, но мы будем тестить через standalone-режим. + +## Шаг 3: Standalone-режим для разработки (1 минута) + +```bash +echo "VITE_STANDALONE=true" >> .env +# Перезапусти npm run dev (Ctrl+C → npm run dev снова) +``` + +Открой http://localhost:5173/sample — загрузится демо-игра из `src/fixtures/sample-game.json`. Игрок-куб на зелёном поле, 4 стены, красная сфера. + +## Шаг 4: Сделай маленькое улучшение + +Хороший первый PR — что-то маленькое и видимое. Варианты: + +- **Опечатка в README** или CHANGELOG (всегда найдётся!). +- **Новый цвет** для одного из примитивов в `src/fixtures/sample-game.json` — поменяй пол с зелёного на красный. +- **Подпись `subText`** в `src/App.jsx:IndexRoute` сделай красивее. + +Пример: поменяем цвет пола в sample-game. + +Открой `src/fixtures/sample-game.json`, найди: +```json +{"id":"floor","type":"box","x":0,"y":-0.5,"z":0,"sx":20,"sy":1,"sz":20,"color":"#3a8a3a"} +``` +Поменяй `#3a8a3a` (зелёный) на свой любимый цвет, например `#7c3aed` (фиолетовый). + +Перезагрузи http://localhost:5173/sample — пол стал фиолетовый! + +## Шаг 5: Проверь стиль кода + +```bash +npm run lint # ESLint +npm run format # Prettier (автоформатирует) +``` + +Оба должны пройти без ошибок. Если ESLint что-то жалуется — исправь. + +## Шаг 6: Запушь и открой PR + +```bash +git checkout -b feature/cool-floor-color +git add src/fixtures/sample-game.json +git commit -m "feat: фиолетовый пол в sample-game" +git push origin feature/cool-floor-color +``` + +Перейди по ссылке которую печатает git (или открой https://git.rublox.pro/rublox/player/pulls и кнопка «New Pull Request»). Опиши что и зачем поменял. + +## Шаг 7: Дождись CI + +После открытия PR автоматически запустятся проверки: +- `Lint + Format` — твой код стилистически чистый +- `Build` — vite build проходит без ошибок +- `Secret scan` — нет утечек паролей/токенов +- `PR size check` — PR не слишком большой + +Если что-то падает — исправь, сделай новый commit, запушь — CI перезапустится. + +## Шаг 8: Дождись ревью + +Лид (МИН) ревьюит каждый PR в течение 48 часов (обычно гораздо быстрее). Если он попросит изменения — поправь, запушь снова в ту же ветку. + +После approve Лид сам нажмёт Merge → webhook задеплоит изменения на staging, а тебе зачислятся **+5 баллов разработчика** + бонусы за объём изменений. + +## Поздравляем! + +Ты сделал первый PR. Дальше — выбирай задачу из issues с тегом `good-first-issue` или предлагай свою. + +## Что почитать дальше + +- [ARCHITECTURE.md](../ARCHITECTURE.md) — как устроен плеер изнутри +- [CONTRIBUTING.md](../CONTRIBUTING.md) — детально про стиль и процесс +- [SECURITY.md](../SECURITY.md) — что делать если нашёл уязвимость +- [TUTORIAL_DEBUG_BABYLON.md](./TUTORIAL_DEBUG_BABYLON.md) — отладка 3D-сцены +- [TUTORIAL_ADD_SCRIPT_API.md](./TUTORIAL_ADD_SCRIPT_API.md) — как расширить API для игровых скриптов + +## Если что-то пошло не так + +- **`npm install` упал** — проверь Node.js версию (нужно 18+), удали `node_modules` и `package-lock.json`, запусти заново. +- **Браузер показывает белый экран** — открой DevTools (F12) → Console, увидишь ошибку. Скорее всего сломанный импорт или typo. +- **CI упал** — кликни по красному крестику в PR, увидишь логи. Обычно это format/lint — `npm run format` + `git commit --amend` чинит. +- **Push в Gitea просит пароль** — добавь SSH-ключ в профиль Gitea (см. /developer/keys). + +Вопросы — в канал `#разработка` на team.rublox.pro.