Suika3 タグリファレンス
====================

## 目次

| タグ名                            | 説明                                                               |
|-----------------------------|--------------------------------------------------------------------|
| [anime](#anime)                | アニメーションファイルを読み込んで実行します。                         |
| [bg](#bg)                       | フェード効果付きで背景画像を変更します。                               |
| [bgm](#bgm)                     | BGMファイルを再生します（Ogg Vorbis形式）。                            |
| [callmacro](#callmacro)      | 定義済みのマクロを呼び出します。                                       |
| [ch](#ch)                       | 詳細なレイヤーパラメーターでキャラクターを表示・非表示にします。       |
| [chapter](#chapter)           | チャプター名を設定します。                                             |
| [choose](#choose)             | 選択肢を表示し、選択結果を変数に保存するかラベルにジャンプします。     |
| [click](#click)               | ユーザーのクリックを待ちます。                                         |
| [config](#config)             | ゲームシステムの設定値を変更します。                                   |
| [defmacro](#defmacro)         | マクロ定義を開始します。                                               |
| [else](#else)                  | 条件が一致しない場合のif/elseifブランチの一部です。                    |
| [elseif](#elseif)              | ブランチに追加の条件を指定します。                                     |
| [endif](#endif)             | 条件分岐を終了します。                                                 |
| [endmacro](#endmacro)       | マクロ定義を終了します。                                               |
| [goto](#goto)               | 指定したラベルタグにジャンプします。                                   |
| [gui](#gui)                 | 指定したファイルのGUIを表示します。                                    |
| [if](#if)                   | 指定した条件に基づいて処理を分岐します。                               |
| [label](#label)             | ジャンプ先のラベルを定義します。                                       |
| [layer](#layer)             | 特定のレイヤーに画像を読み込んだり、パラメーターを設定します。         |
| [load](#load)               | NovelMLファイルを読み込み、特定のラベルにジャンプできます。            |
| [move](#move)               | キャラクターレイヤーを指定時間かけてアニメーションさせます。           |
| [pencil](#pencil)           | レイヤーにテキストを描画します。                                       |
| [returnmacro](#returnmacro) | マクロの実行から戻ります。                                             |
| [se](#se)                   | 効果音ファイルを再生します（Ogg Vorbis形式）。                         |
| [set](#set)                 | 変数の値を設定します（すべての変数はテキストとして扱われます）。       |
| [skip](#skip)               | スキップ機能の有効・無効を切り替えます。                               |
| [text](#text)               | メッセージボックスにテキストを表示します。オプションで名前も表示できます。 |
| [video](#video)             | 動画ファイルを再生します（スキップ設定に対応）。                       |
| [volume](#volume)           | BGM・SE・ボイストラックの音量を設定します。                            |
| [wait](#wait)               | 指定した秒数待機します。                                               |

---

## `anime`

アニメーションの実行

`anime` タグはファイルからアニメーション定義を読み込んで実行します。
単純なトランジションにとどまらず、複雑な視覚エフェクト・キャラクターの動き・ループするシーンアニメーションなどを実現します。

### 基本的な使い方

```
# 同期アニメーションを実行する（完了まで待機）
[anime file="opening_effect.txt"]

# 非同期ループアニメーションを実行する
[anime file="sparkle.txt" async="true" register="my_loop"]

# 登録済みの非同期アニメーションを停止する
[anime stop="true" register="my_loop"]
```

### 引数

| 引数           | 省略可否        | 説明                                               | 備考                                                              |
|---------------|----------------|----------------------------------------------------|-------------------------------------------------------------------|
| `file`        | 可             | アニメーション定義のファイル名。                     | `stop="true"` を使う場合を除き必須です。                            |
| `async`       | 可 (`false`)   | アニメーションを非同期で実行するかどうか。           | `false` の場合、アニメーション完了までスクリプトが待機します。      |
| `register`    | 可             | このアニメーションインスタンスを識別する一意の名前。 | 非同期アニメーションを後から制御・停止するために必要です。          |
| `stop`        | 可 (`false`)   | `true` にすると登録済みアニメーションを停止します。 | `register` 引数が必要です。                                        |
| `showsysbtn`  | 可 (`true`)    | 再生中にシステムボタンを表示するかどうか。           | 同期アニメーションのみ有効です。                                    |
| `showmsgbox`  | 可 (`true`)    | 再生中にメッセージボックスを表示するかどうか。       | 同期アニメーションのみ有効です。                                    |
| `shownamebox` | 可 (`true`)    | 再生中に名前ボックスを表示するかどうか。             | 同期アニメーションのみ有効です。                                    |

### ヒント

**同期 vs. 非同期**:
* **同期（`async="false"`）**: テキストや選択肢が表示される前にアニメーションを見せたいカットシーンに最適です。
* **非同期（`async="true"`）**: 物語が進む間も継続して流れる背景エフェクト（雪や炎のちらつきなど）に最適です。

**インスタンスの管理**:
* `register` 引数を使うと、特定のアニメーションにラベルを付けられます。
* `stop="true"` を使うとき、エンジンはこのラベルで停止するアニメーションを特定します。

**UI 制御**:
* アニメーションがフルスクリーン表示を意図している場合、`showmsgbox="false"` を使うことでダイアログウィンドウを一時的に非表示にし、すっきりした見た目にできます。

---

## `bg`

背景の変更

`bg` タグはなめらかなフェード効果付きで背景画像を変更します。
ビジュアルノベルでシーンを設定するための主要な方法です。

### 基本的な使い方

```
# 1.0秒かけて background.png にトランジション
[bg file="background.png" time="1.0"]

# 黒い画面にフェード（背景を削除）
[bg file="none" time="1.0"]
```

### 引数

| 引数       | 省略可否        | 説明                                      | 備考                                                                          |
|------------|----------------|-------------------------------------------|------------------------------------------------------------------------------|
| `file`     | 不可           | 新しい背景画像のファイル名。               | 背景を削除するには `none` を指定します。                                      |
| `time`     | 可 (`0`)       | フェード効果の時間（秒）。                 | デフォルトは `0.0`（即時変更）。                                              |
| `method`   | 可 (`normal`)  | フェードの方式・スタイル。                 | `normal`、`rule`、`melt` から選択します。                                     |
| `rule`     | 可             | 特定のトランジション用のルール画像ファイル。 | `method` が `rule` または `melt` のときに必要です。                           |
| `x`        | 可 (`0`)       | 背景画像のX軸オフセット。                  | 絶対値（例: `100`）または相対値（例: `r100`）をサポートします。               |
| `y`        | 可 (`0`)       | 背景画像のY軸オフセット。                  | 絶対値（例: `100`）または相対値（例: `r-100`）をサポートします。              |
| `alpha`    | 可 (`255`)     | 背景画像のアルファ値。                     | `0` ～ `255`。                                                                |
| `clear`    | 可 (`false`)   | キャラクターを消去するかどうか。           | `true` にすると全キャラクターが非表示になります。                             |

### トランジション方式（`method`）

適切なトランジションスタイルを選ぶことで、さまざまな雰囲気を演出できます。

| 種類     | 説明                                                                                                                                  |
|----------|--------------------------------------------------------------------------------------------------------------------------------------|
| `normal` | アルファブレンド。デフォルトの方式。旧画像と新画像の間でなめらかなクロスフェードを行います。                                          |
| `rule`   | 1ビット汎用トランジション。グレースケールの「ルール」画像を使って切り替え順序を決定します。                                            |
| `melt`   | 8ビット汎用トランジション。`rule` と同様ですが、トランジション境界にぼかしが入り「溶ける」ような効果が生まれます。                     |

`rule` と `melt` では、ルールマップの暗い部分から明るい部分の順にピクセル単位で切り替わります。

### ヒント

**相対位置指定**:
* 背景を現在の位置から少しずらしたい場合は、`r` プレフィックスを使います。
* 例えば `x="r50"` は、現在のX座標から右に50ピクセル移動します。

**ルール画像とは？**:
* 黒いエリアが最初に、白いエリアが最後にトランジションするグレースケール画像です。
* カスタムのルール画像を作成することで、横方向のワイプ・円形のリビール・より芸術的なパターンなど多彩なエフェクトが実現できます！

---

## `bgm`

BGMの再生

`bgm` タグはBGMトラックを再生します。
音楽はシーンの雰囲気を設定するための重要な手段であり、停止または変更されるまで自動的にループします。

### 基本的な使い方

```
# BGMトラックの再生を開始
[bgm file="field_theme.ogg"]

# 現在のBGMを停止（"none" を使用）
[bgm file="none"]
```

### 引数

| 引数     | 省略可否       | 説明                           | 備考                                        |
|----------|---------------|---------------------------------|---------------------------------------------|
| `file`   | 不可          | 再生する音楽ファイルのファイル名。 | BGMを停止するには `none` を指定します。       |
| `once`   | 可 (`false`)  | ループしない。                  |                                             |

### ヒント

**必須フォーマット**:
* 互換性とパフォーマンスのため、Suika3 の BGM ファイルは **Ogg Vorbis** 形式である必要があります。
* サンプリングレートは **44,100Hz** でなければなりません。

**ループ**:
* BGM はデフォルトでループ再生されるため、長い会話シーンで音楽が突然終わる心配は不要です。

**スムーズなトランジション**:
* 別のトラックが再生中に `[bgm]` を呼び出すと、エンジンが自動的にトランジションを処理します。
* 音楽の音量を調整するには `[volume]` タグを使用します。

**音楽の停止**:
* シーンが終わったり、無音に変わる場合は、`[bgm file="none"]` を使ってプレイヤーの耳を休ませましょう！

---

## `callmacro`

マクロの呼び出し

`callmacro` タグは事前に定義されたマクロを実行します。
キャラクターの登場シーンやUIアニメーションなど、特定のコマンド列をスクリプト全体で何度でも、元のコードを書き直すことなく呼び出せます。

### 基本的な使い方

```
# "kaito_entrance" という名前のマクロを呼び出す
[callmacro name="kaito_entrance"]

# 特定のシーントランジション用マクロを呼び出す
[callmacro name="fade_to_white"]
```

### 引数

| 引数     | 省略可否  | 説明                                 | 備考                                               |
|----------|-----------|--------------------------------------|----------------------------------------------------|
| `name`   | 不可      | 実行するマクロの名前。               | `[defmacro]` タグで定義した名前と一致する必要があります。 |
| `file`   | 可        | マクロが定義されているファイル名。   | 省略すると現在のファイル内のマクロを呼び出します。  |

### ヒント

**効率化**:
* `[callmacro]` を使うことで、メインのストーリースクリプトをシンプルで読みやすく保てます。
* 10行のアニメーションコードの代わりに、1つの明確なコマンドだけが見えるようになります。

**実行フロー**:
* エンジンが `[callmacro]` に到達すると、即座に定義されたマクロにジャンプし、その中のすべてのタグを実行してから、`[callmacro]` タグの次の行に自動的に戻ります。

**モジュラー設計**:
* マクロはゲームの「カスタムタグ」と考えてください。
* キャラクターの登場方法を変更したい場合、`[defmacro]` ブロックを1箇所修正するだけで、すべての `[callmacro]` に反映されます！

---

## `ch`

キャラクターの表示

`ch` タグは各種レイヤーのキャラクター画像を表示・非表示・更新します。
複数のキャラクターと背景の位置・スケール・回転を同時に詳細に制御できます。

### 基本的な使い方

```
# キャラクターを中央に表示
[ch center="chara001.png" time="1.0"]

# 複数のキャラクターを指定位置に表示
[ch left="chara002.png" right="chara003.png" time="0.5"]

# 特定のキャラクターを非表示
[ch center="none" time="1.0"]
```

### 引数

| 引数      | 省略可否        | 説明                                     | 備考                                                  |
|-----------|----------------|------------------------------------------|---------------------------------------------------------|
| `time`    | 可 (`0`)       | トランジションの時間（秒）。              | このタグ内のすべてのレイヤー変更に適用されます。        |
| `method`  | 可 (`normal`)  | フェードの方式・スタイル。                | `normal`、`rule`、`melt`。                              |
| `rule`    | 可             | トランジション用のルール画像ファイル。    | `method` が `rule` または `melt` のときに必要です。     |

#### レイヤーファイル引数

ファイル名を指定してレイヤーに画像を読み込みます。`none` を指定するとレイヤーをアンロード（非表示）します。

| 引数           | 説明                          |
|----------------|-------------------------------|
| `bg`           | 背景レイヤー。                |
| `back`         | 背面中央キャラクター。        |
| `left`         | 左キャラクター。              |
| `left-center`  | 左中央キャラクター。          |
| `center`       | 中央キャラクター。            |
| `right-center` | 右中央キャラクター。          |
| `right`        | 右キャラクター。              |
| `face`         | フェイスキャラクター。        |

#### レイヤーパラメーター引数

上記の各レイヤー（例: `center`）は以下のサフィックスでカスタマイズできます（例: `center-x`、`center-rotate`）。

| サフィックス  | 省略可否      | 説明                       | 備考                                                          |
|-------------|---------------|----------------------------|---------------------------------------------------------------|
| `-x`        | 可 (`0`)      | X位置。                    | 絶対値（例: `100`）または相対値（例: `r50`）をサポート。       |
| `-y`        | 可 (`0`)      | Y位置。                    | 絶対値（例: `100`）または相対値（例: `r-50`）をサポート。      |
| `-a`        | 可 (`255`)    | アルファ値（不透明度）。    | `0`（透明）〜 `255`（不透明）。                               |
| `-scale-x`  | 可 (`1.0`)    | X方向のスケール係数。       | `1.0` が元のサイズ。`r` プレフィックスをサポート。             |
| `-scale-y`  | 可 (`1.0`)    | Y方向のスケール係数。       | `1.0` が元のサイズ。`r` プレフィックスをサポート。             |
| `-center-x` | 可 (`0`)      | 回転の中心（X）。           | 回転エフェクトのピボットポイント。                             |
| `-center-y` | 可 (`0`)      | 回転の中心（Y）。           | 回転エフェクトのピボットポイント。                             |
| `-rotate`   | 可 (`0`)      | 回転角度（度）。            | 正の値は時計回り。`r` プレフィックスをサポート。               |
| `-dim`      | 可 (`false`)  | ディム状態。                | `true` にするとレイヤーが50%暗くなります。                    |

### ヒント

**一括更新**:
* 1つの `[ch]` タグで複数のキャラクターと背景を同時に更新でき、アニメーションを完璧に同期できます。

**相対変形**:
* `bg` タグと同様、すべての数値パラメーターは `r` プレフィックスをサポートします。
* 例えば `center-y="r-50"` とすると、中央キャラクターが現在位置から上に50ピクセル移動します。

---

## `chapter`

チャプター名の設定

`chapter` タグは現在のチャプター名を設定します。
この名前は主にセーブ・ロードメニューやゲーム画面で進捗を表示するために使用され、プレイヤーが物語の進行状況を把握するのに役立ちます。

### 基本的な使い方

```
# ストーリーセグメントの冒頭でチャプター名を設定
[chapter name="第1章: はじまり"]

# 物語の進行に合わせてチャプター名を更新
[chapter name="幕間: 静かな夜"]
```

### 引数

| 引数     | 省略可否  | 説明                               | 備考                                                    |
|----------|-----------|------------------------------------|---------------------------------------------------------|
| `name`   | 不可      | 設定するチャプターの名前。         | この文字列はゲームのシステム変数に保存されます。         |

### ヒント

**セーブデータへの反映**:
* 多くの Suika3 の設定では、ここで設定した文字列が「セーブ」「ロード」スロットに表示されます。
* プレイヤーが物語のどこにいたかを思い出せるような名前を選びましょう！

**一貫性**:
* 新しいシーンやチャプターを開始する `[label]` の直後に `[chapter]` タグを呼び出すのが良い慣習です。

**名前の更新**:
* `[chapter]` は何度でも呼び出せます。
* 呼び出すたびに古いチャプター名が新しいものに上書きされます。

---

## `choose`

Display Selection Options

選択肢の表示

`choose` タグはプレイヤーに最大8つのインタラクティブなボタンを表示します。
選択した項目のテキストを変数に保存します。

### 基本的な使い方

```
# 選択結果を変数に保存
[choose
    text1="赤い薬"
    text2="緑の薬"
    text3="青い薬"
    name="user_choice"
    value1="red"
    value2="green"
    value3="blue"
]
```

### 引数

| 引数              | 省略可否   | 説明                                       | 備考                                               |
|------------------|-----------|--------------------------------------------|----------------------------------------------------|
| `text1`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text2`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text3`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text4`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text5`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text6`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text7`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text8`          | 可        | 各ボタンに表示するテキスト。               | 通常、少なくとも1つのオプションが必要です。        |
| `text<N>-locale` | 可        | 各ボタンに表示するテキスト（ローカライズ）。 | 通常、少なくとも1つのオプションが必要です。       |
| `name`           | 不可      | 結果を保存する変数名。                     | 選択されたオプションのテキストが保存されます。      |
| `value1`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value2`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value3`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value4`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value5`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value6`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value7`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `value8`         | 可        | 結果変数に割り当てる値。                   | 通常、少なくとも1つのオプションが必要です。        |
| `time`           | 可 (`0`)  | タイマー（秒）。                           | `0` の場合はタイマーなし。                         |

### ローカライゼーション

例えば、ユーザーのOS環境が日本語に設定されている場合、`text1` の代わりに `text1-ja` が優先されます。

| サフィックス  | 言語                                     |
|-------------|------------------------------------------|
| -en         | 英語（フォールバック）                   |
| -en-us      | 英語（アメリカ）                         |
| -en-gb      | 英語（イギリス）                         |
| -en-au      | 英語（オーストラリア）                   |
| -en-nz      | 英語（ニュージーランド）                 |
| -fr         | フランス語（フォールバック）             |
| -fr-fr      | フランス語（フランス）                   |
| -fr-ca      | フランス語（カナダ）                     |
| -es         | スペイン語（スペイン、フォールバック）   |
| -es-la      | スペイン語（ラテンアメリカ）             |
| -de         | ドイツ語                                 |
| -it         | イタリア語                               |
| -ru         | ロシア語                                 |
| -el         | ギリシャ語                               |
| -zh         | 中国語（簡体字）                         |
| -zh-tw      | 中国語（繁体字、台湾）                   |
| -ja         | 日本語                                   |
| (サフィックスなし) | フォールバック（開発者が決定）      |

英語のすべての地域ロケールでは、`-en` がデフォルトのフォールバックとして使用されます。`-en-gb` のようにより具体的なバリアントがタグで指定され、ユーザーの地域に最もマッチする場合はそちらが優先されます。同じ仕組みがスペイン語とフランス語にも適用されます。繁体字中国語から簡体字中国語へのフォールバックはありません。

例えば、ユーザーのロケールが `en-AU` の場合、以下の優先順位が適用されます：
* 1. text1-en-au
* 2. text1-en
* 3. text1

以下は現在未対応ですが、対応予定です。

| サフィックス  | 言語                                     |
|-------------|------------------------------------------|
| -ko         | 韓国語                                   |
| -vi         | ベトナム語                               |
| -id         | インドネシア語                           |
| -zh-hk      | 繁体字中国語（香港）                     |
| -pt         | ポルトガル語（フォールバック）           |
| -pt-br      | ポルトガル語（ブラジル）                 |
| -pl         | ポーランド語                             |
| -tr         | トルコ語                                 |
| -ta         | タミル語                                 |
| -te         | テルグ語                                 |
| -kn         | カンナダ語                               |
| -si         | シンハラ語                               |
| -ar         | アラビア語（RTL）                        |
| -fa         | ペルシャ語（RTL）                        |

### ヒント

**分岐ロジック**:
* `[if]` タグを使って保存された値を確認し、複雑な分岐を作成できます。

```
[choose
  name="var1"
  text1="学校へ行く"
  text2="病院へ行く"
  value1="1"
  value2="2"]

[if lhs="${var1}" op="=" rhs="1"]
  # 学校。
[else]
  # 病院。
[endif]
```

**変数の永続性**:
* すべてが文字列として扱われるため、"100" のような数字もテキストとして保存されることを覚えておきましょう。
* Suika3 のロジックタグ（`if` など）はこれらの文字列を比較に利用できます。

---

## `set`

変数の設定

`set` タグは変数名に値を割り当てます。
Suika3 では**すべての変数はテキスト文字列として扱われます**が、`[if]` などの他のタグで数値として比較することも可能です。

### 基本的な使い方

```
# シンプルな文字列を変数に割り当て
[set name="player_name" value="Kaito"]

# 数値ライクな値を設定（文字列として保存される）
[set name="health" value="100"]

# 空文字列を設定して変数をクリア
[set name="flag_event_01" value=""]

# var1 に 1 を加算する
[set name="var1" value1="${var1}" op="+" value2="1"]

```

### 引数

| 引数     | 省略可否       | 説明                                          | 備考                                                               |
|----------|---------------|-----------------------------------------------|---------------------------------------------------------------------|
| `name`   | 不可          | 変数の一意の名前。                            | 互換性のため英数字とアンダースコアを使用してください。               |
| `value`  | 可            | 変数に保存する内容。                          | すべてが文字列として保存されます！                                   |
| `value1` | 可            | 演算のオペランド1。                           |                                                                     |
| `value2` | 可            | 演算のオペランド2。                           |                                                                     |
| `op`     | 可            | 演算コード。（`+`, `-`, `*`, `/`, `//`, `%`） |                                                                     |
| `global` | 可 (`false`)  | フラグをグローバルにする。                    | グローバル変数は「ED1を見た」などのアチーブメントフラグ用です。       |

### ヒント

**文字列の扱い**:
* Suika3 はすべてをテキストとして扱うため、`value="100"` も `value="May"` も内部的には同じように扱われます。
* これらの変数は `${variable_name}` 構文を使って他のタグ（`text` や `if` など）で参照できます。

**フラグ管理**:
* ゲームフラグ（「主人公に会った」など）には `"true"` と `"false"` や `"1"` と `"0"` を使うのが一般的です。
* 一貫性が重要です！`"1"` を使い始めたら、`[if]` チェックで混乱しないよう統一してください。

**変数の命名**:
* 変数名にスペースや特殊記号は避けましょう。`my_variable` は `my variable!` よりずっと安全です。

---

## `click`

クリック待ち

`click` タグはスクリプトの実行を一時停止し、プレイヤーがマウスをクリックするかキーを押すまで待機します。
視覚的な変化の間や大きなトランジションの前にポーズを作るためによく使用されます。

### 基本的な使い方

```
# 背景を変更し、プレイヤーのクリックを待つ
[bg file="sunset.png" time="1.0"]
[click]

# クリック後にキャラクターを表示
[ch center="chara01.png" time="1.0"]
```

### 引数

このタグは引数を取りません。

| 引数 | 省略可否 | 説明 | 備考           |
|------|---------|------|----------------|
| -    | -       | -    | -              |

### ヒント

**タイミングとペース**:
* `[click]` は、会話が続く前に新しい背景や特定のキャラクター表情をプレイヤーに見せたいときに使います。
* メッセージを表示した後に自動的にクリックを待機する `[text]` タグとは異なり、`[click]` は会話以外のシーケンスでの手動フロー制御に使います。

**視覚的なフィードバック**:
* スクリプトが `[click]` タグに達すると、ゲームは静止します。直前のアニメーション（`[bg]` や `[ch]` など）に `time` が設定されていない場合、画面が唐突に止まって見えることがあります。

**時間指定の待機の場合**:
* 時間指定の待機には `[wait]` を使用してください。

---

## `goto`

ラベルへのジャンプ

`goto` タグは NovelML の実行を指定したラベルに即座に移動させます。
ストーリーのフローを制御するための便利なツールで、セクションをスキップしたり前の部分に戻ったりできます。

小さな分岐は `[if]` で実現するようにしてください。

### 基本的な使い方

```
# 朝のシーンの冒頭にジャンプ
[goto name="morning_start"]

# ... スクリプトのこの部分はスキップされます ...

[label name="morning_start"]
[text text="地平線から太陽が昇る。"]
```

### 引数

| 引数     | 省略可否  | 説明                         | 備考                                           |
|----------|-----------|------------------------------|-------------------------------------------------|
| `name`   | 不可      | ジャンプ先のラベル名。       | `[label]` タグで定義した名前と一致する必要があります。 |

### ヒント

**無条件ジャンプ**:
* `[if]` とは異なり、`[goto]` はエンジンがタグに到達した瞬間に必ずターゲットラベルにジャンプします。

**フロー管理**:
* 分岐パスの末尾に `[goto]` を使って、ストーリーを「共通ルート」に戻すことができます。
* 他のロジックと組み合わせてループ（「タイトルに戻る」シーケンスなど）を作成するのにも最適です。

**ファイルを跨いだジャンプ**:
* `[goto]` は通常、現在のスクリプトファイル内でのみ動作します。
* 別のファイルにジャンプしたい場合は `[load]` タグを使用してください！

---

## `defmacro`

マクロの定義

`defmacro` タグはマクロの定義を開始します。
マクロは複数のタグとコマンドを1つの名前付きブロックにまとめ、`[callmacro]` タグを使ってスクリプト全体で再利用できます。

### 基本的な使い方

```
# 特定のキャラクターの登場シーン用マクロを定義
[defmacro name="enter_kaito"]
    [ch center="kaito_smile.png" time="0.5"]
    [text name="Kaito" text="やあ！待たせた？"]
[endmacro]

# スクリプト内で1行で呼び出す
[callmacro name="enter_kaito"]
```

### 引数

| 引数     | 省略可否  | 説明                           | 備考                                              |
|----------|-----------|--------------------------------|---------------------------------------------------|
| `name`   | 不可      | このマクロの一意の名前。       | 後で呼び出すときにマクロを識別するために使います。 |

### ヒント

**定義の終了**:
* すべての `[defmacro]` は対応する `[endmacro]` タグで定義の終わりを示す必要があります。

**コードの再利用**:
* マクロは、特定のUIトランジション、キャラクター固有のビジュアル設定、複雑な音声と映像の組み合わせなど、繰り返しのシーケンスに最適です。

**整理**:
* すべてのマクロをメインスクリプトファイルの冒頭か、スタート時に読み込む別ファイルに定義するのが一般的な慣習です。

**ネストとロジック**:
* マクロ内には `[if]` 文や `[returnmacro]`（条件に基づいてマクロを早期終了するため）を含む、ほぼすべてのタグを組み込めます。

---

## `gui`

GUIの表示

`gui` タグは指定したファイルからGUI（グラフィカルユーザーインターフェース）定義を読み込んで表示します。
メニュー・タイトル画面・カスタムインタラクションパネルの表示に使用されます。

### 基本的な使い方

```
# メインメニューGUIを表示
[gui file="main_menu.txt"]

# カスタムのセーブ・ロード画面を表示
[gui file="save_screen.txt"]
```

### 引数

| 引数     | 省略可否  | 説明                                    | 備考                                                |
|----------|-----------|------------------------------------------|----------------------------------------------------|
| `file`   | 不可      | 読み込むGUI定義のファイル名。            | ファイルはプロジェクトのGUIディレクトリに存在する必要があります。 |

### ヒント

**GUI定義ファイル**:
* `file` 引数は、インターフェースのレイアウト・ボタン・アクションを定義するテキストファイルを指します。
* これらのファイルは、画像の配置とユーザーが操作したときの動作（ラベルへのジャンプや終了など）を指定します。

**フローにおける使い方**:
* `[gui]` タグは通常、タイトル画面などのグラフィカルメニューに使用されます。

**カスタマイズ**:
* GUIは外部ファイルで定義されているため、ゲームの複数のデザインを作成し、このタグで異なるファイルを呼び出すだけで切り替えられます。

---

## `label`

ラベルの定義

`label` タグは `[goto]` や `[load]` などのジャンプコマンドがターゲットにできる特定のスクリプト上の位置を定義します。
物語内のナビゲーションのためのブックマークとして機能します。

### 基本的な使い方

```
# 新しいチャプター開始のラベルを定義
[label name="chapter_01_start"]

# ジャンプコマンドでこのラベルに到達する
[goto name="chapter_01_start"]
```

### 引数

| 引数     | 省略可否  | 説明                           | 備考                                                   |
|----------|-----------|--------------------------------|---------------------------------------------------------|
| `name`   | 不可      | このラベルの一意の名前。       | 大文字・小文字を区別します。スペースや特殊記号は避けてください。 |

### ヒント

**ナビゲーション制御**:
* ラベルは分岐パスを作成するのに役立ちます。
* 例えば、長いジャンプのためにストーリーのセクション冒頭に `label` を配置できます。

**一意の命名**:
* 1つのスクリプトファイル内のすべてのラベル名は一意である必要があります。
* 同じ名前のラベルが2つあると、エンジンがどこにジャンプすべきか判断できなくなります！

**整理**:
* `label1` の代わりに `label_evening_park` のような説明的な名前を使う習慣をつけましょう。
* スクリプトを後で読み返すときに、何が起きているか格段にわかりやすくなります。

---

## `text`

テキストの表示

`text` タグはメッセージボックスにメッセージを表示します。
メインの会話やナレーションを表示し、オプションで名前ボックスにキャラクター名を表示することもできます。

### 基本的な使い方

```
# ナレーションスタイル（名前なし）
[text text="風が木々の間を唸りながら吹き抜けた。"]

# キャラクター会話
[text name="Keith" text="この小さな部屋でずっと待っていたよ。"]
```

### 引数

| 引数              | 省略可否  | 説明                                           | 備考                                              |
|------------------|-----------|------------------------------------------------|---------------------------------------------------|
| `text`           | 不可      | 表示するメッセージ内容。                       |                                                   |
| `text-<locale>`  | 可        | 表示するメッセージ内容（ローカライズ）。        |                                                   |
| `voice`          | 可        | ボイスファイル。                               |                                                   |
| `voice-<locale>` | 可        | ボイスファイル（ローカライズ）。               |                                                   |
| `name`           | 可        | 名前ボックスに表示するキャラクター名。         | 省略すると名前ボックスは通常非表示になります。      |
| `action`         | 可        | NVLモードおよび手動の表示・非表示制御用。      |                                                   |
| `space`          | 可        | NVLモード用。                                  |                                                   |

### ローカライゼーション

例えば、ユーザーのOS環境が日本語に設定されている場合、`text` の代わりに `text-ja` が優先されます。

| サフィックス  | 言語                                     |
|-------------|------------------------------------------|
| -en         | 英語（フォールバック）                   |
| -en-us      | 英語（アメリカ）                         |
| -en-gb      | 英語（イギリス）                         |
| -en-au      | 英語（オーストラリア）                   |
| -en-nz      | 英語（ニュージーランド）                 |
| -fr         | フランス語（フォールバック）             |
| -fr-fr      | フランス語（フランス）                   |
| -fr-ca      | フランス語（カナダ）                     |
| -es         | スペイン語（スペイン、フォールバック）   |
| -es-es      | スペイン語（スペイン、フォールバック）   |
| -es-la      | スペイン語（ラテンアメリカ）             |
| -de         | ドイツ語                                 |
| -it         | イタリア語                               |
| -ru         | ロシア語                                 |
| -el         | ギリシャ語                               |
| -zh-cn      | 中国語（簡体字）                         |
| -zh-tw      | 中国語（繁体字、台湾）                   |
| -ja         | 日本語                                   |
| (サフィックスなし) | フォールバック（開発者が決定）      |

英語のすべての地域ロケールでは、`-en` がデフォルトのフォールバックとして使用されます。`-en-gb` のようにより具体的なバリアントがタグで指定され、ユーザーの地域に最もマッチする場合はそちらが優先されます。同じ仕組みがスペイン語とフランス語にも適用されます。繁体字中国語から簡体字中国語へのフォールバックはありません。

例えば、ユーザーのロケールが `en-GB` の場合、以下の優先順位が適用されます：
* 1. text-en-gb
* 2. text-en
* 3. text

以下は現在未対応ですが、対応予定です。

| サフィックス  | 言語                                     |
|-------------|------------------------------------------|
| -ko         | 韓国語                                   |
| -vi         | ベトナム語                               |
| -id         | インドネシア語                           |
| -zh-hk      | 繁体字中国語（香港）                     |
| -pt         | ポルトガル語（フォールバック）           |
| -pt-br      | ポルトガル語（ブラジル）                 |
| -pl         | ポーランド語                             |
| -tr         | トルコ語                                 |
| -ta         | タミル語                                 |
| -te         | テルグ語                                 |
| -kn         | カンナダ語                               |
| -si         | シンハラ語                               |
| -ar         | アラビア語（RTL）                        |
| -fa         | ペルシャ語（RTL）                        |

### アクション

`text` タグで特殊なパラメーターを使用できます。

```
# メッセージボックスをクリアする。
[text action="clear"]

# メッセージボックスをクリアして表示する。
[text action="new"]

# メッセージボックスを表示する。
[text action="show"]

# メッセージボックスを非表示にする。
[text action="hide"]
```

### NVLモード

configを設定することでNVLモードに入ることができます。

```
[text action="hide"]
[wait time="0.3"] # メッセージボックスが非表示になるまで待機。
[config name="game.novel" value="true"]
[config name="msgbox.image" value="system/message/msgbox-nvl.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="0"]
[config name="msgbox.margin.line" value="60"]
[config name="namebox.enable" value="false"]
[config name="choose.box1.idle" value="system/choose/nvl.png"]
[config name="choose.box1.hover" value="system/choose/nvl.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box2.idle" value="system/choose/nvl.png"]
[config name="choose.box2.hover" value="system/choose/nvl.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="choose.box3.idle" value="system/choose/nvl.png"]
[config name="choose.box3.hover" value="system/choose/nvl.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle-nvl.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover-nvl.anime"]
[config name="click.move" value="true"]
[text action="clear"]
```

configをリセットすることでADVモードに戻ることができます。

```
[text action="hide"]
[wait time="0.3"] # メッセージボックスが非表示になるまで待機。
[config name="game.novel" value="false"]
[config name="msgbox.image" value="system/message/msgbox.png"]
[config name="msgbox.x" value="0"]
[config name="msgbox.y" value="520"]
[config name="msgbox.margin.line" value="40"]
[config name="namebox.enable" value="true"]
[config name="choose.box1.idle" value="system/choose/idle.png"]
[config name="choose.box1.hover" value="system/choose/hover.png"]
[config name="choose.box1.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box1.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box2.idle" value="system/choose/idle.png"]
[config name="choose.box2.hover" value="system/choose/hover.png"]
[config name="choose.box2.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box2.hover_anime" value="system/choose/hover.anime"]
[config name="choose.box3.idle" value="system/choose/idle.png"]
[config name="choose.box3.hover" value="system/choose/hover.png"]
[config name="choose.box3.idle_anime" value="system/choose/idle.anime"]
[config name="choose.box3.hover_anime" value="system/choose/hover.anime"]
[config name="click.move" value="false"]
```

NVLモードでは、テキストメッセージを以下のように制御できます：

```
# 新しいページ。
[text action="clear"]
[text text="こんにちは、これはNVLモードのテストです。"]
[text text="NVLモードはフルスクリーンスタイルのメッセージボックスを持ちます。"]
[text text="デフォルトでは各textタグが改行を行います。"]
[text text="段落を継続するには、"]
[text text="spaceパラメーターを指定してください。" space=" "]

# 新しいページ。
[text action="clear"]
[text text="メッセージボックスを明示的にクリアしてください。"]
```

### ボイス

現在の言語が `en-us` の場合、ボイスファイルは以下の順序で解決されます：

1. `voice-en-us` パラメーター
2. `voice/en-us/` + `voice` パラメーター
3. `voice-en` パラメーター
4. `voice/en/` + `voice` パラメーター
5. `voice` パラメーター

現在の言語が `ja` の場合、ボイスファイルは以下の順序で解決されます：

1. `voice-ja` パラメーター
2. `voice/ja/` + `voice` パラメーター
3. `voice` パラメーター

### ヒント

**自動待機**:
* 他のタグとは異なり、`text` タグはメッセージが完全に表示された後、プレイヤーのクリックを自動的に待機します。
* 会話の各行の後に `[click]` タグを追加する必要はありません！

**変数の使用**:
* `${variable_name}` 構文を使ってテキスト内に変数を埋め込めます。
* 例：`[text text="こんにちは、${player_name}さん！"]` は変数に保存された名前でプレイヤーに挨拶します。

**行の長さ**:
* 1行の最大文字数はプロジェクトの設定を確認してください。
* テキストが長すぎるとメッセージボックスからあふれる可能性があるため、`text` 引数の長さに注意してください！

---

## `if`

条件分岐

`if` タグは特定の条件に基づいて NovelML を分岐させます。
変数や値を比較することで、独自のストーリーパスを作ったり、プレイヤーの過去の選択に反応したりできます。

### 基本的な使い方

```
# 変数が特定の値と等しいか確認
[if lhs="${points}" op="==" rhs="100"]
    [text text="満点！素晴らしい。"]
[elseif lhs="${points}" op=">=" rhs="80"]
    [text text="よくできました！合格です。"]
[else]
    [text text="次は頑張りましょう。"]
[endif]
```

### 引数

| 引数     | 省略可否  | 説明                             | 備考                                           |
|----------|-----------|----------------------------------|------------------------------------------------|
| `lhs`    | 不可      | 条件の左辺。                     | 通常 `${var_name}` のような変数を使います。    |
| `op`     | 不可      | 比較に使う演算子。               | 下記「演算子」テーブルを参照してください。      |
| `rhs`    | 不可      | 条件の右辺。                     | 比較する値や変数。                             |

### 比較演算子（`op`）

2つの値の比較方法を定義するために以下の演算子を使用できます：

| 演算子   | 説明                      |
|----------|---------------------------|
| `===`    | 等しい（文字列）          |
| `==`     | 等しい（数値）            |
| `>`      | より大きい（数値）        |
| `>=`     | 以上（数値）              |
| `<`      | より小さい（数値）        |
| `<=`     | 以下（数値）              |

### ヒント

**ブロックの終了**:
* すべての `[if]` ブロックは必ず `[endif]` タグで終了する必要があります。
* 忘れると、エンジンが条件の終わりを認識できなくなります！

**変数の構文**:
* `lhs` として変数を使う場合は必ず `${}` で囲んでください。
* 例えば `lhs="flag_01"` ではなく `lhs="${flag_01}"` のように記述します。

**文字列と数値の扱い**:
* Suika3 は変数の値を文字列として扱いますが、これらの演算子を使って数値スタイルの比較ができます。
* 値に一貫性を持たせましょう（例：trueに "1"、falseに "0" を使う）。

**複数の分岐**:
* `[if]` と `[endif]` の間に必要なだけ `[elseif]` タグを使って複数の特定条件を確認できます。

---

## `elseif`

追加の条件分岐

`elseif` タグは `[if]` ブロック内に追加の条件を指定します。
直前の `[if]` および前の `[elseif]` の条件がすべて false の場合にのみ評価されます。

### 基本的な使い方

```
[if lhs="${rank}" op="==" rhs="A"]
    [text text="素晴らしい！プロですね。"]
[elseif lhs="${rank}" op="==" rhs="B"]
    [text text="よくできました！続けてください。"]
[elseif lhs="${rank}" op="==" rhs="C"]
    [text text="悪くありませんが、もっとできるはずです。"]
[else]
    [text text="諦めないで！もう一度挑戦しましょう。"]
[endif]
```

### 引数

`[if]` と同じです。[if](#if) も参照してください。

### ヒント

**順次評価**:
* エンジンは条件を上から下の順に確認します。
* `[if]` または `[elseif]` のいずれかの条件が満たされると、そのブロックが実行され、残りのブランチ（他の `[elseif]` や `[else]`）はスキップされます。

**配置**:
* `[elseif]` は必ず `[if]` タグと `[else]` または `[endif]` タグの間に配置する必要があります。
* すべての条件をカバーするために必要なだけ `[elseif]` タグを使用できます！

**効率性**:
* 同じ変数を確認する条件が多い場合、複数の `[if]` ブロックをネストするよりも複数の `[elseif]` タグを使う方がはるかにすっきりして効率的です。

---

## `else`

デフォルトの条件分岐

`else` タグは、直前の `[if]` または `[elseif]` の条件がいずれも満たされなかった場合に実行されるコードブロックを定義します。
分岐ロジックの「デフォルト」パスとして機能します。

### 基本的な使い方

```
[if lhs="${weather}" op="==" rhs="sunny"]
    [text text="素晴らしい天気！"]
[elseif lhs="${weather}" op="==" rhs="rainy"]
    [text text="傘を持っていくべきだ。"]
[else]
    # sunny でも rainy でもない場合（曇りや雪など）に実行される
    [text text="今日は面白い空模様だ。"]
[endif]
```

### 引数

このタグは引数を取りません。

| 引数 | 省略可否 | 説明 | 備考 |
|------|---------|------|------|
| -    | -       | -    | -    |

### ヒント

**最終のキャッチオール**:
* `[if]` や `[elseif]` で明示的にカバーしていないシナリオを `[else]` で処理しましょう。
* ゲームが常に有効なパスを持つことを保証します。

**配置**:
* `[else]` はすべての `[elseif]` タグ（ある場合）の後、`[endif]` タグの直前に配置する必要があります。
* 1つの `[if]` ブロックに `[else]` は1つだけです。

**省略可能**:
* `[else]` ブロックは必須ではありません。
* 条件が満たされず `[else]` もない場合、エンジンはすべてをスキップして `[endif]` の後から処理を続けます。

---

## `endif`

条件分岐の終了

`endif` タグは `[if]` タグで開始された条件ブロックの終わりを示します。
分岐ロジックが完了した後、エンジンに通常のスクリプト実行を再開するよう伝えます。

### 基本的な使い方

```
[if lhs="${love_points}" op=">=" rhs="50"]
    [text text="彼女は温かい笑顔を向けてくれた。"]
[else]
    [text text="彼女は礼儀正しく挨拶した。"]
[endif]

# 上記の結果に関わらず、スクリプトの実行はここから続く
[text text="その日は続いていった..."]
```

### 引数

このタグは引数を取りません。

| 引数 | 省略可否 | 説明 | 備考 |
|------|---------|------|------|
| -    | -       | -    | -    |

### ヒント

**必須の終了タグ**:
* すべての `[if]` タグには対応する `[endif]` が必要です。
* ストーリーのロジックを整理するために対になっています。

**配置**:
* `[endif]` は必ず条件シーケンスの最後、つまり `[elseif]` や `[else]` ブロックの後に配置してください。

**ネスト**:
* `[if]` の中に別の `[if]` を入れる場合、それぞれに独自の `[endif]` が必要です。
* 適切なネストが複雑でバグのないストーリーフラグの秘訣です！

---

## `load`

スクリプトファイルの読み込み

`load` タグは現在のスクリプトを別の NovelML ファイルに切り替えます。
大きなストーリーを複数のチャプターに分割したり、タイトル画面とメインストーリーのような異なるゲームパート間のトランジションに主に使用されます。

### 基本的な使い方

```
# scene02.novel の先頭から読み込んで開始
[load file="scene02.novel"]

# scene02.novel を読み込み、特定のラベルに直接ジャンプ
[load file="scene02.novel" label="chapter2_start"]
```

### 引数

| 引数     | 省略可否  | 説明                                          | 備考                                                   |
|----------|-----------|-----------------------------------------------|--------------------------------------------------------|
| `file`   | 不可      | 読み込む NovelML スクリプトのファイル名。     | プロジェクトのスクリプトディレクトリに有効なファイルである必要があります。 |
| `label`  | 可        | 新しいファイル内でジャンプするターゲットラベル。 | 省略すると最初の行からスクリプトが開始されます。        |

### ヒント

**プロジェクトの整理**:
* ゲーム全体を1つの巨大なファイルに書く代わりに、`[load]` を使って `chapter1.novel`・`chapter2.novel` のような管理しやすいチャンクに分割しましょう。

**即時トランジション**:
* エンジンが `[load]` タグに達すると、現在の NovelML ファイルの実行を即座に停止し、新しいファイルに切り替えます。
* 元のファイルの `[load]` の後に続くコマンドは実行されません。

**グローバルフラグ**:
* 変数の心配は不要です。`[set]` タグで設定した値は新しいスクリプトファイルを読み込んだ後も保持されます！

---

## `se`

効果音の再生

`se` タグは効果音（SE）を再生します。
ドアのノック・足音・UIフィードバックなどの短い音声キューに使用され、シーンに没入感とリアリティを加えます。

### 基本的な使い方

```
# 効果音を一度再生
[se file="door_open.ogg"]

# 現在再生中のすべての効果音を停止
[se file="none"]
```

### 引数

| 引数     | 省略可否       | 説明                               | 備考                                         |
|----------|---------------|------------------------------------|----------------------------------------------|
| `file`   | 不可          | 再生する効果音のファイル名。        | SEの再生を停止するには `none` を指定します。   |
| `loop`   | 可 (`false`)  | 効果音をループするかどうか。        |                                              |

### ヒント

**必須フォーマット**:
* BGMと同様、Suika3 の SE ファイルは **Ogg Vorbis** 形式である必要があります。
* サンプリングレートは高品質と互換性を確保するために **44,100Hz** でなければなりません。

**サウンドのレイヤリング**:
* 効果音は通常 BGM の再生中にも再生できます。
* 独自のオーディオトラックを持つため、音楽を中断しません。

**音量制御**:
* BGM 音量を変えずに効果音の音量だけを調整するには、`track="se"` を指定した `[volume]` タグを使います。

**アンビエンスへの活用**:
* SE は短い音だけでなく、ループするアンビエントサウンド（風や雨など）にも使用できます。
* ループする SE はセーブデータが読み込まれたときに復元されます。

---

## `volume`

音量の設定

`volume` タグは特定のオーディオトラックのサウンド音量を設定します。
BGMが重要な効果音やキャラクターのボイスをかき消さないよう調整するのに最適です。

### 基本的な使い方

```
# BGM音量を50%に設定
[volume track="bgm" volume="0.5"]

# SE音量を最大に設定
[volume track="se" volume="1.0"]

# ボイスをミュート
[volume track="voice" volume="0.0"]
```

### 引数

| 引数     | 省略可否  | 説明                                 | 備考                                      |
|----------|-----------|--------------------------------------|-------------------------------------------|
| `track`  | 不可      | 調整するオーディオトラック。          | 下記「トラック」テーブルを参照してください。 |
| `volume` | 不可      | `0.0` から `1.0` までの音量レベル。   | `0.0` は無音、`1.0` は最大音量。           |
| `time`   | 可 (`0`)  | フェード時間（秒）。                  | `0` は即時変更。                           |

### トラック種別（`track`）

Suika3 はオーディオを3つのメイントラックに分類します：

| トラック名 | 説明                         |
|------------|------------------------------|
| `bgm`      | バックグラウンドミュージック。 |
| `se`       | 効果音およびシステムサウンド。 |
| `voice`    | キャラクターのボイスファイル。 |

### ヒント

**即時変更**:
* `time` が `0` より大きい場合、音量変化は徐々に行われます。
* `time="0"` は即時変更を意味します。

**デフォルトレベル**:
* ゲームの開始時（例えば `start` ラベル内）に希望の音量レベルを設定しておくと、プレイヤーに一貫した体験を提供できます。

---

## `skip`

スキップ状態の設定

`skip` タグはゲーム内のスキップ機能を有効または無効にします。
重要なシネマティックシーケンスをスキップされないようにしたり、特定のシーンを意図したペースで体験させるのに役立ちます。

### 基本的な使い方

```
# スキップ機能を有効にする
[skip enable="true"]

# 重要なシーン中はスキップ機能を無効にする
[skip enable="false"]
```

### 引数

| 引数     | 省略可否  | 説明                                     | 備考                                                   |
|----------|-----------|------------------------------------------|-------------------------------------------------------|
| `enable` | 不可      | スキップ機能を有効にするかどうか。        | `true` でスキップを許可、`false` でブロックします。    |

### ヒント

**シネマティック制御**:
* スキップ機能は通常、起動時のタイトルロゴの前には無効にされます。

**設定の復元**:
* 重要なシーンが終わったら `[skip enable="true"]` を設定することを忘れずに。
* プレイヤーはすでに見たテキストをスキップできる自由を通常は感謝します。

**システムの動作**:
* このタグはエンジンの全体的な「スキップ」状態を制御します。
* プレイヤーがスキップのホットキーを押しても、`enable` が `false` の場合はエンジンが無視します。

---

## `config`

設定値の変更

`config` タグはマークアップから直接ゲームシステムの設定を変更できます。
メッセージボックスの移動やシステムレベルのパラメーターをその場で調整するなど、ゲームのUIを動的に変更するために不可欠です。

### 基本的な使い方

```
# メッセージボックスの位置を変更
[config name="msgbox.x" value="100"]
[config name="msgbox.y" value="200"]

# 特定のシステム設定を更新
[config name="msgbox.font.size" value="24"]
```

### 引数

| 引数     | 省略可否  | 説明                                         | 備考                                                     |
|----------|-----------|----------------------------------------------|----------------------------------------------------------|
| `name`   | 不可      | 変更する設定パラメーターの名前。             | 有効な名前はシステムの設定リストを参照してください。      |
| `value`  | 不可      | パラメーターに割り当てる新しい値。           | 値は文字列として扱われますが、数値を表す場合もあります。   |

### ヒント

**UIのカスタマイズ**:
* `[config]` を使って特定のシーンでメッセージボックスを移動させ、よりシネマティックな雰囲気を演出できます。

**動的な調整**:
* このタグはスクリプトのどこでも呼び出せるため、物語が進むにつれてゲームの「見た目と感触」を変えられます。
* 例えば「フラッシュバック」シーケンス用にUIをシフトするなど。

**パラメーター名**:
* `name` 引数には注意が必要です！
* Suika3 プロジェクト設定で定義された内部設定キーと完全に一致する必要があります。
* [設定の完全なリスト](config.md)も参照してください。

---

## `layer`

レイヤーの直接操作

`layer` タグは特定の画像・テキストレイヤーを直接制御できます。
`[bg]` や `[ch]` などのタグが通常シーンでは使いやすいですが、`[layer]` は任意の個別レイヤーの位置・スケール・回転を独立して精密に変更できます。

### 基本的な使い方

```
# 中央キャラクターレイヤー (chc) に直接画像を読み込む
[layer name="chc" file="heroine_smile.png"]

# 背景 (bg) の位置と不透明度のみを調整する
[layer name="bg" x="100" y="100" alpha="128"]

# フェイスレイヤーを回転させる
[layer name="chf" rotate="45.0" center-x="100" center-y="100"]
```

### 引数

| 引数       | 省略可否     | 説明                                | 備考                                       |
|------------|-------------|-------------------------------------|--------------------------------------------|
| `name`     | 不可        | 対象のレイヤー名。                   | 下記「レイヤー名」テーブルを参照してください。 |
| `file`     | 可          | レイヤーに読み込むファイル名。        | `none` でレイヤーをクリアします。            |
| `x`        | 可 (`0`)    | レイヤーのX座標。                    |                                            |
| `y`        | 可 (`0`)    | レイヤーのY座標。                    |                                            |
| `alpha`    | 可 (`255`)  | レイヤーの不透明度。                 | `0` ～ `255`。                             |
| `scale-x`  | 可 (`1.0`)  | X軸のスケール係数。                  | `1.0` が元のサイズ。                       |
| `scale-y`  | 可 (`1.0`)  | Y軸のスケール係数。                  | `1.0` が元のサイズ。                       |
| `center-x` | 可 (`0`)    | 回転の中心（X）。                    | 回転のピボットポイント。                    |
| `center-y` | 可 (`0`)    | 回転の中心（Y）。                    | 回転のピボットポイント。                    |
| `rotate`   | 可 (`0.0`)  | 回転角度（度数）。                   | 正の値で時計回り。                          |

### レイヤー名一覧（`name`）

Suika3 には豊富なプリセットレイヤーがあります。

以下にすべてのレイヤーの一覧を示します：

|レイヤー名       |説明                                          |
|----------------|----------------------------------------------|
|bg               |背景画像                                      |
|bg2              |背景画像2                                     |
|efb1             |後方エフェクト1                               |
|efb2             |後方エフェクト2                               |
|efb3             |後方エフェクト3                               |
|efb4             |後方エフェクト4                               |
|chb              |中央後方キャラクター                           |
|chb-eye          |中央後方キャラクターの目                      |
|chb-lip          |中央後方キャラクターの口                      |
|chb-fo           |フェードアウト中の中央後方キャラクター         |
|chl              |左キャラクター                                |
|chl-eye          |左キャラクターの目                            |
|chl-lip          |左キャラクターの口                            |
|chl-fo           |フェードアウト中の左キャラクター              |
|chlc             |左中央キャラクター                            |
|chlc-eye         |左中央キャラクターの目                        |
|chlc-lip         |左中央キャラクターの口                        |
|chlc-fo          |フェードアウト中の左中央キャラクター          |
|chr              |右キャラクター                                |
|chr-eye          |右キャラクターの目                            |
|chr-lip          |右キャラクターの口                            |
|chr-fo           |フェードアウト中の右キャラクター              |
|chrc             |右中央キャラクター                            |
|chrc-eye         |右中央キャラクターの目                        |
|chrc-lip         |右中央キャラクターの口                        |
|chrc-fo          |フェードアウト中の右中央キャラクター          |
|chc              |中央キャラクター                              |
|chc-eye          |中央キャラクターの目                          |
|chc-lip          |中央キャラクターの口                          |
|chc-fo           |フェードアウト中の中央キャラクター            |
|msgbox           |メッセージボックス（`[layer]` からは操作不可） |
|namebox          |名前ボックス（`[layer]` からは操作不可）      |
|click            |クリックアニメーション（`[layer]` からは操作不可）|
|eff1             |前方エフェクト1                               |
|eff2             |前方エフェクト2                               |
|eff3             |前方エフェクト3                               |
|eff4             |前方エフェクト4                               |
|chf              |フェイスキャラクター                          |
|chf-eye          |フェイスキャラクターの目                      |
|chf-lip          |フェイスキャラクターの口                      |
|chf-fo           |フェードアウト中のフェイスキャラクター        |
|text1            |テキストレイヤー1                             |
|text2            |テキストレイヤー2                             |
|text3            |テキストレイヤー3                             |
|text4            |テキストレイヤー4                             |
|text5            |テキストレイヤー5                             |
|text6            |テキストレイヤー6                             |
|text7            |テキストレイヤー7                             |
|text8            |テキストレイヤー8                             |
|gui1             |GUIボタン1（`[layer]` からは操作不可）        |
|gui2             |GUIボタン2（`[layer]` からは操作不可）        |
|gui3             |GUIボタン3（`[layer]` からは操作不可）        |
|gui4             |GUIボタン4（`[layer]` からは操作不可）        |
|gui5             |GUIボタン5（`[layer]` からは操作不可）        |
|gui6             |GUIボタン6（`[layer]` からは操作不可）        |
|gui7             |GUIボタン7（`[layer]` からは操作不可）        |
|gui8             |GUIボタン8（`[layer]` からは操作不可）        |
|gui9             |GUIボタン9（`[layer]` からは操作不可）        |
|gui10            |GUIボタン10（`[layer]` からは操作不可）       |
|gui11            |GUIボタン11（`[layer]` からは操作不可）       |
|gui12            |GUIボタン12（`[layer]` からは操作不可）       |
|gui13            |GUIボタン13（`[layer]` からは操作不可）       |
|gui14            |GUIボタン14（`[layer]` からは操作不可）       |
|gui15            |GUIボタン15（`[layer]` からは操作不可）       |
|gui16            |GUIボタン16（`[layer]` からは操作不可）       |
|gui17            |GUIボタン17（`[layer]` からは操作不可）       |
|gui18            |GUIボタン18（`[layer]` からは操作不可）       |
|gui19            |GUIボタン19（`[layer]` からは操作不可）       |
|gui20            |GUIボタン20（`[layer]` からは操作不可）       |
|gui21            |GUIボタン21（`[layer]` からは操作不可）       |
|gui22            |GUIボタン22（`[layer]` からは操作不可）       |
|gui23            |GUIボタン23（`[layer]` からは操作不可）       |
|gui24            |GUIボタン24（`[layer]` からは操作不可）       |
|gui25            |GUIボタン25（`[layer]` からは操作不可）       |
|gui26            |GUIボタン26（`[layer]` からは操作不可）       |
|gui27            |GUIボタン27（`[layer]` からは操作不可）       |
|gui28            |GUIボタン28（`[layer]` からは操作不可）       |
|gui29            |GUIボタン29（`[layer]` からは操作不可）       |
|gui30            |GUIボタン30（`[layer]` からは操作不可）       |
|gui31            |GUIボタン31（`[layer]` からは操作不可）       |
|gui32            |GUIボタン32（`[layer]` からは操作不可）       |

### ヒント

**精密な制御**:
* 専用タグを持たないカスタムエフェクトレイヤー（`eff1` など）に手動で画像を読み込みたい場合に `[layer]` を使います。

**即時更新**:
* `[ch]` や `[bg]` と異なり、`layer` タグは通常即座に画面を更新します。
* これらの変更を時間をかけてアニメーションしたい場合は、`[move]` タグを使ってください！

**レイヤーの重なり順**:
* レイヤーは積み重なっていることを覚えておいてください。
* 例えば `chf`（フェイスキャラクター）は常に `chc`（中央キャラクター）の前面に描画されます。
* この「Zオーダー」を理解することが複雑なビジュアル構成の鍵です。

---

## `move`

レイヤーのアニメーション

`move` タグは特定のレイヤーを指定した時間をかけてアニメーションします。
スライドエフェクトの作成、キャラクターへのズームイン、画面要素の回転など、シーンに躍動感を加えるのに最適です。

### 基本的な使い方

```
# 中央キャラクターを2.0秒かけて新しい位置に移動させる
[move time="2.0" center-x="150" center-y="100"]

# 相対移動: 背景を右に50pxずらす
[move time="1.0" bg-x="r50"]

# レイヤーを回転させながら徐々にフェードアウトさせる
[move time="3.0" face-alpha="0" face-rotate="r360"]
```

### 引数

**共通：**
| 引数               | 省略可否       | 説明                                | 備考                                      |
|--------------------|---------------|-------------------------------------|-------------------------------------------|
| `name`             | 不可          | アニメーションする対象レイヤー。     | 下記「移動可能レイヤー」テーブルを参照。   |
| `time`             | 不可          | アニメーションの継続時間（秒）。     | 小数値に対応（例：`0.5`）。               |
| `async`            | 可 (`false`)  | `true` の場合、非ブロッキングアニメーション。 |                                    |
| `accel`            | 可 (`normal`) | 加速タイプ。                         | いずれか一つ                              |
| (レイヤー)-(サフィックス) | 可       |                                     |                                           |

**(レイヤー)：**
| 引数           | 説明                          |
|----------------|-------------------------------|
| `bg`           | 背景レイヤー。                 |
| `bg2`          | 背景2。                        |
| `back`         | 中央後方キャラクター。         |
| `left`         | 左キャラクター。               |
| `left-center`  | 左中央キャラクター。           |
| `center`       | 中央キャラクター。             |
| `right-center` | 右中央キャラクター。           |
| `right`        | 右キャラクター。               |
| `face`         | フェイスキャラクター。         |

**(サフィックス)：**
| サフィックス  | 省略可否     | 説明                     | 備考                                                          |
|---------------|-------------|--------------------------|---------------------------------------------------------------|
| `-x`          | 可 (`0`)    | X座標。                  | 絶対値（例：`100`）または相対値（例：`r50`）に対応。         |
| `-y`          | 可 (`0`)    | Y座標。                  | 絶対値（例：`100`）または相対値（例：`r-50`）に対応。        |
| `-a`          | 可 (`255`)  | アルファ値（不透明度）。  | `0`（透明）から `255`（不透明）。                            |
| `-scale-x`    | 可 (`1.0`)  | Xスケール係数。           | `1.0` が元のサイズ。`r` プレフィックスに対応。               |
| `-scale-y`    | 可 (`1.0`)  | Yスケール係数。           | `1.0` が元のサイズ。`r` プレフィックスに対応。               |
| `-center-x`   | 可 (`0`)    | 回転の中心（X）。         | 回転エフェクトのピボットポイント。                           |
| `-center-y`   | 可 (`0`)    | 回転の中心（Y）。         | 回転エフェクトのピボットポイント。                           |
| `-rotate`     | 可 (`0`)    | 回転角度（度数）。        | 正の値で時計回り。`r` プレフィックスに対応。                 |
| `-dim`        | 可 (`false`)| ディム状態。              | `true` の場合、レイヤーが50%暗く描画されます。               |

### ヒント

**非ブロッキングアニメーション（`async="true"`）**:
* `[move]` 開始直後にスクリプトが次のコマンドへ進みます。
* アニメーション終了まで待機させたい場合は、同じ `time` 値の `[wait]` タグを続けてください。

**相対変換**:
* `r` プレフィックス（例：`x="r100"`）は、絶対座標を計算せずにキャラクターを「ジャンプ」させたり「揺らす」など繰り返しの動作に非常に便利です。

**視覚的な仕上げ**:
* `scale-x` と `scale-y` を `move` と組み合わせると、ドラマチックなクローズアップのためにキャラクターの顔を「ズームイン」するエフェクトが作れます！

---

## `pencil`

ペンシル

レイヤーにテキストを描画します。

### 基本的な使い方

```
[pencil layer="bg" font-size="30" text="Hello, World!"]
```

### 引数

| 引数            | 省略可否          | 説明                        |
|----------------|------------------|-----------------------------|
| text           | 不可              | 描画するテキスト。           |
| layer          | 可 (`text1`)      | レイヤー名。                 |
| font-type      | 可 (`0`)          | フォント選択。（0〜3）       |
| font-size      | 可 (`16`)         | フォントサイズ。             |
| color          | 可 (`#000000`)    | フォントカラー。             |
| outline-width  | 可 (`0`)          | フォントのアウトライン幅。   |
| outline-color  | 可 (`#ffffff`)    | フォントのアウトラインカラー。|
| line-margin    | 可                | 行マージン。                 |
| char-margin    | 可 (`0`)          | 文字マージン。               |
| x              | 可 (`0`)          | 描画エリアのX座標。          |
| y              | 可 (`0`)          | 描画エリアのY座標。          |
| width          | 可                | 描画エリアの幅。             |
| height         | 可                | 描画エリアの高さ。           |

## 対応レイヤー名

|レイヤー名       |説明                      |
|----------------|--------------------------|
|bg               |背景画像                  |
|bg2              |背景画像2                 |
|efb1             |後方エフェクト1           |
|efb2             |後方エフェクト2           |
|efb3             |後方エフェクト3           |
|efb4             |後方エフェクト4           |
|chb              |中央後方キャラクター      |
|chl              |左キャラクター            |
|chlc             |左中央キャラクター        |
|chr              |右キャラクター            |
|chrc             |右中央キャラクター        |
|chc              |中央キャラクター          |
|eff1             |前方エフェクト1           |
|eff2             |前方エフェクト2           |
|eff3             |前方エフェクト3           |
|eff4             |前方エフェクト4           |
|chf              |フェイスキャラクター      |
|text1            |テキストレイヤー1         |
|text2            |テキストレイヤー2         |
|text3            |テキストレイヤー3         |
|text4            |テキストレイヤー4         |
|text5            |テキストレイヤー5         |
|text6            |テキストレイヤー6         |
|text7            |テキストレイヤー7         |
|text8            |テキストレイヤー8         |

---

## `returnmacro`

マクロからの復帰

`returnmacro` タグは現在のマクロを即座に終了し、元の `[callmacro]` タグの次の行にスクリプト実行を返します。
`[if]` ブロック内の特定の条件に基づいてマクロを早期終了するのに特に便利です。

### 基本的な使い方

```
[defmacro name="check_item"]
    [if lhs="${has_key}" op="==" rhs="false"]
        [text text="ドアに鍵がかかっています。"]
        [returnmacro]
    [endif]

    # has_key が true の場合のみここが実行される
    [text text="鍵でドアを開けました！"]
[endmacro]
```

### 引数

このタグには引数がありません。

| 引数 | 省略可否 | 説明 | 備考 |
|------|---------|------|------|
| -    | -       | -    | -    |

### ヒント

**早期終了**:
* 特定の条件が満たされた場合にマクロの残りのコマンドをスキップするために、`[if]` ブロック内で `[returnmacro]` を使います。
* これによりマクロを柔軟かつ強力にできます！

**暗黙のリターン**:
* 実際にはすべてのマクロの末尾に `[returnmacro]` を置く必要はありません。
* エンジンが `[endmacro]` タグに到達すると、自動的にメインスクリプトに戻ります。

**フロー制御**:
* このタグは*現在の*マクロのみを終了することを覚えておいてください。ゲーム全体を停止したり別のラベルにジャンプしたりするわけではなく、マクロが呼び出された箇所に戻るだけです。

---

## `video`

動画の再生

`video` タグは画面で動画ファイルを再生します。
オープニングシネマティクス、トランジションカットシーン、フルモーションビデオとして表現するのが最適な高インパクトなビジュアルエフェクトに最適です。

### 基本的な使い方

```
# オープニング動画を再生する（スキップ不可）
[video file="opening.mp4"]

# プレイヤーがクリックでスキップできる短いカットシーンを再生する
[video file="cutscene01.mp4" skippable="true"]
```

### 引数

| 引数         | 省略可否      | 説明                                         | 備考                                                             |
|-------------|--------------|----------------------------------------------|------------------------------------------------------------------|
| `file`      | 不可          | 再生する動画のファイル名。                    | サポートされているフォーマット（例：.mp4）である必要があります。  |
| `skippable` | 可 (`false`) | プレイヤーのクリックで動画をスキップできるか。 | `false` でプレイヤーに動画全体を視聴させます。                   |

### ヒント

**ファイルサポート**:
* 動画ファイルは .mp4（H.264 + AAC）フォーマットを使用してください。
* 32ビットWindowsをサポートしたい場合は、.mp4と並べて .wmv ファイルを用意し、拡張子を省略してください（例：`[video file="opening"]`）。

**トランジション**:
* 動画が再生終了（またはスキップ）されると、エンジンは自動的にスクリプトの次のコマンドへ進みます。
* `[video]` タグの後に `[bg]` タグを続けると、動画終了後に画面が意図した状態になります。

**動画内のオーディオ**:
* ほとんどの動画ファイルには独自のオーディオトラックが含まれています。
* このオーディオは再生中の `[bgm]` と同時に流れます。
* 音声付き動画を開始する前に `[bgm file="none"]` でBGMを停止することを検討してください！

---

## `wait`

時間待機

`wait` タグは指定した時間だけ NovelML の実行を一時停止します。
ビジュアルトランジションのペース制御、ドラマチックな間の演出、プレイヤー入力なしでエフェクトのタイミングを合わせるのに不可欠です。

### 基本的な使い方

```
# 次のコマンドの前に1.5秒間一時停止する
[wait time="1.5"]

# キャラクター切り替えの間に短い間を作る
[ch center="chara01_surprised.png" time="0.5"]
[wait time="1.0"]
[text text="彼女は自分の目が信じられなかった。"]
```

### 引数

| 引数           | 省略可否      | 説明                         | 備考                               |
|---------------|--------------|------------------------------|-------------------------------------|
| `time`        | 不可          | 待機する秒数。               | 小数値に対応（例：`0.5`）。         |
| `hidemsgbox`  | 可 (`false`) | メッセージボックスを強制非表示にする。 |                                |
| `hidenamebox` | 可 (`false`) | 名前ボックスを強制非表示にする。       |                                |

### ヒント

**非インタラクティブな一時停止**:
* プレイヤーの操作を待つ `[click]` と異なり、`[wait]` は時間が経過すると自動的に進みます。
* これは「自動再生」セグメントやタイミングが重要なビジュアルシーケンスに最適です。

**アニメーションとの組み合わせ**:
* `[ch]` や `[bg]` タグに `time` 引数を指定した場合、アニメーション再生中にエンジンは即座に次のコマンドへ進みます。
* アニメーション終了まで（またはドラマチックな効果のためにさらに）スクリプトを停止させたい場合は、アニメーションの後に `[wait]` を使います。

**ユーザー体験**:
* 視覚的な理由なしに `[wait]` の時間を長くしすぎないよう注意してください（3秒以上など）。プレイヤーがゲームがフリーズしたと思う可能性があります！

