# Effects Engine — анимированные визуальные эффекты для сцен

Effects Engine позволяет сценарию показать поверх сцены короткий визуальный эффект: вспышку, дым, искры, волшебное свечение. Эффект — это маленькая сцена Godot, которую мод кладёт в свою папку `effects/`; сценарий запускает эффект по имени, и тот остаётся на экране, пока не закончится сам или не кончится диалог.

Это мод-движок, у которого нет ничего своего на экране. Входящие в проекты игры пока не содержат ни одной сцены-эффекта, поэтому во время игры вы эффект не встретите; мод существует для авторов, которые хотят такой добавить.

## Как эффект появляется

1. В сценарии выполняется строка `effect <имя>`.
2. Effects Engine ищет сцену `effects/<имя>.tscn` среди загруженных модов.
3. Эффект ложится поверх картинки сцены — выше фона и его предметов, ниже текстового окна — и проигрывается.
4. Когда заканчивается диалог, запустивший эффект, тот убирается, если не убрался сам раньше.

Сценарий эффекта не ждёт: следующая строка показывается сразу.

## Авторам: добавить эффект

Положите сцену эффекта в свой мод:

```filestree
my_mod/
└── effects/
    └── sparks.tscn
```

Запустите из сценария:

```scenario
text "Лампа мигнула."
effect sparks
text "В темноте что-то шевельнулось."
end
```

**Моды должны быть папками.** Сцены Godot загружаются только из мода, установленного папкой. У мода, распространяемого архивом `.zip`, эффекты пропускаются с предупреждением в логе.

### Кубики для сцены эффекта

Effects Engine даёт три способа анимировать кадры внутри сцены эффекта:

- **Набор кадров с перетеканием** — узел со скриптом `EffectDataSet`, список картинок-кадров и `AnimationController`, который растворяет один кадр в другом. Скорость и время растворения задаются в инспекторе; кадры проигрываются один раз, и эффект убирает себя сам.
- **Спрайт-лист в шейдере** — `EffectAnimator` прокручивает `TextureRect` с материалом кадровой простыни через заданное число кадров за заданное время.
- **Спрайт-лист без шейдера** — `EffectAnimNode` листает горизонтальный спрайт-лист (ширина кадра = ширина листа / число кадров) и в конце убирает себя. Его можно создать и из кода: `EffectAnimNode.SpawnOn(target, sheet, frameCount, seconds)`.

Набор кадров и спрайт-лист без шейдера растягиваются на всю сцену, поэтому кадры, нарисованные под размер сцены, совпадают с фоном.

### Первый эффект без кода

Простейший эффект — сцена, у которой в корне `TextureRect` с картинкой, растянутой на весь экран, — например, полупрозрачное свечение. Он появляется по `effect <имя>` и исчезает, когда кончается диалог.

## Если что-то пошло не так

1. **Ничего не появляется, а в логе — что эффект не найден.** Файл должен лежать как `effects/<имя>.tscn` в моде, входящем в игру, и имя в сценарии должно совпадать.
2. **Эффект работает в разработке, но не у игроков.** Мод был опубликован архивом `.zip`; публикуйте папкой.
3. **Эффект не исчезает.** Он висит, пока не кончится его диалог; завершите диалог или соберите эффект из блоков набора кадров или спрайт-листа — они убирают себя, когда заканчиваются.