278 lines
11 KiB
Markdown
278 lines
11 KiB
Markdown
# Скриптовый формат `Perep_script`
|
||
|
||
**Версия:** 1.0 (стабильная, с поддержкой универсальных ссылок)
|
||
**Цель:** Полное описание синтаксиса и семантики скриптового языка, используемого в событиях _Persona 2 (PSX)_.
|
||
**Ключевая особенность:** Поддержка **универсальных ссылок** через `!`, `@`, `#`.
|
||
|
||
---
|
||
|
||
## 1. Общее описание
|
||
|
||
`Perep_script` — это **событийно-ориентированный, потоковый скриптовый язык**, предназначенный для описания интерактивных сцен в игре: диалоги, эффекты, анимации, переходы.
|
||
|
||
Он сочетает:
|
||
|
||
- Низкоуровневые hex-команды
|
||
- Высокоуровневые именованные операции
|
||
- **Механизм асинхронного управления через универсальные ссылки**
|
||
- Поддержку подпрограмм и ожиданий
|
||
|
||
---
|
||
|
||
## 2. Универсальные ссылки: `!`, `@`, `#`
|
||
|
||
### 🔥 Главный принцип:
|
||
|
||
> **Любая команда может быть помечена символом `!`, `@` или `#`. Это создаёт уникальную ссылку (handle), по которой можно управлять выполнением этой команды.**
|
||
|
||
Символы **не имеют семантической привязки** к типу команды (не важно, окно это, звук или задержка). Это просто **три доступных регистра ссылок**.
|
||
|
||
|Символ|Назначение|
|
||
|---|---|
|
||
|`!`|Ссылка типа A (универсальная)|
|
||
|`@`|Ссылка типа B (универсальная)|
|
||
|`#`|Ссылка типа C (универсальная)|
|
||
|
||
> ✅ Можно пометить `SoundPly#`, `000000A8!`, `LoadDung@` — всё валидно.
|
||
> ✅ Можно использовать `__WaitTo @` на `collLink@` или `00000043#`.
|
||
> ❌ Нельзя использовать один символ для двух активных задач одновременно — поведение не определено (перезапись).
|
||
|
||
---
|
||
|
||
### Пример использования:
|
||
|
||
PASCAL
|
||
|
||
`SoundPly@ 00003023 0000007F // Проиграть звук → handle = @ 00000043# 00000004 // Задержка на 4 тика → handle = # __WaitTo @ // Ждать завершения звука __WaitTo # // Ждать завершения задержки`
|
||
|
||
👉 Порядок `__WaitTo` определяет синхронизацию.
|
||
|
||
---
|
||
|
||
## 3. Синтаксис команд
|
||
|
||
### Формат:
|
||
|
||
```
|
||
[Команда][!/@/#] [аргументы...]
|
||
```
|
||
|
||
или
|
||
|
||
```
|
||
[Команда] [аргументы...]
|
||
```
|
||
|
||
Если команда помечена символом — она **регистрируется в системе ссылок** под этим тегом.
|
||
|
||
---
|
||
|
||
## 4. Управление выполнением
|
||
|
||
### `__WaitTo [!/@/#]`
|
||
|
||
- Приостанавливает выполнение скрипта до **завершения команды**, помеченной указанным символом.
|
||
- Если команда уже завершена — продолжает сразу.
|
||
- Поддерживает асинхронные операции: звуки, загрузки, эффекты.
|
||
|
||
**Пример:**
|
||
|
||
PASCAL
|
||
|
||
`LoadDung@ 00002E06 __WaitTo @ // Ждать загрузки локации`
|
||
|
||
---
|
||
|
||
### `__GoSub># [label]`
|
||
|
||
- Вызов подпрограммы.
|
||
- Метка `#` может использоваться для:
|
||
- Отслеживания выполнения
|
||
- Прерывания (`__Kill #` — если поддерживается)
|
||
- Вложенных ожиданий
|
||
|
||
**Пример:**
|
||
|
||
PASCAL
|
||
|
||
`__GoSub># SHOW_TEXT __WaitTo # // Ждать завершения всей подпрограммы`
|
||
|
||
> ⚠️ Реализация `__WaitTo #` зависит от движка: может означать "ждать входа", "ждать выхода" или "ждать завершения".
|
||
|
||
---
|
||
|
||
### `__Return--> [label]`
|
||
|
||
- Возврат из подпрограммы.
|
||
- Указание метки — скорее всего, **отладочное**, чтобы легче было читать скрипт.
|
||
- На исполнение не влияет.
|
||
|
||
---
|
||
|
||
### Возможные дополнительные команды (предположительно):
|
||
|
||
- `__Kill !` — принудительно завершить/прервать операцию с меткой `!`
|
||
- `__Check @` — проверить состояние (выполняется/завершена)
|
||
- (Требует подтверждения из других скриптов)
|
||
|
||
---
|
||
|
||
## 5. Команды (по категориям)
|
||
|
||
### 🔹 Аудио
|
||
|
||
|Команда|Описание|
|
||
|---|---|
|
||
|`SoundPly@`|Проиграть звук. Аргументы: `sound_id volume`|
|
||
|`SoundStop!`|Остановить звук (если есть)|
|
||
|
||
---
|
||
|
||
### 🔹 Визуальные эффекты
|
||
|
||
|Команда|Описание|
|
||
|---|---|
|
||
|`000000A8`|Инициализация эффекта?|
|
||
|`000000B9`|Настройка окна: `x y w h color flags`|
|
||
|`000000BA`, `000000BB`|Fade-in/out: `type duration flag`|
|
||
|`000000A9`|Начало fade-блока|
|
||
|`0000004E`|Конец блока или синхронизация|
|
||
|
||
---
|
||
|
||
### 🔹 Диалоги
|
||
|
||
|Команда|Описание|
|
||
|---|---|
|
||
|`WindShow!`|Показать окно. Аргумент: режим|
|
||
|`TextShow@`|Вывести текст с тегами|
|
||
|`WinClose!`|Закрыть окно, связанное с `!`|
|
||
|
||
---
|
||
|
||
### 🔹 Управление объектами
|
||
|
||
|Команда|Описание|
|
||
|---|---|
|
||
|`collLink@`|Привязать объект к карте: `type x y z rot`|
|
||
|`CSetAnim#`|Установить анимацию: `char_id anim_id speed`|
|
||
|
||
---
|
||
|
||
### 🔹 Работа с миром
|
||
|
||
|Команда|Описание|
|
||
|---|---|
|
||
|`LoadDung@`|Загрузить локацию по ID|
|
||
|`SetFlag!`|Установить флаг события (если есть)|
|
||
|
||
---
|
||
|
||
### 🔹 Системные
|
||
|
||
|Команда|Описание|
|
||
|---|---|
|
||
|`00000043`|Задержка в тиках|
|
||
|`__GoSub>#`|Вызов подпрограммы|
|
||
|`__WaitTo @`|Ожидание завершения операции|
|
||
|`__Return-->`|Возврат из подпрограммы|
|
||
|
||
---
|
||
|
||
## 6. Текст и теги
|
||
|
||
Поддерживаются **встроенные теги** `[XXXX]`, интерпретируемые как байтовые коды.
|
||
|
||
**Пример:**
|
||
|
||
PASCAL
|
||
|
||
`TextShow@ [2E12][0B00]Привет~[0111]Работает?`
|
||
|
||
### Распространённые теги:
|
||
|
||
|Тег|Предположение|
|
||
|---|---|
|
||
|`[2E12]`|Цвет текста|
|
||
|`[0B00]`|Размер шрифта|
|
||
|`[0100]`|Выравнивание|
|
||
|`[0111]`|Пауза между символами|
|
||
|`[0611]`|Эффект печати|
|
||
|`[0211]`|Звук при символе|
|
||
|`[0311]`|Новая строка / страница|
|
||
|
||
Символ `~` — **управляющий**: пауза, перенос, продолжение.
|
||
|
||
---
|
||
|
||
## 7. Пример: Полный разбор
|
||
|
||
PASCAL
|
||
|
||
`START: 000000A8 000000B9! 000000A0 00000078 00FFFFFF 00FFFFFF 00000002 SoundPly@ 00003023 0000007F 00000043# 00000004 __WaitTo @ __WaitTo # 000000A9 000000BA! 00000000 00006000 00000001 000000BB# 00000000 00006000 00000001 0000004E __GoSub>$ SHOW_TEXT __WaitTo $ LoadDung@ 00002E06 __Return--> START`
|
||
|
||
### Что происходит:
|
||
|
||
1. `000000B9!` — настройка окна → handle `!`
|
||
2. `SoundPly@` — старт звука → handle `@`
|
||
3. `00000043#` — задержка 4 тика → handle `#`
|
||
4. `__WaitTo @` — ждать звук
|
||
5. `__WaitTo #` — ждать задержку (хотя они могли идти параллельно)
|
||
6. Затем — fade-in через `000000BA!`, `000000BB#`
|
||
7. `__GoSub>$` — вызов `SHOW_TEXT` с handle `#` (здесь `$` — опечатка? или расширение? возможно, `#`)
|
||
8. `__WaitTo $` — ждать завершения подпрограммы
|
||
9. `LoadDung@` — загрузка локации
|
||
10. `__Return`
|
||
|
||
> ⚠️ Ошибка: `__GoSub>$` — возможно, опечатка. Должно быть `__GoSub>#`. Или `$` — четвёртый тип ссылки? (маловероятно)
|
||
|
||
---
|
||
|
||
## 8. Ключевые выводы
|
||
|
||
### ✅ Сильные стороны:
|
||
|
||
- **Универсальность ссылок** — любая команда может быть адресована
|
||
- **Гибкое управление потоком** — можно строить сложные цепочки
|
||
- **Асинхронность без потоков** — через `__WaitTo`
|
||
- **Читаемость** — при правильном использовании
|
||
|
||
### ⚠️ Ограничения:
|
||
|
||
- Нет проверки на повторное использование ссылки
|
||
- Нет обработки ошибок
|
||
- Нет явного освобождения handle
|
||
- Нет документации от разработчиков — всё по анализу
|
||
|
||
---
|
||
|
||
## 9. Рекомендации
|
||
|
||
1. **Используйте ссылки последовательно:**
|
||
|
||
PASCAL
|
||
|
||
`SoundPly@ ... __WaitTo @ TextShow# ... __WaitTo #`
|
||
|
||
2. **Не используйте одну метку дважды подряд без ожидания:**
|
||
|
||
PASCAL
|
||
|
||
`SoundPly@ 1234 SoundPly@ 5678 ← Первая ссылка @ теряется!`
|
||
|
||
3. **Для вложенных вызовов используйте разные метки:**
|
||
|
||
PASCAL
|
||
|
||
`__GoSub># sub1 __GoSub>@ sub2 __WaitTo # __WaitTo @`
|
||
|
||
|
||
---
|
||
|
||
## 10. Заключение
|
||
|
||
`Perep_script` — это **гибкий, event-driven язык с мощной системой управления выполнением через универсальные ссылки**. Его ключевое преимущество — способность синхронизировать разнородные операции (звук, графика, загрузка) через единый механизм `__WaitTo @`.
|
||
|
||
Он идеально подходит для сценариев в RPG с множеством асинхронных действий.
|
||
|