紙芝居アプリ 3.2 内部仕様書

Scratch／TurboWarpのproject構造

cloneとActor

紙芝居DSLと実行

変数とblock

内部構造のレイヤー

次の図は、汎用アプリSB3の実行時責務を上位から下位へ並べた概念図です。 上位レイヤーは下位レイヤーへ処理を委譲し、eventや共有変数を介して結果と状態を受け取ります。 各レイヤーの具体的なtarget、変数、message、custom blockは後続の章で説明します。

実行アーキテクチャ

次の図は、DSLがブラウザ上で実行されるまでの包含関係と主要な接続を示します。 TurboWarpランタイムはSB3 projectと機能拡張を読み込み、project内のStageに実装された DSLランタイムが、外部ファイルまたはSB3へ埋め込まれたDSLを解析・実行します。 DSLランタイムはbroadcastや共有変数でproject内のtargetを統括し、画像・音声、入力、 姿勢認識などの処理を機能拡張へ委譲します。

実装スナップショット

本書に掲載するblock IDの意味と安定性は 「event、カスタムブロック、呼出し関係」で説明します。

使用する機能拡張

管理対象となる埋め込み拡張では、GitHubの固定commitまたはnpm packageの完全固定version、 artifact path、SHA-256をapp/embedded-extensions.jsonのsourceに記録します。SVG Textは @kubohiroya/turbowarp-svg-text@0.1.0のdist/svg-text.jsとAPI manifestをnpm source providerから同期します。更新方法は sb3-toolchainのワークフロー に従います。kubohiroyakamishibairuntimeとkubohiroyaweblinkはこのproject内で管理する 小規模な拡張なので、sourceを持ちません。

target一覧

Actorの本体は非表示で、cloneだけを登場人物として表示します。prompt、UiItem clone、 Loading、LoadingBubbleAnchorの実画像は、Asset Managerへ登録します。台本が定義する 予約済みUIテキストはui.promptだけです。ui.open、ui.reload、ui.about、ui.language、 ui.invalidScriptはアプリの言語定義から設定します。

UiItem本体を非表示のcontroller兼雛形とし、 showTitle、showMenu、showLanguageMenuごとに必要な項目だけをcloneとして作ります。画面遷移時は cloneを非表示のまま保持せず削除します。 保存済み台本があるmenuでは、上段をファイルを開く／もう一度、下段を アプリ情報／言語とする2列×2行の固定グリッドでcloneを配置します。 各セルは、上側にローカルSVG costumeのアイコン、下側にruntime textのラベルを配置します。 上段のラベルと下段のアイコンの中心間隔を90以上確保し、行間を明確に分けます。 4つのメニューラベルには、既定のHandwritingではなく細身のSans Serifを指定します。 左右で異なるラベル長と文字高を含む可視外接範囲がStage中央に来るよう、セル中心全体を 幾何学的な中央から右へ17、下へ17移動し、四辺の余白を均等にします。 アイコンはui.icon.open、ui.icon.reload、ui.icon.about、ui.icon.languageとして Asset Managerへ登録し、対応するラベルと同じuiActionを持つ独立したUiItem cloneにします。 そのため、アイコンとラベルのどちらをクリックしても同じ画面操作を実行します。 雛形は10×10の透明costumeを保持し、位置とsizeだけを設定してcloneします。2×2の透明costumeでは TurboWarpのsprite fencingにより50〜80%の指定が100%へ切り上げられるため、最小50%を保持できる寸法にしています。 Asset Managerのruntime text skinはclone開始後にclone自身へ適用し、Animated Textのskinを雛形から複製しません。 3.2.xアプリでは、台本宣言が3.1でも3.2でも旧Text Assetの登録、text／textStyle／action=text、Text Assetを参照するshow／setSkinをこの経路で実行します。Kamishibai Runtimeは対象名を収集し、プロジェクトごとに一度LEGACY_TEXT_ASSET_DEPRECATEDをconsoleへ出力しますが、実行経路を止めません。移行先はturbowarp-svg-textであり、旧経路は少なくとも3.2系列で維持します。

新経路では、StageがsvgTextStyle=STYLE:BACKGROUND:TEXT_COLOR:FONT:SIZE:ALIGN:DIRECTIONを7項目へ分解してSVG TextのdefineStyleを呼びます。Actor cloneはaction=ACTOR:setText:TEXT:STYLEを受け、リテラル\nを改行へ変換してからsetTextを呼びます。SVG Textはstage sizeを基準にfontと余白を再計算し、style size 100を480×360で14px相当として扱います。

スタイル付き吹き出しでは、Stageのexec actor actionがaction=ACTOR:say|think:TEXT:SECONDS:STYLEの5番目の値をruntime variable actionParam3へ設定します。対象Actor cloneはこの変数が存在するときだけ、通常のLooks blockではなくSVG TextのsayWithStyle／thinkWithStyleを呼びます。変数が存在しない従来書式は通常のsay／thinkを通じてdefaultstyleを使用します。通常完了、Rightによるaction skip、Downによるscene skip、次のaction開始時のcleanupで、吹き出しとactionParam3を残しません。0.1.0ではanimationを実行しません。 生成手続きはwarpで原子的に実行し、cloneへローカル値をコピーした直後に雛形のuiIsTemplateを数値1へ復元します。 asset適用後に表示し、1 tick譲ってから最前面へ移動します。

アプリUIの定義元はscripts/sb3/app-shell-locales.mjsです。ロケール別のabout.title、 about.officialWebsite.name、about.license.app、about.license.story、 about.author.organization、about.author.nameと、共通のabout.officialWebsite.url、 about.author.emailを、green flag後にAsset Managerの実行時SVGテキストとして表示します。 versionとbuild dateはbuild時にabout.versionへ設定します。言語変更時は表示中の同じspriteの テキストskinを更新するため、ロケール別backdropは使用しません。

title用テキストの配置と文字サイズはScratch標準のStage解像度である480×360を基準にします。 長いライセンス文はロケール定義で明示的に2行へ分け、縮小表示に依存せず、タイトル、version、 公式Webサイト名、ライセンス、開発者情報を480×360の画面上で読める大きさに保ちます。

SB3読込直後からAsset Manager初期化完了まで、または初期化に失敗した場合にも画面を空に しないため、Titleとofficial-website-buttonには英語の固定フォールバックをbuild時に 埋め込みます。初期化が完了してshowTitleを送ると、Stageは文字なしのTitleRuntimeへ、 公式Webボタンは文字なしの実行時costumeへ切り替え、title用テキストspriteを重ねます。 公式Webボタンの両costumeにはsite/favicon.pngを埋め込みます。

green flag時はlocalStorageのuiLanguageがjaまたはenならその値を優先します。未保存なら 標準translate機能拡張の（言語） reporterが日本語、ja、ja-JPのいずれかを返す場合は 日本語、それ以外は英語を選びます。menuのlanguageButtonから選び直した値はlocalStorageへ 保存し、languageChangedでアプリUIのテキストを即時更新します。言語選択画面では現在値に ✓を付けます。台本のUTF-8本文には翻訳や言語切替を適用しません。

アクターへ命令を届けるしくみ

Scratch／TurboWarpで1つのspriteから複数の登場人物を作る場合、cloneごとに スプライトローカル変数の識別子を持たせれば、同じblockを共有しながら個体を区別できます。 このアプリはその考え方を、cloneへ命令を届けるところまで拡張しています。

本書では、cloneの雛形として使うActor targetをアクタースプライト、そこから作られ、 スプライトローカル変数のactorNameを割り当てられた各cloneをアクターと呼びます。 アクタースプライトの本体は表示せず、物語の登場人物として表示するのはアクターだけです。 すべてのアクターは同じblock定義を共有し、actorNameによって互いを区別します。

Stageからアクターへ命令を届ける流れは次のとおりです。

1. StageがDSLのActor actionを、宛先となるアクター名、command、引数に分解する
2. actionTarget、actionCommand、actionParam、actionParam2というruntime variableへ それぞれを格納する。このまとまりを本書ではaction envelopeと呼ぶ
3. StageがexecActorActionをbroadcastする
4. すべてのActor cloneがmessageを受け取り、自分のactorNameがactionTargetの 対象に含まれるかを調べる
5. 対象になったアクターだけが、actionCommandを入れ子の条件分岐で振り分け、 移動、見た目、音、時間に関する処理を実行する

つまり、action envelopeが「誰に・何を・どの引数で実行させるか」を表し、broadcastが その命令を全アクターへ配送します。ここでいうcommandは、アクターに対する メソッドに相当しますが、TurboWarp上ではカスタムブロックと条件分岐で実装されています。

通常のScratch projectではcostumeやsoundはspriteに属します。このアプリでは TurboWarp-Asset-Managerを使い、 SB3内のcostume、backdrop、sound、textや、外部URLの画像・音声を、名前を持つassetとして 登録します。アクターの見た目や音のactionはこのasset名を参照するため、振る舞いを実装する アクタースプライトと、実際に使う画像・音声を分けて組み合わせられます。

台本DSLは、このassetの定義、アクターの定義、sceneごとにアクターへ送るactionの定義を テキストで記述するための言語です。TurboWarpで作られたこのアプリはDSLを解析し、assetを 読み込み、アクターを生成し、action envelopeとbroadcastを使って命令を実行します。 したがって、このアプリ全体は、紙芝居DSLを解析・実行する処理系であり、その実行基盤 （runtime）でもあります。

台本からアクターclone生成までのシーケンス

アクターは、台本準備時にactor= commandから生成します。これは生成済みのアクターへ Actor actionを送る処理とは実行時期もデータの渡し方も異なるため、別の図に示します。

exec command %s %sはactor=の値をactorListへ追加します。各値は アクター名,初期skin名の形式です。その後、Stageのcreate actorがactorListを順に読み、 各値をthread variableのnameとskinへ分けます。Stageは共有runtime variableの actionTargetへname、actionParamへskinを設定してから、Actor targetのcloneを 作ります。

clone開始hatは、actionTargetをそのcloneのスプライトローカル変数actorNameへ保存し、 actionParamをTurboWarp-Asset-Managerへ渡して初期skinを設定します。Stageはcloneを 作るたびに0.1秒待ち、この初期化が走る機会を設けてから、共有runtime variableを次の アクター用の値で上書きします。clone生成時にはexecActorActionをbroadcastしません。

Actor target本体はcloneの雛形として非表示です。cloneはこの表示状態を引き継ぐため、 生成直後も非表示であり、sceneの後続のActor actionによって必要な時点で表示されます。

台本からActor actionまでのシーケンス

台本ファイルからActor内の処理までを、データの変換と実行の順に並べると次のようになります。 外部ファイルだけでなく、再生用SB3へ組み込んだ台本もscriptへ入った後は同じ経路を通ります。

create sceneListはscriptをscene単位に分けます。exec scene # %s with %sは現在のsceneを 行単位のcommandListに分け、exec command %s %sでcommandを順に処理します。このうち action=の値をactionListへ集め、exec actionListが各actionをexec action %sへ渡します。 Stage actionはStage内で実行されます。Actor actionでは、StageがactionTarget、 actionCommand、actionParam、actionParam2へaction envelopeを書き込んでから、 execActorActionをbroadcastします。messageを受信した各Actor cloneは4変数を読み、 自分のactorNameと宛先を照合します。実際にcommandを分岐して処理するのは、宛先に 一致したアクターだけです。

target間の責務

Stageは台本をsceneList、commandList、actionListへ段階的に変換します。 さらにsceneと共有runtime状態を管理し、Stage actionを実行します。Actor cloneの責務は、 生成時に自分のactorNameと初期skinを確定し、その後、 「アクターへ命令を届けるしくみ」で配送されたActor actionのうち 自分を対象とするものを実行することです。

UI spriteは表示状態をshowMenu／hideMenu、showPrompt／hidePrompt、 Asset ManagerのLoading messageで受け取ります。UiItem本体が画面単位の clone生成とaction実行を担い、clone自身は表示情報とclickしたactionだけを保持します。 台本の実行状態をUI sprite側へ複製せず、Stageを状態の所有者とします。

Scratch変数

__tmpose_embedded_scriptはStageに一つだけ存在し、monitorを持ちません。genericと editorでは空、playerではbuilderが変換済み台本を設定します。 featureDetailedScriptErrorsは最初のstartStoryで一度だけ読み、次のgreen flagまで値を固定します。 falseでは従来のScratch parserとinvalidScript経路だけを使います。 cloneUiItemsEnabledはclone UIの内部guardで、汎用SB3ではtrueのまま使用します。

Scratch list

すべてStage所有で、汎用SB3では空の初期状態です。

runtime variable

静的な名前を持つruntime variableは次の21個です。

このほか、exec command %s %sはDSLで指定されたruntime variable名を動的に設定します。 分岐条件はbranch:<branchName>という名前で保存します。この2系列は入力から名前が決まるため、 静的な21個には数えません。

詳細診断を有効にしてfatal errorが発生した場合、Kamishibai Runtimeは互換用scalarとして kamishibaiErrorCategory、kamishibaiErrorCode、kamishibaiErrorLine、 kamishibaiErrorColumn、kamishibaiErrorMessage、kamishibaiErrorSource、 kamishibaiErrorSvgを作ります。診断の正本は拡張内部のlastDiagnosticであり、これらの runtime variableと前回のSVG skinは次のgreen flagで削除します。

thread variable

カスタムブロック呼出しごとに分離され、呼出し終了後に共有状態として残さない値です。

runtime variableと同名のsceneIndex thread variableは、カスタムブロック内の局所的な 引数・計算値です。project全体の現在sceneはruntime variable側だけを正本とします。

event hat一覧

procedures_definitionと、接続されていないreporter blockはevent hatに含めません。 「実行される内容」はhatを起点とする主要なカスタムブロック呼出し、broadcast、状態変更、 表示操作を要約したもので、標準blockを含む全処理の逐語的な列挙ではありません。

カスタムブロック定義一覧

引数名はprototypeのargumentnames、warpはprototypeのmutation.warpから取得します。 「呼び出す処理／送信するmessage」には定義内で呼ぶ別のカスタムブロックや機能拡張の 処理を示し、broadcast messageは送信する名前を明記します。

主要な呼出し経路

create assetはLoading用assetを先に登録し、assetLoadingStartedをbroadcast and waitします。 通常assetは登録完了数がthread variable loadingDisplayedを上回る場合だけ最大値を保存し、 assetLoadingProgressを通常broadcastで1件につき1回送ります。全assetの登録後は assetLoadingCompletedをbroadcast and waitします。URL／cacheの完了待ちはAsset Managerが 返すPromiseに委ね、追加のwait 0は行いません。

message一覧

stopKeyInputとstopTouchInputは標準broadcast blockではなく、Async Inputへ渡した callback messageです。debugTestCameraは通常フローに送信元を持たない診断用messageです。

状態遷移

主要状態はStageが所有します。UI表示そのものを状態の正本にせず、runtime variable、 broadcast、実行中のcustom blockから導出します。

invalidScriptはpose待機への遷移ではありません。flag OFFでは、Stageが台本検証、command解析、 scene解析のエラー時にこのmessageを送信し、各送信箇所の直後にstop allを実行します。 promptはmessageを受信するとui.invalidScriptのskinを設定して表示します。

flag ONでは、Kamishibai RuntimeがScratch parserより前に物理行番号付きの限定preflightを行います。 最初のfatal diagnosticを内部へ保存してruntime.stopAll()を呼び、日本語または英語の説明、 code、行・列、該当行をXML escapeした480×360 SVGをpromptへ適用します。Asset Managerの project-local address検証APIとRuntime Expressionのsyntax-only APIだけを使い、正常時の 実行用listやactorは従来のScratch parserだけが生成します。rendererを利用できない場合は テキスト表示、それも利用できない場合はinvalidScriptへfallbackします。

skipModeは要求、skipContextは消費可能な境界です。要求はtitle、action、pose、sceneの 該当境界だけが消費し、scene開始、cover、stopでclearします。nextSceneLabelはkey／touch listenerが設定し、scene loopがlabelをindexへ解決したあと削除します。

skipMode=sceneでは、scene parserは残りのcommandを解析してaction listを完成させます。 action loopはbgmとtransitionだけを選択して台本順に高速実行し、それ以外を読み飛ばします。 transitionの反復待ちはskipModeの存在で終了しますが、最後の明るさ設定は必ず実行します。 bgmはscene skip中も開始でき、down arrow handlerは全音声を停止せず、現在のsoundだけを 停止します。これにより、すでに再生中またはシーン残部で開始したBGMを次sceneへ引き継ぎます。