TM紙芝居 3.2 機能拡張ガイド
Copyright © 2026 Hiroya Kubo. この文書はCC BY-SA 4.0で提供します。引用図版には各出典の条件が適用されます。
全34ページ。16個の機能拡張を、1拡張につき2ページの見開きで図解する
kamishibai=3.1とkamishibai=3.2の台本を動かす3.2.xアプリは、次の16機能拡張を利用します。
読む順番は実行時の読込順ではなく、Gallery由来 → TurboWarp標準 → 外部埋め込み → アプリ内蔵です。
2種類の数え方: このガイドは保守するソース単位で16個を説明します。一方、bundle版SB3では、そのうち4個をtmbundleという1個のIDにまとめます。詳しくは次ページを参照してください。
右ページの実画面例はTurboWarp Editorを高解像度で撮影し、SVG Textだけは公開済み図解ガイドを撮影しています。詳しい呼出し関係は内部仕様書、更新手順はメンテナンスガイドを参照してください。
4拡張を1つのIDへまとめる
2 / 34 sb3-toolchainのbundle
このガイドで説明する16個は、更新・検査する論理上の機能拡張です。 sb3-toolchainでbundle版SB3を生成すると、相互に動的opcode参照を行う4個だけを、1個の複合機能拡張へまとめます。
kubohiroyaassetmanager Asset Managertext Animated Textkubohiroyakamishibairuntime Kamishibai Runtimekubohiroyasvgtext SVG Textbundle外12個 + tmbundle 1個
sourceは展開したまま
- 4拡張を個別に更新・検査
- GitHub／npmの固定由来を保持
check／syncも個別に実行
生成物だけを集約
- opcodeとstorageをmember別にnamespace化
- member間の動的opcode参照も変換
- 復元用capsuleにより展開可能
重要: 16個の機能が13個へ減るわけではありません。実装を統合するのではなく、配布するSB3の読込・登録単位だけをまとめる仕組みです。依存のないGallery拡張、Translate、TurboWarp TMなど12個はbundleの外に残ります。
Consoles、Text、Local Storage、More Timers、Files、Text Lines、TurboWarp TM、SVG Text、Web Linkは、他拡張を直接呼ばず、Stageのblockとruntime変数を介して連携します。
出典: sb3-toolchain: Extension bundles、Version 3.2.0 埋め込みmanifest、依存APIの実装
Consoles — ログ・警告・エラー・計測結果をブラウザーコンソールへ出力する
Gallery 1 / 7 機能拡張そのもの 1 / 2
ブラウザーの開発者ツールにあるJavaScript consoleへ、値をlog、warn、errorなどの種類で出力する拡張です。 group、経過時間の計測、consoleの消去もblockから操作でき、実行中の処理をまとまりと時系列で追跡できます。
warn / error→group・timerで整理→ブラウザーのconsole
記録する
- 通常値、情報、warning、error
- 複数値の結合と整形
- 開発者ツールへ即時出力
追跡する
- 処理をgroup化
- timerの開始・終了
- 前回のconsoleを消去
出典: Galleryバナー、配布ソース
Consolesで台本の実行状況をログへ記録し、停止した処理を突き止める
Gallery 1 / 7 TM紙芝居での利用例 2 / 2
このアプリでの役割: 緑の旗で古いconsoleを消し、journalで進行、errorで異常を記録します。表示用errorと開発用logを混ぜないことが重要です。
ブロック例: Version 3.2.0 project source（Stage: exec scene # %s with %s）
Temporary Variables — 実行範囲の異なる一時変数を作成・共有する
Gallery 2 / 7 機能拡張そのもの 1 / 2
Scratch変数を増やさず、処理の途中だけ必要な名前付き値を保持します。 一つのcustom block内だけのthread variableと、project全体で共有するruntime variableを使い分けます。
その実行だけ／runtime variable
project全体
thread variable
- blockの実行stackに所属
- 再帰や同時実行で値を分離
- 処理終了後に捨てられる
runtime variable
- 全target・拡張から共有
- 名前で作成・更新・削除
- project停止時までの一時値
出典: Galleryバナー、配布ソース
Temporary Variablesで処理ごとの一時値を分け、同時実行による上書きを防ぐ
Gallery 2 / 7 TM紙芝居での利用例 2 / 2
注意: runtime variableも永続保存ではありません。再起動後に残す値はLocal Storageを使い、green flag時にruntimeへ戻します。
ブロック例: Version 3.2.0 project source（Stage: create asset）
Text — 文字列を検索・分割・置換する
Gallery 3 / 7 機能拡張そのもの 1 / 2
文字や文章を検索、分割、置換、比較、trimするための文字列演算拡張です。 「含むか」を調べるだけでなく、区切りごとの項目取得、部分文字列、文字種変換などを値blockとして組み合わせられます。
形を調べる
- 文字数と出現回数
- 前方・後方一致
- 厳密な文字列比較
値を取り出す
- 区切り文字でsplit
- 部分文字列
- 前後の空白をtrim
出典: Galleryバナー、配布ソース
Textで台本のコマンド名と引数を、区切り文字から読み取る
Gallery 3 / 7 TM紙芝居での利用例 2 / 2
asset=...の最初の=を境界にする。区別: このTextは文字列演算のstringsです。Stageへ文字を描くAnimated Text（ID: text）とは別物です。
ブロック例: Version 3.2.0 project source（Stage: selectValue # %s separated by %s from %s）
Local Storage — 文字列をブラウザーへ保存・取得・削除する
Gallery 4 / 7 機能拡張そのもの 1 / 2
ブラウザーの保存領域に、project固有のnamespaceで文字列を保持します。 Scratch変数と違い、ページを閉じた後でも次回起動時に読み戻せます。
できること
- plain textの保存・取得・削除
- namespace単位の全削除
- 別windowでの変更検知
性質と制約
- 通常変数より書込が遅い
- Web版は容量が小さい
- 同じnamespaceは互いに上書き
出典: Galleryバナー、公式ドキュメント
Local Storageで選んだ台本と言語設定を保存し、次回起動時に復元する
Gallery 4 / 7 TM紙芝居での利用例 2 / 2
kamishibaiに定め、runtimeのscriptをstorageへ書く、隣接した2ブロックです。注意: 同じprojectを複数tabで開くと、後から保存したwindowが値を上書きする可能性があります。小さな設定と台本文字列だけを対象にします。
ブロック例: Version 3.2.0 project source（Stage: green flag）
More Timers — 複数の名前付きタイマーを個別に管理する
Gallery 5 / 7 機能拡張そのもの 1 / 2
標準timerを一つだけでなく、文字列で名付けた複数のタイマーとして並行管理します。 各timerを個別に開始、pause、resume、reset、増減、削除できるため、重なった処理の経過時間を独立して扱えます。
値を読む・増減→remove
個別timer
- 名前で作成・照会
- pause／resume
- reset、増減、削除
複数のタイマー
- 互いの値を上書きしない
- 存在する名前を確認
- 必要なら全timerを削除
出典: Galleryバナー、配布ソース
More Timersで待機時間を計測しながら、利用者のスキップ操作にも応答する
Gallery 5 / 7 TM紙芝居での利用例 2 / 2
設計上の要点: Scratchの長い「待つ」ブロックに任せず、短いloopでtimerとskipを同時に監視します。これによりプレイ中の操作へすぐ反応できます。
ブロック例: Version 3.2.0 project source（Stage: wait %s seconds）
Files — ローカルファイルの読込みとダウンロードを行う
Gallery 6 / 7 機能拡張そのもの 1 / 2
利用者が選択またはdrag & dropしたlocal fileを、textまたはdata URLとしてprojectへ渡す拡張です。 逆にproject内の値をfilename付きでdownloadでき、ブラウザーのfile pickerとTurboWarpのblockを橋渡しします。
+ filename↔download
入力
- 拡張子・MIME type指定
- text／data URL
- cancel時は空文字
出力
- filename付きdownload
- ブラウザー内で完結
- 明示的な利用者操作から開始
出典: Galleryバナー、配布ソース
Filesで参加者が選んだTXT台本を、埋め込み台本と同じ検査・実行経路へ渡す
Gallery 6 / 7 TM紙芝居での利用例 2 / 2
scriptへ渡す。安全性: pickerは利用者clickに続いて開きます。cancelで空文字になった場合は、保存済み台本を勝手に置き換えません。
ブロック例: Version 3.2.0 project source（UiItem: runUiItemAction）
Animated Text — 文字列をスプライトの見た目として描画・アニメーションする
Gallery 7 / 7 機能拡張そのもの 1 / 2
spriteへ文字専用のrenderer skinを作り、font、色、幅、配置、outlineを設定して表示する拡張です。 文章をtyping、rainbow、zoom、shakeなどで演出でき、Scratch LabのAnimated Text実験と互換性があります。
色・幅・配置→renderer skin→spriteへ表示→animation
style
- font、色、outline
- 幅、折返し、align
- spriteのskinとして描画
animation
- typing
- rainbow、zoom
- shakeなどの演出
出典: Galleryバナー、配布ソース
Animated Textで台詞やメニューの文字列を画面へ描画する
Gallery 7 / 7 TM紙芝居での利用例 2 / 2
text_setFont等のopcodeをruntimeから取得する。text_setText／text_animateTextでskinを作る。重要: 接続済みscriptにAnimated Text blockはありません。Asset Managerが表示時にtext_setFont、text_setColor、text_setWidth、text_setText／text_animateTextをprogrammaticに呼ぶ依存関係です。
DSL 3.2: この経路は旧Text Assetのdeprecated互換機能として少なくとも3.2系列で維持します。3.2.0にはturbowarp-svg-textも組み込まれており、新旧を併用できます。
ブロック例: Version 3.2.0 project source（text asset登録・style設定）、内部実装: Asset ManagerからAnimated Text opcodeを取得する処理
Translate — 文章を翻訳し、閲覧環境の言語を取得する
TurboWarp標準 1 / 1 機能拡張そのもの 1 / 2
Scratch／TurboWarp標準の翻訳拡張です。文章と翻訳先の言語を指定するblockに加え、viewerで選択中の言語を返します。 翻訳結果とviewer languageは別のreporterであり、後者は通信せずに現在のlocale名を取得します。
文章の翻訳結果と、現在のTurboWarp UIが使う言語名をreporterとして返します。
翻訳reporter
- 入力textと翻訳先を指定
- 対応言語から選択
- 結果を文字列で返す
language reporter
- viewerのlocaleを取得
- 通信を必要としない
- UI初期値の判断に使える
Translateで閲覧環境の言語を取得し、初期表示へ反映する
TurboWarp標準 1 / 1 TM紙芝居での利用例 2 / 2
方針: ブラウザーのlocaleを毎回強制せず、利用者が一度選んだUI言語を優先します。Translateは初期値を決める補助です。
ブロック例: Version 3.2.0 project source（Stage: green flag）
Asset Manager — 異なる場所・種類の素材を名前付きで管理・操作する
外部埋め込み 1 / 6 機能拡張そのもの 1 / 2
Web上の画像・音声、SB3内のcostume・backdrop・sound、実行時textを一つの名前付き登録簿で扱います。 登録後は素材の置き場所や種類に応じた処理を拡張が選び、共通のasset名で表示、再生、animation、cacheを操作できます。
URL、project内素材、textを同じasset名へまとめ、Stage・Actor・音声へ配ります。
project内素材
動的text→名前 + 種類を登録
Web素材はcache→sprite / Stage
sound / Actor timeline
読込
- 種類判定と取得
- IndexedDB cache
- Loading用の素材を先行
利用
- Stage／sprite skin
- 音声再生・停止
- Actor loop／sequence
Asset Managerで台本指定の素材を読み込み、名前で背景・登場人物・音を操作する
外部埋め込み 1 / 6 TM紙芝居での利用例 2 / 2
address例: costume:Actor:hero1、backdrop:sea、sound:Stage:bell。project内参照はsprite名と素材名を正確に指定します。
ブロック例: Version 3.2.0 project source（Stage: create asset）
TurboWarp TM — 学習済みモデルでカメラ映像のポーズを認識する
外部埋め込み 2 / 6 機能拡張そのもの 1 / 2
Teachable Machine Pose modelとカメラ映像を接続し、現在のpose名とconfidenceをTurboWarpの値として返します。 model、camera、preview、predictionを別々に開始・停止できます。
カメラ映像から骨格を推定し、Teachable Machineで学習したposeごとのconfidenceを返します。
keypoints→TM classifier→label・confidence
蓄積score
現在の認識
- pose labelとconfidence
- すばやい動きへ即時反応
- camera previewを配置
時間を含む認識
- confidenceを蓄積・減衰
- 一瞬の揺れを平滑化
- 開始・停止を個別管理
TurboWarp TMで観客のポーズを認識し、物語を進める入力として扱う
外部埋め込み 2 / 6 TM紙芝居での利用例 2 / 2
start pose recogとstart camera preview。各custom blockが対応するTurboWarp TM blockを1つずつ呼びます。TMPoseURLでmodelをload。実行条件: camera権限とHTTPSが必要です。modelとTensorFlow／Teachable Machine libraryの取得にはnetwork接続を使います。
ブロック例: Version 3.2.0 project source（Stage: setTMPoseURL / exec pose）
Text Lines — 複数行の文字列を行単位で取得・リスト化する
外部埋め込み 3 / 6 機能拡張そのもの 1 / 2
長いtextを改行位置で分割し、行数、指定行、Scratch listとして扱います。 LF、CRLF、CRを同じ改行として正規化するため、台本を作ったOSに依存しません。
元sourceの行番号を保ったまま、preflightと実行loopへ渡します。
を正規化→行数
指定した1行
list全置換
入力
- LF、CRLF、CR
- 空行を含む全文
- UTF-8の台本文字列
出力
- 行数
- 1始まりの指定行
- list全置換
Text Linesで台本を行ごとに分け、エラー表示を元のTXTの行番号へ対応させる
外部埋め込み 3 / 6 TM紙芝居での利用例 2 / 2
lines listへ展開する部分です。lines listをscene生成へ渡す。listの扱い: 書込blockは追記ではなく全置換です。前回台本の行が残らないため、reloadしても行番号がずれません。
ブロック例: Version 3.2.0 project source（Stage: create sceneList）
Runtime Expression — 一時変数を参照する制限付き条件式を安全に評価する
外部埋め込み 4 / 6 機能拡張そのもの 1 / 2
Temporary Variablesのruntime値を、JavaScriptに似た制限付き条件式から参照し、true／falseを返します。 任意codeを実行せず、許可した比較、論理、算術、括弧だけを評価します。
score >= 3 && hasKeyのような式を検査して評価し、必要ならfalse／trueの変化をbroadcastします。
+ 条件式→制限付きparser→true / false／false↔true時だけ
broadcast
条件reporter
- 比較、論理、算術、括弧
vars["日本語名"]- 代入・関数呼出しは禁止
条件付きbroadcast
- 最初の状態を記憶
- 結果が変化した時だけ通知
- IDで置換・解除・timeout
Runtime Expressionで台本の条件式を安全に評価し、最初に成立した場面へ進む
外部埋め込み 4 / 6 TM紙芝居での利用例 2 / 2
condition reporterで現在のruntime値に対して評価してから次の条件へ進みます。registerBranchが式とscene labelを保持。二段階の安全性: Kamishibai Runtimeが実行前にsyntaxを検査し、scene移動時にRuntime Expressionが現在値で評価します。
ブロック例: Version 3.2.0 project source（Stage: exec branch action）
SVG Text — 名前付きスタイルで相対サイズの吹き出しとSVG文字を描画する
外部埋め込み 5 / 6 機能拡張そのもの 1 / 2
背景色、文字色、font、相対font size、配置、吹き出し方向を名前付きstyleとして定義し、say／think bubbleとsprite自身のSVG text skinで共有する拡張です。文字列中の\nを複数のSVG tspanへ変換します。
size 100を480×360 stageの14px相当とし、stage寸法が変わっても相対的な大きさを保ちます。
+ 複数行text→stage scaleで再計算→say / think bubble／SVG text actor
style
- 背景色・文字色・font
- size 1〜1000、左右／中央揃え
- 上下左右と斜めの8方向
再描画
- stage size変更へ追従
- 同名styleの再定義へ追従
- 0.1.0ではanimationなし
SVG Textで吹き出しとテキストアクターの見た目を共有する
外部埋め込み 5 / 6 TM紙芝居での利用例 2 / 2
\nで改行し、同じ名前付きstyleを吹き出しとSVG text actorへ適用します。svgTextStyleで共通styleを定義。setTextでActor自身をSVG文字へ変更。say|think:TEXT:SECONDS:STYLEで個別に選択。DSL 3.2: svgTextStyleで定義したstyleを、setTextまたはaction=ACTOR:say|think:TEXT:SECONDS:STYLEから使います。後者は内部でsayWithStyle／thinkWithStyleを呼び、STYLE省略時はdefaultを使います。旧Text Assetもdeprecated互換として維持します。
ブロック例: Version 3.2.0 project source（Stage: svgTextStyle、Actor: setText）、スタイル付きsay／think実装PR、図版: SVG Text日本語ガイド
Async Input — キー・タッチ・カスタム入力を値更新と通知へ接続する
外部埋め込み 6 / 6 機能拡張そのもの 1 / 2
key、sprite／cloneのtouch、任意機能のpose入力を、Temporary Variablesのruntime値更新とbroadcastへ接続します。 bindingは登録したtargetが所有し、値を更新してから受信scriptの完了を待たずにmessageを送ります。
key、touch、poseを「runtime値を更新し、必要ならmessageを送る」target所有のbindingへ揃えます。
pose（任意）→target-owned binding→runtime値を先に更新→broadcast
待機しない
登録
- KeyboardEvent.code
- sprite／clone／Actor名
- 代入または算術更新
解除
- cover表示
- scene境界
- target削除・stop
Async Inputでキー・画面タッチ・ポーズ入力を、競合しない場面遷移へまとめる
外部埋め込み 6 / 6 TM紙芝居での利用例 2 / 2
後片付け: 登録はtargetごとに所有されます。sceneをまたいだ古いlistenerが次の場面で発火しないよう、境界で必ず停止します。
ブロック例: Version 3.2.0 project source（Stage: keyInputToChangeScene）
Kamishibai Runtime — 紙芝居DSLを事前検査し、構造化診断とSVGを生成する
アプリ内蔵 1 / 2 機能拡張そのもの 1 / 2
紙芝居DSL 3.1／3.2を実行前に検査し、旧Text Assetのdeprecated警告と、失敗時の分類済み診断・SVG error画面を作るproject専用拡張です。 正常な台本の実行は置き換えず、副作用を始めてよいかだけを判定します。
cameraや音声を始める前に、version、command、参照、条件式をまとめて検査します。
address・条件式→実行許可
／ SVG診断
検査
- version、command、action
- scene／asset参照
- addressと条件式syntax
診断
- error code
- 行・列
- source抜粋とSVG文字
Kamishibai Runtimeで素材読込やカメラ開始の前に台本を検査し、エラーを表示する
アプリ内蔵 1 / 2 TM紙芝居での利用例 2 / 2
startStory直後にvalidateし、成功した場合だけskip状態の初期化やcamera開始へ進む順序を示します。startStory直後、asset／cameraより前。責任境界: DSL parser／実行器全体ではありません。実行前の限定preflightと、利用者が直せる診断表示に責任を絞っています。
ブロック例: Version 3.2.0 project source（Stage: startStory）
Web Link — HTTPS URLを検証し、新しいタブで開く
アプリ内蔵 2 / 2 機能拡張そのもの 1 / 2
受け取ったURLを検証し、ブラウザーの新しいタブで開くproject専用の小さな拡張です。 任意schemeを許可せず、HTTPS URLへの明示的なnavigationだけをblock化します。
絶対URL、HTTPS、noopener／noreferrerを確認してから新しいtabを開きます。
noopener / noreferrer
許可
- 絶対URL
https:- 利用者clickからの呼出し
拒否
http:file:／javascript:- 通常sceneからの任意navigation
Web Linkで利用者がボタンやメニューを操作したとき、設定済みのHTTPSページを開く
アプリ内蔵 2 / 2 TM紙芝居での利用例 2 / 2
open-urlを指定したUI項目。browser policy: popup blockを避けるため、利用者clickに続けて実行します。新しいtabにはnoopener,noreferrerを付けます。
ブロック例: Version 3.2.0 project source（officialWebsiteButton）