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

このドキュメントでは、NovelML の「基本的な構文」と「実行の仕組み」を説明します。

各タグの詳しい説明については [NovelML タグリファレンス](novelml-tags.md) を参照してください。

---

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

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

- 各タグは、エンジンに何をするかを指示します
- タグは、書かれている順番に **1つずつ** 実行されます
- タグが実行されると、そのタグは「完了」し、「実行位置」が次へ進みます

同じタグをもう一度書いた場合、そのタグは **実行されるたびに** 同じ処理を行います。

---

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

NovelML は、ファイルの先頭から末尾へ向かって、タグを1つずつ実行します。

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

```PlainText
[text text="Hello"]
[text text="World"]
```

この場合:

1. `Hello` が表示されます
2. そのあと `World` が表示されます

---

## 3. すべてをタグとして書く必要があります

NovelML では、**すべての行をタグとして書く必要があります**。

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

```PlainText
[text text="It's a beautiful day."]
```

---

## 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="Alice"]
```

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

### 7.2 変数展開

タグの値やテキストの中で、変数展開を使うことができます。

```PlainText
[text text="${player_name} stands up"]
```

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

```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="Hello"]
[endmacro]

[callmacro name="greet"]
```

---

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

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

`file=` は必須で、`label=` は省略できます。

---

## 10. ファイルの末尾で起こること

実行が次の状態になった場合:

- ファイルの末尾に到達し、
- それ以上 `goto` または `load` タグが実行されない

そのとき、**シナリオの実行は終了** します。

ただし、一部のプラットフォーム (たとえば iOS やゲーム機) では、アプリの終了が許可されていません。

そのため、シナリオを自動終了させるのではなく、**明示的に** 次のどちらかを行うことを推奨します。

- `goto` を使ってタイトルへ戻る
- `load` を使ってタイトルシーンを読み込む

---

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

このドキュメントは、次のドキュメントと合わせて使うことを想定しています。

- タグリファレンス: 各タグが何をするかを説明します
- このドキュメント: シナリオがどのように実行されるかを説明します

個別のタグの詳細については、「タグリファレンス」を参照してください。
