紙芝居DSL 2.0から3.2への変更履歴

旧Text Assetの互換期間

次の3.1構文は3.2でもno-opにならず、表示・更新を含めて動作します。

旧構文を含む台本は実行を継続し、開発者コンソールへプロジェクトごとに一度LEGACY_TEXT_ASSET_DEPRECATED警告を出します。旧Text Assetは少なくとも3.2系列で維持し、削除する場合は将来のメジャーバージョンで事前に告知します。

通常の画像・音声アセットと、アクターに従属する吹き出しのsay／thinkはこのdeprecated警告の対象外です。

SVG Textへの段階移行

移行先はnpmで公開した@kubohiroya/turbowarp-svg-text@0.1.0です。TM Kamishibai 3.2.0へ組み込まれているため、既存台本の旧Text Assetを動かしたまま、新規部分からSVG Textへ置き換えられます。

3.2で追加したDSLは次の2つです。

svgTextStyle=STYLE:BACKGROUND:TEXT_COLOR:FONT:SIZE:ALIGN:DIRECTION
action=ACTOR:setText:TEXT:STYLE

名前付きスタイルは吹き出しとSVGテキストアクターで共有できます。サイズ100は480×360ステージで標準14px相当になり、画面サイズに比例して変わります。TEXT中のリテラル\nは改行になります。背景色、文字色、フォント、左右／中央揃えと8方向の吹き出し方向を指定でき、3.2.0ではアニメーションしません。

3.1から3.2への移行チェックリスト

• 先頭がkamishibai=3.1またはkamishibai=3.2であることを確認した
• 新規台本または3.2機能を前提に更新する台本ではkamishibai=3.2を使用した
• 旧Text Assetが3.2でも表示・更新されることを確認した
• LEGACY_TEXT_ASSET_DEPRECATEDをエラーではなく移行通知として扱う運用にした
• 新規テキスト表示はsvgTextStyleとsetTextで設計した
• 旧Text AssetとSVG Textを併用する期間と置換順を決めた
• say／think、画像、音声が従来どおり動作することを確認した

setRuntimeVariable

setRuntimeVariable=変数名:値

Temporary Variablesのランタイム変数を台本から設定できるようにしました。開始シーンを指定する予約変数 startSceneIndex や、条件分岐で参照する状態の初期化に使います。

setRuntimeVariable=startSceneIndex:1
setRuntimeVariable=takeSeaRoute:true

registerBranch

registerBranch=分岐名:条件1,条件2,...:シーンラベル1,シーンラベル2,...

Runtime Expressionで評価する条件と移動先を登録できるようにしました。条件は左から順に評価され、最初に真になった条件と同じ位置のシーンラベルが選ばれます。

registerBranch=chooseRoute:takeSeaRoute,true:ocean,home

sceneLabel

sceneLabel=シーンラベル

シーンへ一意の名前を付けられるようにしました。条件分岐、キー入力、タッチ入力の移動先として使います。

scene 0のtext

text=ui.prompt:ポーズをとろう！

ポーズ案内を台本から定義できるようにしました。ui.promptはランタイムが自動登録する予約済みテキストアセットです。物語開始時に既定値へ戻してからscene 0の定義を適用するため、前に実行した台本の文言は残りません。

ファイル読込、再読込、タイトル表示、言語選択、台本エラーとタイトル画面はアプリ側の日本語／英語定義から表示します。初回は標準の（言語）ブロックで判定し、メニューから選んだ言語はlocalStorageへ保存します。過去の資料に記載されていたtext=ui.open:、text=ui.reload:、text=ui.about:、text=ui.invalidScript:は、台本読込前のUIには適用できないため現行仕様から除外しました。

シーン直下のtext=テキストアセット名:文字列も互換性のため利用できますが、アクション列より先に処理されます。時系列に沿ったテキスト更新には、次節のaction=text:...を使用します。

setLoadingBackdrop

setLoadingBackdrop=loadingBackground

アセット読込中のステージ背景を指定できるようにしました。指定背景を最初に読み込み、完了直後に表示します。Loading用背景は進捗の分子・分母から除外されます。省略時は組み込みの真っ黒な背景を表示し、タイトル画面をLoading中に残しません。

setLoadingCostume

setLoadingCostume=loading1,loading2,loading3

アセット読込中に表示する画像アセットを複数指定できるようにしました。指定アセットを通常アセットより先に読み込み、通常アセットの読込番号に応じて循環表示します。吹き出しの完了数 / 総数からLoading用アセット自身は除外します。省略した台本は組み込みのLoadingコスチュームを使います。

setPoseRecognitionSound

setPoseRecognitionSound=Clock Ticking

ポーズ認識開始から終了まで鳴らす音声アセットを台本から指定できるようにしました。省略時は無音です。generic SB3に残っていた未使用のActor/popとLoading/Chirpは本番成果物から削除し、テスト専用fixtureへ移しました。

グローバルアクション

キー入力とタッチ入力はバックグラウンドで待機します。入力項目と移動先ラベルは、同じ個数を同じ順番で指定します。

アクターアクション

loopはアセット数と秒数の個数をそろえます。sequenceの秒数はアセット数より1つ少なくします。どちらも待ち時間に 0 を使うことで、画像と音などを同時に開始できます。

アセット識別子

3.1では、プロジェクト内アセットを短く指定できるようにし、ステージ背景の識別子を backdrop に統一しました。また、ランタイムテキストをアセットとして扱えるようにしました。

短縮指定では、アセット名と同名のコスチューム、背景、音、テキストを参照します。

show

従来の書式に加え、スキン名を省略して初期スキンまたは現在のスキンを使えるようにしました。

# 2.0から継続する書式
action=Hero:show:Hero-normal:0,-60,30

# 3.1で追加した省略形
action=Hero:show:0,-60,30

setSkin

スキン切り替えと同時にサイズを変更できる書式を追加しました。

action=Hero:setSkin:Hero-surprised:45

シーンの実行モデル

2.0の記述順による進行を維持しつつ、3.1では次の仕組みで任意のシーンへ移動できるようにしました。

• startSceneIndexによる開始シーン指定
• sceneLabelによる移動先の命名
• registerBranchとbranchによる条件分岐
• keyInputToChangeSceneによるキー入力分岐
• touchInputToChangeSceneによるタッチ入力分岐

バージョン2.0

kamishibai=2.0
asset=Beach,background:beach
asset=Hero,costume:Hero:normal
asset=Opening,sound:@stage:opening
actor=Hero,Hero
cover=Beach,Opening
---
# scene 1
action=stage:Beach
action=Hero:show:Hero:0,-60,30
action=Hero:say:こんにちは！:2

バージョン3.1

kamishibai=3.1
setRuntimeVariable=startSceneIndex:1
setRuntimeVariable=takeSeaRoute:true
registerBranch=chooseRoute:takeSeaRoute,true:ocean,home
asset=Beach,backdrop
asset=Ocean,backdrop
asset=Home,backdrop
asset=Hero,costume
asset=Opening,sound
asset=Narration,text
asset=loading1,https://example.com/loading1.png
asset=loading2,https://example.com/loading2.png
setLoadingCostume=loading1,loading2
text=ui.prompt:ポーズをとろう！
actor=Hero,Hero
actor=Narration,Narration
cover=Beach,Opening
---
sceneLabel=opening
action=transition:fadeOut
action=stage:Beach
action=transition:fadeUp
action=Hero:show:0,-60,30
action=Narration:show:Narration:0,120,100
action=text:Narration:どちらへ進みますか？
action=Hero:say:こんにちは！:2
action=branch:chooseRoute
---
sceneLabel=ocean
action=stage:Ocean
---
sceneLabel=home
action=stage:Home