Suika3 タグリファレンス

目次

---

anime

アニメーションの実行

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

基本的な使い方

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

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

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

引数

ヒント

同期 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"]

引数

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

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

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

ヒント

相対位置指定:

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

ルール画像とは？:

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

---

bgm

BGMの再生

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

基本的な使い方

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

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

引数

ヒント

必須フォーマット:

• 互換性とパフォーマンスのため、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"]

引数

ヒント

効率化:

• [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"]

引数

レイヤーファイル引数

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

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

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

ヒント

一括更新:

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

相対変形:

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

---

chapter

チャプター名の設定

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

基本的な使い方

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

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

引数

ヒント

セーブデータへの反映:

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

一貫性:

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

名前の更新:

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

---

choose

Display Selection Options

選択肢の表示

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

基本的な使い方

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

引数

ローカライゼーション

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

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

例えば、ユーザーのロケールが en-AU の場合、以下の優先順位が適用されます：

• 1. text1-en-au
• 1. text1-en
• 1. text1

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

ヒント

分岐ロジック:

• [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"]

引数

ヒント

文字列の扱い:

• 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="地平線から太陽が昇る。"]

引数

ヒント

無条件ジャンプ:

• [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"]

引数

ヒント

定義の終了:

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

コードの再利用:

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

整理:

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

ネストとロジック:

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

---

gui

GUIの表示

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

基本的な使い方

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

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

引数

ヒント

GUI定義ファイル:

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

フローにおける使い方:

• [gui] タグは通常、タイトル画面などのグラフィカルメニューに使用されます。

カスタマイズ:

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

---

label

ラベルの定義

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

基本的な使い方

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

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

引数

ヒント

ナビゲーション制御:

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

一意の命名:

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

整理:

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

---

text

テキストの表示

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

基本的な使い方

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

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

引数

ローカライゼーション

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

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

例えば、ユーザーのロケールが en-GB の場合、以下の優先順位が適用されます：

• 1. text-en-gb
• 1. text-en
• 1. text

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

アクション

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]

引数

比較演算子（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] または [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"]

引数

ヒント

プロジェクトの整理:

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

即時トランジション:

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

グローバルフラグ:

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

---

se

効果音の再生

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

基本的な使い方

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

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

引数

ヒント

必須フォーマット:

• 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）

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

ヒント

即時変更:

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

デフォルトレベル:

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

---

skip

スキップ状態の設定

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

基本的な使い方

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

# 重要なシーン中はスキップ機能を無効にする
[skip enable="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"]

引数

ヒント

UIのカスタマイズ:

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

動的な調整:

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

パラメーター名:

• name 引数には注意が必要です！
• Suika3 プロジェクト設定で定義された内部設定キーと完全に一致する必要があります。
• 設定の完全なリストも参照してください。

---

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）

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

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

ヒント

精密な制御:

• 専用タグを持たないカスタムエフェクトレイヤー（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"]

引数

共通：

(レイヤー)：

(サフィックス)：

ヒント

非ブロッキングアニメーション（async="true"）:

• [move] 開始直後にスクリプトが次のコマンドへ進みます。
• アニメーション終了まで待機させたい場合は、同じ time 値の [wait] タグを続けてください。

相対変換:

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

視覚的な仕上げ:

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

---

pencil

ペンシル

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

基本的な使い方

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

引数

対応レイヤー名

---

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"]

引数

ヒント

ファイルサポート:

• 動画ファイルは .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="彼女は自分の目が信じられなかった。"]

引数

ヒント

非インタラクティブな一時停止:

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

アニメーションとの組み合わせ:

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

ユーザー体験:

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