Ассеты, аудио, сейвы

AssetLoader

Загрузчик поверх Assets из Pixi. URL решает приложение — движок получает функцию-резолвер:

import { AssetLoader } from '@rpg/engine';

const assets = new AssetLoader((key) => `assets/${key}.png`);
await assets.load(['tiles/grass', 'chars/hero_down_1'], (p) => setProgressBar(p));

assets.texture('tiles/grass'); // Texture; бросает, если не загружено
assets.has('tiles/water_1');

Грабли: Assets.load без предварительного Assets.init({}) висит навсегда без ошибок в консоли. AssetLoader делает ensureInit() сам.

Атласы

// Spritesheet JSON должен ссылаться на PNG относительным путём — Pixi загрузит сам
const sheet = await assets.loadAtlas('chars/hero_sheet');

assets.frames('chars/hero_sheet', 'hero_walk');   // кадры hero_walk_1, hero_walk_2, ...
assets.animation('chars/hero_sheet', 'hero_walk_down'); // готовая анимация из sheet.animations

frames() сортирует кадры по числу в конце имени. animation() возвращает кадры из sheet.animations (их пишут генераторы — buildAtlas(..., { animations }), см. art-pipeline.md); готовые списки удобно отдавать в SpriteAnimator (anim.md). Пример генерации атласа — в art-pipeline.md.

Размер кадра в рантайме — из атласа, не из констант:

assets.frameSize('chars/hero_sheet.json');              // { w: 16, h: 24 } — первый кадр
assets.frameSize('chars/npcs_sheet.json', 'trader_mila_1'); // конкретный кадр (sourceSize)

Смещения над головой персонажа (маркер, полоска HP) считайте от frameSize, а не от захардкоженной высоты. Источник номиналов для генераторов — apps/game/tools/pixelart/sizes.mjs (см. art-pipeline.md).

FrameAnimation

import { FrameAnimation } from '@rpg/engine';

const sprite = new Sprite(frames[0]);
const anim = new FrameAnimation(sprite, frames, 8 /* fps */, true /* loop */);
anim.update(dt);          // каждый тик
anim.setFrames(otherFrames, true); // сменить кадры (поворот, состояние)

AudioManager

Четыре шины (master/music/sfx/ambience), кроссфейд лупов, опции sfx (громкость/скорость/панорама), кэш сэмплов. Фабрика AudioContext инъецируется (в тестах — фейк), как StorageLike у SaveManager:

import { AudioManager } from '@rpg/engine';

const audio = new AudioManager((key) => `audio/${key}.wav`);

// Расблокировать из обработчика пользовательского ввода (требование браузеров):
uiButton.onSelect = () => void audio.unlock();

await audio.load('bell');
await audio.play('bell', 0.8);                            // sfx, громкость 0.8
const h = await audio.play('bell', { volume: 0.8, rate: 1.1, pan: -0.4 }); // хендл голоса
h?.setVolume(0.5);                                        // параметры в полёте
h?.setRate(1.3);
h?.setPan(0.6);                                           // panner создастся, если его не было
h?.stop(0.05);                                            // короткое затухание
await audio.playMusic('meadows_theme', { fade: 2 });      // зациклится с нарастанием 2 сек
audio.stopMusic(1);                                       // затухание 1 сек
await audio.playAmbience('meadows', { fade: 3 });         // слот амбиента — отдельно от музыки
audio.setBusVolume('music', 0.6);                         // громкость шины

Опции play (PlayOptions): volume (по умолчанию 1), rate (0.5..2 — джиттер шагов, вариации тона), pan (-1..1; при |pan| < 0.01 узел StereoPanner не создаётся), restart (заглушить прежние играющие экземпляры того же ключа коротким фейдом). Число вместо объекта — синтаксический сахар для { volume } (старые вызовы не надо мигрировать).

play возвращает SfxHandle | null (null — ключ не декодировался, контекст не готов). Хендл умеет stop(fadeSeconds?), setVolume, setPan, setRate; после stop и естественного конца звука хендл «мёртв» — все методы no-op. Полифония ограничена maxVoices (третий аргумент конструктора, по умолчанию 24, 0 — без лимита): при переполнении воруется самый тихий играющий голос.

playBuffer(key, buffer, opts?) — тот же sfx, но из буфера в памяти (процедурные звуки, синтезированные в рантайме): ключ — логическое имя голоса (дедуп, restart, полифония, шпион onPlayed), не файл. Пара к нему — createBuffer(data: Float32Array, sampleRate = 22050): моно-сэмплы → AudioBuffer (null, пока контекст не разблокирован — после первого play/unlock работает). Чистые примитивы синтеза (bandNoise, synth, decay, normalize, makeRng) идут с движком в @rpg/engine/tools/synth.mjs — без node-импортов, готовы для браузера:

import { bandNoise, decay, normalize, synth } from '@rpg/engine/tools/synth.mjs';

const samples = normalize(synth(0.12, (t) => noise() * decay(t, 0.12, 2)), 0.3);
const buf = audio.createBuffer(samples);
if (buf) await audio.playBuffer('sfx/step_grass#0', buf, { volume });
// до unlock буфер не создать — fallback на файловый audio.play('sfx/step_grass')

Слоты лупов: playMusic и playAmbience — независимые слоты с кроссфейдом (повторный вызов вытесняет прежний трек своего слота; негодный ключ не глушит текущий). playLoop — луп без слота (занимать нечего, сколько вызвали — столько играет, MusicHandle.stop останавливает конкретный): база для локальных амбиент-слоёв (вода, гул) — игра поверх амбиента области. У MusicHandle есть setVolume(v) — мгновенная громкость для медленных тик-фейдов поверх (сам движок фейд не тикает):

const layer = await audio.playLoop('ambience/ponds_water', { bus: 'ambience', fade: 2 });
// ...
layer?.stop(2);

Шпионский хук onPlayed?: (key, opts) => void вызывается при каждом фактическом запуске звука — и sfx, и лупов (музыка/амбиент/слои; опции нормализованы, rate 1/pan 0) — для тестов и DEV-лога игры (кольцо window.__gameAudioLog, им пользуется агентная проба checks/audio.mjs: на слух в headless не проверить — смотрят фактические запуски). onEnded?(key) зовётся, когда звук доиграл до конца; заглушенные голосом (stop, воровство, restart) окончания событие не поднимают. duration(key) — длительность буфера в секундах (null, если ещё не декодирован) — для катсцен и генераторов, синхронизирующихся со звуком.

Связка с Settings (громкости применяются при изменении):

settings.onChange((s) => {
    audio.setBusVolume('master', s.master);
    audio.setBusVolume('music', s.music);
    audio.setBusVolume('sfx', s.sfx);
    audio.setBusVolume('ambience', s.ambience);
});

play/playMusic/playAmbience не падают, если звук не загружен или AudioContext не разблокирован — тихо ничего не делают. До unlock шин ещё нет — setBusVolume игнорируется, громкости применяются после него.

SaveManager

JSON-слоты в Storage-подобном хранилище (localStorage в браузере, Map в тестах):

import { SaveManager } from '@rpg/engine';

const saves = new SaveManager(localStorage);
saves.save('autosave', { pos: { x: 5, y: 5 }, state: gameState.serialize() });
const data = saves.load<typeof myData>('autosave');
saves.has('autosave');
saves.delete('autosave');