docs: туториалы first-PR + debug Babylon + Code of Conduct
This commit is contained in:
parent
3aadb32b62
commit
d0f5c90622
43
CODE_OF_CONDUCT.md
Normal file
43
CODE_OF_CONDUCT.md
Normal file
@ -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.
|
||||
128
docs/TUTORIAL_DEBUG_BABYLON.md
Normal file
128
docs/TUTORIAL_DEBUG_BABYLON.md
Normal file
@ -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 → <device>.
|
||||
|
||||
## Что почитать
|
||||
|
||||
- https://doc.babylonjs.com/features/featuresDeepDive/inspector
|
||||
- https://spector.babylonjs.com/
|
||||
- [reference_kubikon_scripting_api.md](../../disaster-recovery/...) — приватный референс API для скриптов
|
||||
|
||||
## Вопросы
|
||||
|
||||
В канал `#разработка` на https://team.rublox.pro.
|
||||
117
docs/TUTORIAL_FIRST_PR.md
Normal file
117
docs/TUTORIAL_FIRST_PR.md
Normal file
@ -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.
|
||||
Loading…
x
Reference in New Issue
Block a user