From 7dabfd4ffffd27cd17c94b0519ec9f39f9591fe4 Mon Sep 17 00:00:00 2001 From: Yuriy Mayatnikov Date: Thu, 18 Jun 2026 16:15:36 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=81=D0=B8=D0=BD=D1=85=D1=80=D0=BE?= =?UTF-8?q?=D0=BD=D0=B8=D0=B7=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20?= =?UTF-8?q?=D0=BE=D0=BF=D0=B8=D1=81=D0=B0=D0=BD=D0=B8=D0=B5=20=D0=B0=D1=81?= =?UTF-8?q?=D1=81=D0=B5=D1=82=D0=BE=D0=B2=20=D1=81=20=D1=80=D0=B5=D0=B0?= =?UTF-8?q?=D0=BB=D1=8C=D0=BD=D0=BE=D1=81=D1=82=D1=8C=D1=8E=20(PNG=20?= =?UTF-8?q?=D0=B8=D0=B7=20src/assets=20+=20=D1=84=D0=BE=D0=BB=D0=B1=D1=8D?= =?UTF-8?q?=D0=BA)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ревью отметило устаревшие тексты после перехода на загрузку PNG: - assets.ts: заголовок описывал «процедурно, без внешних файлов» — теперь PNG из src/assets/<ключ>.png с процедурным фолбэком. - HOWTO §8: убран совет «заменить тело drawX() на TextureLoader» (уже сделано); актуальный путь — положить PNG с нужным именем в src/assets/. - README/ARCHITECTURE/ASSET_BRIEF: статус «подключено», корректный механизм (рантайм- загрузка по пути, не импорт-бандлинг). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 5 +++-- docs/ARCHITECTURE.md | 9 +++++---- docs/ASSET_BRIEF.md | 26 +++++++++++++------------- docs/HOWTO.md | 17 +++++++++++------ src/render/assets.ts | 16 ++++++++-------- 5 files changed, 40 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 76487a6..4f2eb60 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,9 @@ Top-down рогалик: процедурный данжен из комнат, Есть **стартовое меню** с выбором уровня: данжен генерируется процедурно каждый забег, но параметризуется набором правил (размер, плотность/сила врагов, HP, seed). -Двери видны всегда (закрыты в бою, открыты после зачистки). Графика — процедурные -ассеты в `render/assets.ts`; бриф на полную художку — в `docs/ASSET_BRIEF.md`. +Двери видны всегда (закрыты в бою, открыты после зачистки). Графика — PNG-ассеты в +`src/assets/` (грузятся в `render/assets.ts`; при отсутствии файла — процедурный +фолбэк). Бриф на художку — `docs/ASSET_BRIEF.md`. > Это рабочая **база для развития**, а не готовая игра. Архитектура специально > сделана так, чтобы её было легко расширять — и человеку, и ИИ-агентам. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bc6cd0a..3208706 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -129,10 +129,11 @@ ### Ассеты (render/assets.ts) -`Assets` строит текстуры процедурно на `` (спрайты персонажей, пол, стены, -двери, снаряд, эффекты, тень) и кэширует их. Это «стандартный» набор без внешних файлов. -Заменить на свои PNG — описано в `docs/HOWTO.md` и `docs/ASSET_BRIEF.md` (бриф на полную -графику). Ключи ассетов используются и в рендере, и в брифе. +`Assets` грузит текстуры из `src/assets/<ключ>.png` (спрайты персонажей, пол, стены, +двери, снаряд, эффекты, тень) и кэширует их; если PNG нет — рисует процедурный фолбэк +на ``, поэтому игра не ломается без ассетов. Dev-сервер отдаёт `/assets/*` из +`src/assets/`, прод-сборка копирует их в `dist/assets/`. Подмена/добавление графики — +`docs/HOWTO.md` и `docs/ASSET_BRIEF.md`. Ключи ассетов едины в рендере, брифе и именах файлов. ### Эффекты оружия diff --git a/docs/ASSET_BRIEF.md b/docs/ASSET_BRIEF.md index 60d4ebe..e544ac6 100644 --- a/docs/ASSET_BRIEF.md +++ b/docs/ASSET_BRIEF.md @@ -1,11 +1,12 @@ # Бриф на ассеты — «Биндим Фигняшку» -Документ для генерации полного набора графики (через Claude/дизайн-ИИ или художника). -Ниже — **готовый промпт** (можно копировать целиком) и **таблица ассетов**, привязанная -к нашему пайплайну: каждый ассет ложится в `src/render/assets.ts` вместо текущего -процедурного рисунка (заменяем `drawX()` на загрузку PNG через `THREE.TextureLoader`). +Документ для генерации/догенерации графики (через Claude/дизайн-ИИ или художника). +Ниже — **готовый промпт** (можно копировать целиком) и **таблица ассетов**. -Следующим заходом мы подключим присланные PNG; пока в игре — простые процедурные плейсхолдеры. +> ✅ **Статус: набор уже подключён.** 21 PNG лежат в `src/assets/` и автоматически +> грузятся `src/render/assets.ts` по имени файла (`assets/<ключ>.png`); если какого-то +> файла нет — рисуется процедурный фолбэк. Этот бриф нужен, чтобы **догенерировать или +> заменить** ассеты: достаточно положить PNG с тем же именем в `src/assets/`. --- @@ -93,13 +94,12 @@ --- -## Как мы это применим (следующий заход) +## Как это подключено (уже работает) -1. Кладём PNG в `src/assets/` (новая папка) и импортируем как URL (Bun умеет в `import img from './x.png'`). -2. В `src/render/assets.ts` заменяем процедурные `drawX()` на - `new THREE.TextureLoader().load(url)` с теми же ключами — больше нигде ничего менять не нужно - (рендер берёт текстуры по ключам, см. `docs/ARCHITECTURE.md` → «Тема / ассеты»). -3. При желании заводим тему `Theme` со ссылками на наборы ассетов, чтобы переключать стиль. +1. PNG лежат в `src/assets/` с именами-ключами (`floor.png`, `player-ranged.png`, …). +2. `src/render/assets.ts` грузит их в рантайме через `THREE.TextureLoader` по пути + `assets/<ключ>.png` (НЕ импорт-бандлингом). Нет файла → процедурный фолбэк `drawX()`. +3. Dev-сервер отдаёт `/assets/*` из `src/assets/`; прод-сборка копирует их в `dist/assets/`. +4. HUD-ассеты (`heart-*`, `icon-*`) грузит `HudOverlay`, меню (`logo`, `menu-bg`) — `index.html`. -Если пришлёте ОДИН атлас вместо отдельных файлов — приложите JSON с прямоугольниками -(`{ "player-ranged": [x,y,w,h], ... }`), мы нарежем через `texture.repeat`/`offset`. +**Заменить/добавить:** просто положи PNG с тем же именем в `src/assets/` — подхватится само. diff --git a/docs/HOWTO.md b/docs/HOWTO.md index 3bee9ef..53702a8 100644 --- a/docs/HOWTO.md +++ b/docs/HOWTO.md @@ -115,14 +115,19 @@ ## 8. Кастомные ассеты (спрайты, текстуры, тема) -Графика (спрайты персонажей/врагов, пол, стены, двери, снаряд, эффекты, тень) рисуется -процедурно в **`src/render/assets.ts`** (класс `Assets`, кэширует текстуры three.js). +Графика грузится из PNG в **`src/assets/`** (класс `Assets` в `src/render/assets.ts` +тянет `assets/<ключ>.png` через `THREE.TextureLoader`); если файла нет — рисуется +процедурный фолбэк на canvas, и игра не ломается. -- **Свои PNG вместо процедурных:** замени тело нужного `drawX()` на загрузку картинки - `new THREE.TextureLoader().load(url)` и верни её из соответствующего геттера — рендер - берёт текстуры по ключам, больше ничего менять не нужно. Полный список нужных ассетов с - размерами и готовый промпт для дизайн-ИИ — в **`docs/ASSET_BRIEF.md`**. +- **Свой/новый ассет:** просто положи PNG с именем `<ключ>.png` в **`src/assets/`** + (dev-сервер отдаёт их сразу, прод-сборка копирует в `dist/assets`). Код менять не нужно. + Ключи = именам файлов (`player-ranged`, `enemy-boss`, `floor`, `door-closed`, `tear`, + `heart-full`, `icon-ranged`, …); полный список и промпт для дизайн-ИИ — в **`docs/ASSET_BRIEF.md`**. +- **Запасной рисунок (фолбэк):** функции `drawX()` в `assets.ts` — правь их, только если + нужен другой плейсхолдер на случай отсутствия PNG. - **Цвета/тинты/фон** (не текстуры) — в **`src/render/theme.ts`** (`Theme` + `DEFAULT_THEME`). +- **HUD-ассеты** (сердечки `heart-*`, иконки `icon-*`) грузит `HudOverlay`; меню (`logo`, + `menu-bg`) — `index.html`. Те же имена в `src/assets/`. - **Своя палитра:** сделай ещё один объект `Theme` и передай его в `new ThreeRenderer(canvas, myTheme)` в `main.ts`. Сейчас рендер создаётся один diff --git a/src/render/assets.ts b/src/render/assets.ts index 6c55946..2445c19 100644 --- a/src/render/assets.ts +++ b/src/render/assets.ts @@ -1,15 +1,15 @@ import * as THREE from 'three'; /** - * assets.ts — СТАНДАРТНЫЕ АССЕТЫ, нарисованные процедурно на canvas и - * превращённые в текстуры three.js. Никаких внешних файлов: спрайты «зашиты» - * в код, поэтому проект самодостаточен и легко версионируется. + * assets.ts — поставщик текстур. Каждая текстура грузится из + * `src/assets/<ключ>.png` через THREE.TextureLoader; если PNG нет — рисуется + * процедурный фолбэк на canvas (функции drawX ниже), чтобы игра работала без + * ассетов. Текстуры кэшируются и освобождаются в dispose(). * - * Как заменить на свои картинки: вместо рисования на canvas загрузи PNG через - * `new THREE.TextureLoader().load('путь.png')` и верни его из соответствующего - * геттера. Остальной рендер не изменится — он просто берёт текстуру по имени. - * - * Текстуры кэшируются (строятся один раз) и освобождаются в dispose(). + * Как заменить/добавить графику: положи PNG с именем `<ключ>.png` в `src/assets/` + * (dev-сервер отдаёт их из src/assets, прод-сборка копирует в dist/assets). Код + * трогать не нужно. Функции drawX — это лишь плейсхолдер-фолбэк; правь их, только + * если хочешь другой запасной рисунок. Полный список ключей — в docs/ASSET_BRIEF.md. */ export type SpriteKey =