webTaleKit タグリファレンス

概要

webTaleKitは、TypeScript/JavaScriptベースのビジュアルノベルエンジンです。このリファレンスでは、.sceneファイルで使用できるすべてのタグとその属性について詳しく説明しています。

各タグは特定の機能を提供し、組み合わせることで豊かなインタラクティブストーリーを作成できます。

🌟 グローバル属性

if属性:すべてのタグでif="条件式"を使用できます。条件がtrueの場合のみそのタグが実行されます。

<text>
基本的なテキスト表示を行います。ゲームの地の文や説明文の表示に使用されます。

属性

speed
number (省略可)
テキストの表示速度(ミリ秒)。デフォルト: 25
time
number (省略可)
表示後の待機時間(ミリ秒)
get / post / put / delete
string (省略可)
HTTPリクエストのURL。子要素でheader、data、then、errorを指定

マークアップタグ

<color value="色名">
文字色指定
文字の色を変更します(red, blue, #ff0000など)
<b>
太字
テキストを太字で表示します
<i>
斜体
テキストを斜体で表示します
<ruby text="ルビ">
ルビ
漢字等にルビを振ります
<br>
改行 + 待機
テキストを改行し、クリック待ちします(waitタグのエイリアス)
<wait time="ミリ秒" nw />
一時停止
テキスト表示中に指定時間待機します。timeを省略するとクリック待ち。nw属性で待機スキップ

使用例

<text>これは基本的なテキストです。</text>

<text speed="10">ゆっくりと表示されるテキストです。</text>

<text>変数も使用できます: {{playerName}}</text>

<!-- マークアップタグの使用例 -->
<text>
  <color value="red">赤い文字</color>や<b>太字</b>、<i>斜体</i>も使えます。
  <br>改行も簡単です。
</text>

<!-- ルビの使用例 -->
<text>
  <ruby text="かんじ">漢字</ruby>にルビを振ることができます。
</text>

<!-- テキスト内での待機 -->
<text>
  こんにちは。<wait time="1000" />お元気ですか?
</text>

<!-- 複合的な使用例 -->
<text>
  <color value="blue"><b>重要な</b></color>お知らせがあります。<br>
  <wait time="500" /><i>しばらくお待ちください...</i>
</text>

<!-- HTTPリクエストの使用例 -->
<text get="https://api.example.com/data">
  <progress>データを読み込み中...</progress>
  <header>
    <content-type>application/json</content-type>
    <authorization>Bearer token</authorization>
  </header>
  <data>
    <query>example</query>
  </data>
  <then>データの読み込みが完了しました。</then>
  <error>データの読み込みに失敗しました。</error>
</text>

<!-- ifグローバル属性の使用例 -->
<text if="playerLevel >= 10">レベル10以上のプレイヤーのみに表示されるメッセージです。</text>

<text if="hasItem('key')">鍵を持っている場合のメッセージです。</text>

<text if="gameMode === 'hard'">ハードモード専用のヒントです。</text>

使用上の注意

  • マークアップタグは適切に閉じてください(<b>...</b>)
  • マークアップタグはネストすることができます
  • {{variable}}形式でJavaScript変数を展開できます
  • speedが小さいほど文字表示が速くなります
  • colorタグのvalue属性には色名(red, blue)やHEXコード(#ff0000)が使用できます
  • <br>タグは改行と同時にクリック待ちが発生します(<wait />のエイリアス)
  • waitタグのnw属性を指定すると、待機をスキップできます
  • HTTPリクエスト機能を使用すると、API連携やAI統合が可能になります
  • HTTPレスポンスの結果は、sceneFile.resに格納されます
  • if属性:条件がtrueの場合のみテキストが表示されます(例: if="playerLevel >= 5")
<say>
キャラクターの台詞を表示します。キャラクター名と音声ファイルを指定できます。

属性

name
string (必須)
話者の名前
voice
string (省略可)
音声ファイルのパス
speed
number (省略可)
テキストの表示速度。デフォルト: 25

使用例

<say name="主人公">こんにちは!</say>

<say name="ヒロイン" voice="./voice/heroine_01.wav">
  お疲れ様でした。
</say>

<say name="{{characterName}}" speed="50">
  変数も使用できます。
</say>

<!-- ifグローバル属性の使用例 -->
<say name="店主" if="playerMoney >= 100">
  いらっしゃいませ!何かお買い物ですか?
</say>

<say name="警備員" if="hasPermission === false">
  ここから先は立ち入り禁止です。
</say>

使用上の注意

  • nameは必須属性です
  • voiceで指定した音声ファイルは台詞と同時に再生されます
  • textタグと同様にマークアップタグが使用できます
  • if属性:条件がtrueの場合のみ台詞が表示されます(例: if="characterPresent")
<choice>
プレイヤーが選択できる選択肢を表示します。ストーリーの分岐に使用されます。

属性

prompt
string (省略可)
選択肢の前に表示するプロンプトテキスト

子要素: <item>

label
string (必須)
選択肢に表示するテキスト
onSelect
string (省略可)
選択時のイベント識別子

使用例

<choice prompt="どちらを選びますか?">
  <item label="はい" onSelect="yes">
    <say name="主人公">はいを選びました。</say>
  </item>
  <item label="いいえ" onSelect="no">
    <say name="主人公">いいえを選びました。</say>
  </item>
</choice>

<choice>
  <item label="次のシーンへ">
    <route to="next_scene" />
  </item>
</choice>

<!-- ifグローバル属性の使用例 -->
<choice prompt="何をしますか?" if="canMakeChoice">
  <item label="戦う">
    <text>戦闘を開始します。</text>
  </item>
  <item label="逃げる">
    <text>逃走します。</text>
  </item>
</choice>

使用上の注意

  • 各itemには任意のタグを含めることができます
  • 選択後は自動的に選択肢が非表示になります
  • promptが空文字列の場合、プロンプトは表示されません
  • if属性:条件がtrueの場合のみ選択肢が表示されます(例: if="allowChoices")
<show>
画像(背景、キャラクター、エフェクトなど)を画面に表示します。

属性

src
string (必須)
画像ファイルのパス
name
string (省略可)
画像の識別名
mode
string (省略可)
表示モード: bg, chara, cutin, cg, effect
pos
string (省略可)
位置指定: left/center/right:top/middle/bottom
x, y
number (省略可)
詳細な座標指定(ピクセル)
width, height
number (省略可)
画像のサイズ(ピクセル)
transition
string (省略可)
表示エフェクト: fade
duration
number (省略可)
エフェクトの時間(ミリ秒)
opacity
number (省略可)
透明度(0.0-1.0)
sepia
number (省略可)
セピア効果の強度
mono
boolean (省略可)
モノクロ効果
blur
number (省略可)
ぼかし効果の強度
look
boolean (省略可)
画像を左右反転して表示
entry
object (省略可)
表示開始の遅延設定 {time: 秒数, wait: boolean}

使用例

<!-- 背景画像の表示 -->
<show src="./resource/background/forest.jpg" mode="bg" />

<!-- キャラクターの表示 -->
<show src="./resource/chara/hero.png" name="主人公" pos="left:middle" />

<!-- フェードイン効果付きで表示 -->
<show src="./resource/chara/heroine.png" name="ヒロイン" pos="right:middle" 
      transition="fade" duration="2000" />

<!-- エフェクト適用 -->
<show src="./resource/effect/sparkle.png" name="キラキラ" 
      opacity="0.7" sepia="0.3" />

<!-- 座標指定 -->
<show src="./resource/item/sword.png" name="剣" x="100" y="200" />

<!-- 左右反転表示 -->
<show src="./resource/chara/hero.png" name="主人公" pos="left:middle" look="true" />

<!-- 遅延表示 -->
<show src="./resource/chara/surprise.png" name="驚き" pos="center:middle" 
      entry="{time: 2, wait: true}" />

<!-- ifグローバル属性の使用例 -->
<show src="./resource/chara/angry.png" name="主人公" pos="left:middle" 
      if="playerEmotion === 'angry'" />

<show src="./resource/item/treasure.png" name="宝箱" pos="center:middle" 
      if="foundTreasure" />

使用上の注意

  • mode="cutin"の場合、pos="center:middle"が強制されます
  • mode="cg"の場合、画面全体に表示され他の画像は一時的に隠されます
  • nameを指定することで、後からhideやmovetoで操作できます
  • posとx,yの両方を指定した場合、x,yが優先されます
  • lookをtrueにすると画像が左右反転されます(キャラの向きを変える時に便利)
  • entryで表示開始を遅延できます(演出効果に有効)
  • if属性:条件がtrueの場合のみ画像が表示されます(例: if="showCharacter")
<hide>
showで表示した画像を非表示にします。

属性

name
string (必須)
非表示にする画像の識別名
mode
string (省略可)
非表示モード: cg(CGモードの終了)
transition
string (省略可)
非表示エフェクト: fade
duration
number (省略可)
エフェクトの時間(ミリ秒)

使用例

<!-- 即座に非表示 -->
<hide name="主人公" />

<!-- フェードアウト効果 -->
<hide name="ヒロイン" transition="fade" duration="1500" />

<!-- CGモードの終了 -->
<hide mode="cg" />

使用上の注意

  • nameで指定する識別名は、showで指定したものと一致する必要があります
  • mode="cg"の場合、nameは不要で、CGモードが終了され元の画像が復元されます
<sound>
BGMや効果音の再生・停止・一時停止を制御します。

属性

src
string (省略可)
音声ファイルのパス
name
string (省略可)
音声の識別名
mode
string (省略可)
音声モード: bgm, se
play
boolean (省略可)
再生開始
stop
boolean (省略可)
再生停止
pause
boolean (省略可)
再生一時停止
loop
boolean (省略可)
ループ再生

使用例

<!-- BGMの再生 -->
<sound src="./resource/bgm/peaceful.mp3" mode="bgm" play loop />

<!-- 効果音の再生 -->
<sound src="./resource/se/door.wav" play />

<!-- BGMの停止 -->
<sound mode="bgm" stop />

<!-- 特定の音声の一時停止 -->
<sound name="環境音" pause />

使用上の注意

  • mode="bgm"の場合、以前のBGMは自動的に停止されます
  • loopを指定すると、音声が無限にループ再生されます
  • play, stop, pauseは排他的に使用してください
<jump>
シナリオ内の指定した行番号にジャンプします。

属性

index
number (必須)
ジャンプ先の行番号(0から開始)

使用例

<!-- 10行目にジャンプ -->
<jump index="10" />

<!-- 選択肢での使用例 -->
<choice prompt="もう一度見ますか?">
  <item label="はい">
    <jump index="5" />
  </item>
  <item label="いいえ">
    <text>終了します。</text>
  </item>
</choice>

使用上の注意

  • 行番号は0から開始します
  • 存在しない行番号を指定するとエラーになります
  • 後方にジャンプした場合、間の行は再実行されません
<route>
別のシーンファイルに遷移します。

属性

to
string (必須)
遷移先のシーンファイル名

使用例

<!-- タイトルシーンに遷移 -->
<route to="title" />

<!-- 次のシーンに遷移 -->
<route to="chapter2" />

<!-- 選択肢での使用例 -->
<choice>
  <item label="タイトルに戻る">
    <route to="title" />
  </item>
</choice>

使用上の注意

  • 遷移前に現在のシーンのcleanUp関数が呼ばれます
  • BGMは自動的に停止され、新しいシーンのBGMが再生されます
  • 画面は新しいシーンの設定でリセットされます
<if>
条件に基づいてシナリオを分岐します。JavaScript式を条件として使用できます。

属性

condition
string (必須)
評価するJavaScript式

子要素

<then>
element
条件がtrueの場合に実行される内容
<else>
element (省略可)
条件がfalseの場合に実行される内容

使用例

<if condition="playerScore >= 80">
  <then>
    <say name="先生">素晴らしい成績ですね!</say>
  </then>
  <else>
    <say name="先生">もう少し頑張りましょう。</say>
  </else>
</if>

<if condition="hasKey === true">
  <then>
    <text>扉を開けることができます。</text>
    <route to="inside_room" />
  </then>
  <else>
    <text>鍵が必要です。</text>
  </else>
</if>

使用上の注意

  • conditionには任意のJavaScript式を記述できます
  • シーンのscript部分で定義した変数や関数を参照できます
  • elseは省略可能です
  • ifは入れ子にすることができます
<call>
JavaScript関数を実行します。ゲームの状態変更や複雑な処理に使用されます。

属性

method
string (省略可)
実行するJavaScriptコード
func
string (省略可)
実行する関数呼び出し(methodの別名)

使用例

<!-- 変数の設定 -->
<call method="playerScore = 100" />

<!-- 関数の呼び出し -->
<call func="saveGame()" />

<!-- 複雑な処理 -->
<call method="
  if (inventory.includes('key')) {
    hasKey = true;
    removeItem('key');
  }
" />

使用上の注意

  • methodとfuncは同じ機能です(互換性のため両方サポート)
  • シーンのscript部分で定義した変数や関数にアクセスできます
  • エラーが発生した場合はコンソールに出力されます
<moveto>
表示中の画像を指定した位置に移動します。アニメーション効果付きです。

属性

name
string (必須)
移動させる画像の識別名
x
number (必須)
移動先のX座標
y
number (必須)
移動先のY座標
duration
number (省略可)
移動にかかる時間(秒)。デフォルト: 1

使用例

<!-- 画像を表示 -->
<show src="./resource/chara/hero.png" name="主人公" pos="left:middle" />

<!-- 中央に移動(2秒かけて) -->
<moveto name="主人公" x="400" y="300" duration="2" />

<!-- 素早く移動 -->
<moveto name="主人公" x="100" y="100" duration="0.5" />

使用上の注意

  • 移動対象の画像は事前にshowで表示されている必要があります
  • 移動中は他のコマンドも並行して実行されます
  • 存在しないnameを指定してもエラーにはなりません
<wait>
指定した時間だけ待機します。またはクリック待ちを行います。

属性

time
number (省略可)
待機時間(ミリ秒)
wait
number (省略可)
待機時間(timeの別名)

使用例

<!-- 2秒待機 -->
<wait time="2000" />

<!-- クリック待ち -->
<wait />

<!-- テキスト内での使用 -->
<text>
  こんにちは。<wait time="1000" />お元気ですか?
</text>

使用上の注意

  • timeまたはwaitを省略した場合、クリック待ちになります
  • timeとwaitは同じ機能です
  • テキスト内のwaitタグはnw属性で無待機にできます
<dialog>
モーダルダイアログを表示します。ユーザーとのインタラクションやメニュー、確認画面の表示に使用されます。

属性

id
string (省略可)
ダイアログの識別ID
template
string (省略可)
カスタムテンプレートファイルのパス

子要素

<prompt>
element (必須)
ダイアログに表示するメッセージ(文字列またはテキスト要素)
<actions>
element (必須)
ダイアログのアクション群(action要素を含む)

<action>要素の属性

id
string (必須)
アクションの識別ID
label
string (必須)
ボタンに表示するラベル
value
string (省略可)
アクションの値

使用例

<!-- 基本的なダイアログ -->
<dialog id="confirm">
  <prompt>本当に削除しますか?</prompt>
  <actions>
    <action id="yes" label="はい" value="delete">
      <call method="deleteData()" />
      <text>削除しました。</text>
    </action>
    <action id="no" label="いいえ" value="cancel">
      <text>キャンセルしました。</text>
    </action>
  </actions>
</dialog>

<!-- 選択肢ダイアログ -->
<dialog id="choice">
  <prompt>どの色が好きですか?</prompt>
  <actions>
    <action id="red" label="赤" value="red">
      <text>赤は情熱的な色ですね。</text>
    </action>
    <action id="blue" label="青" value="blue">
      <text>青は落ち着いた色です。</text>
    </action>
    <action id="green" label="緑" value="green">
      <text>緑は自然を感じさせます。</text>
    </action>
  </actions>
</dialog>

<!-- カスタムテンプレート使用 -->
<dialog id="custom" template="./src/screen/custom.html">
  <prompt>カスタムダイアログです</prompt>
  <actions>
    <action id="ok" label="OK">
      <text>カスタムダイアログを閉じます。</text>
    </action>
  </actions>
</dialog>

<!-- ネストしたダイアログ -->
<dialog id="main">
  <prompt>メニューを選択してください</prompt>
  <actions>
    <action id="settings" label="設定">
      <dialog id="settings">
        <prompt>設定項目を選択してください</prompt>
        <actions>
          <action id="sound" label="音量設定">
            <text>音量設定画面を開きます。</text>
          </action>
          <action id="display" label="表示設定">
            <text>表示設定画面を開きます。</text>
          </action>
        </actions>
      </dialog>
    </action>
  </actions>
</dialog>

使用上の注意

  • ダイアログは画面の中央にモーダル表示されます
  • actionsの各actionには必ずidとlabelを指定してください
  • ダイアログが表示されている間、背景の操作はできません
  • promptには文字列またはtext要素を指定できます
  • templateを指定すると、カスタムデザインのダイアログが使用できます
  • ダイアログ内でさらにダイアログを開くことができます(ネスト可能)
  • アクション選択後は自動的にダイアログが閉じられます
  • 選択されたアクションのIDは戻り値として取得できます
<newpage>
画面をクリアして新しいページを開始します。背景画像のみが残ります。

使用例

<!-- ページをクリア -->
<newpage />

<!-- 新しい場面の開始 -->
<text>場面が変わりました。</text>

使用上の注意

  • すべてのキャラクターと効果が削除されます
  • 背景画像とテキスト表示領域はクリアされます
  • 新しい場面を開始する際に使用します
↑ TOPへ