# Скриптовый формат `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 с множеством асинхронных действий.