紙芝居アプリ内部仕様書

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、SHA-256を app/embedded-extensions.jsonのsourceに記録します。更新方法は sb3-toolchainのワークフロー に従います。kubohiroyaweblinkはこのproject内で管理する小規模な拡張なので、 sourceを持ちません。

target一覧

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

アプリ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で受け取ります。台本の実行状態をUI sprite側へ 複製せず、Stageを状態の所有者とします。

Scratch変数

__tmpose_embedded_scriptはStageに一つだけ存在し、monitorを持ちません。genericと editorでは空、playerではbuilderが変換済み台本を設定します。

Scratch list

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

runtime variable

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

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

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は送信する名前を明記します。

主要な呼出し経路

message一覧

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

状態遷移

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

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

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へ引き継ぎます。