NovelML 文法リファレンス
========================

このドキュメントでは、NovelML の基本的な文法とその実行方法について説明します。

各タグの詳細な説明については、[Suika3 タグリファレンス](tag.md)を参照してください。

---

## 1. NovelML は「タグ」と呼ばれるエンジンコマンドのリストです

NovelML は**タグ**のリストです。タグは**エンジンへのコマンド**です。

- 各タグはエンジンに何かをするように指示します。
- タグは、出現順に**一つずつ**実行されます。
- タグの実行が終わると「完了」となり、「実行位置」が次に移動します。

同じタグを再度書くと、そのタグが**実行されるたびに**同じことが行われます。

---

## 2. 実行は上から下へ進みます

NovelML はファイルの先頭から末尾に向かって、一度に1つのタグずつ実行されます。

- 実行は通常、前方に進みます。
- 現在の**実行位置**は1つだけです。

```PlainText
[text text="こんにちは"]
[text text="世界"]
```

この場合：

1. `こんにちは` が表示されます。
2. 次に `世界` が表示されます。

---

## 3. すべてをタグとして記述する必要があります

NovelML では、**すべての行がタグである必要があります**。

- シナリオ全体がタグを使用して記述されます。
- テキストであっても `[text]` タグを使用する必要があります。

```PlainText
[text text="いい天気ですね。"]
```

---

## 4. 待機するタグと待機しないタグ

タグには大きく分けて2つの種類があります。

- **実行後、すぐに次のタグに移動するタグ**
- ユーザー入力や何かが終了するのを**待機するタグ**

一般的な「待機」タグには以下のものがあります。

- `text` (クリックを待機)
- `click` (クリックを待機)
- `wait` (指定された時間を待機)
- `video` (再生が終了するまで待機)

これらのタグは、**特別な構文なしで**実行を一時停止します。

### 4.1 バックグラウンドで実行されるタグ (非同期)

一部のタグは**バックグラウンドで実行**（非同期実行）される場合があります。

代表的な例：

- `anime`
- `move`

これらのタグは：

- アニメーションや移動を作成し、開始します。
- `async="true"` が指定されている場合、終了を**待たずに**直ちに次のタグの実行を継続します。

このため、`async="true"` タグの後に続くタグは、**アニメーションがまだ再生されている間に**実行される可能性があります。

これにより、以下のようなことが可能になります。

- 背景やキャラクターを移動させる。
- その間にテキストを表示したり、他のエフェクトを実行したりする。

---

## 5. 実行の流れを変更するタグ

通常、実行は上から下へ進みますが、一部のタグは**実行を継続する場所を変更**します。

### 5.1 ラベル

```PlainText
[label start]
```

- ラベルはシナリオ内の名前付きの位置をマークします。
- ラベル自体を実行しても、それだけでは何も起こりません。

### 5.2 ジャンプ

```PlainText
[goto name="start"]
```

---

## 6. 条件分岐 (if / elseif / else)

```PlainText
[if ...]
  ...
[elseif ...]
  ...
[else]
  ...
[endif]
```

- 最初に一致したブロックのみが実行されます。
- 選択されなかったブロックは**完全にスキップ**されます。
- `elseif` は0回以上記述できます。
- `else` は任意です。

---

## 7. 変数と変数値の展開

### 7.1 変数の設定

変数を設定するには `[set]` タグを使用します。

```PlainText
[set name="player_name" value="アリス"]
```

- すべての変数は**文字列**です。
- 数値や真偽値も文字列として保存されます。

### 7.2 変数値の展開

タグの値やテキストの中で変数展開を使用できます。

```PlainText
[text text="${player_name}は立ち上がった"]
```

- `${...}` は実行時に変数の値に置き換えられます。
- 展開は**タグが実行される時**に行われます。

```PlainText
[set name="x" value="1"]
[text text="${x}"]
[set name="x" value="2"]
[text text="${x}"]
```

この例では、出力は `1`、次に `2` となります。

---

## 8. マクロは一単位として実行できるブロックです

マクロを使用すると、複数のタグをグループ化して一緒に実行できます。

```PlainText
[defmacro name="greet"]
  [text text="こんにちは"]
[endmacro]

[callmacro name="greet"]
```

---

## 9. ファイルの切り替え (load)

```PlainText
[load file="scene2.txt" label="start"]
```

`file=` は必須で、`label=` は任意です。

---

## 10. ファイルの終端に達した時の挙動

実行が：

- ファイルの末尾に達し、かつ
- それ以上 `goto` や `load` が発生しない場合

**シナリオの実行は終了します**。

ただし、一部のプラットフォーム（iOSやゲームコンソールなど）では、アプリの終了が許可されていません。

そのため、シナリオの最後では**明示的に**以下のいずれかを行うことが推奨されます。

- `goto` を使用してタイトルに戻る。
- `load` を使用してタイトルシーンを読み込む。

自動的に終了させるのではなく、上記のように処理してください。

---

## 11. このドキュメントと他のドキュメントの関係

このドキュメントは、以下のドキュメントと併せて読むことを想定しています。

- [タグリファレンス](tag.md): 各タグが何をするか
- 本ドキュメント: シナリオがどのように実行されるか

個々のタグの詳細については、[タグリファレンス](tag.md)を参照してください。
