TurboWarp Bubble ブロック利用マニュアル

このマニュアルでは、turbowarp-bubbleをTurboWarpのカスタム拡張機能として使い、SVG本体、文字、キャラクター表情、目パチ、口パク、「次へ」アイコンを組み合わせたBubbleを表示します。

紙芝居DSL 4.0集約ランタイム： 集約ランタイムのパレットでBubble見出し直下のドキュメントボタンを押すと、このマニュアルを開けます。集約されたブロックも、ここで説明するstyle、配置、portrait、逐次表示、音声、待機、animation、clone、自動解放の動作を保ち、拡張機能別の名前空間とBubbleアイコンで由来を識別できます。

1. 必要な拡張機能

入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.1のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime Expressionはconditionを使うBubble待機またはclose policyで必要です。timeoutだけのclose policyにはどちらも不要です。

開発中のBubbleを試す場合は、このリポジトリのdist/turbowarp-bubble.jsをローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、condition待機の開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。

参考：

• Asset Manager 日本語ガイド
• Async Input 日本語ガイド
• Runtime Expression 日本語ガイド
• SVG Text 日本語ガイド

2. 表情画像を準備する

例ではAssetsという素材用spriteに、次のcostumeを入れます。素材用spriteは画面上で非表示でも構いません。

ベース、目、口の画像は同じcanvasサイズと同じ中心位置で作ります。差分画像の背景は透明にしてください。位置やcanvasサイズが異なると、レイヤーを重ねたときに目や口がずれます。

Asset Managerのブロックで各costumeを登録します。

register resource [costume:Assets:HeroFace] as asset [HeroFace]
register resource [costume:Assets:HeroEyesOpen] as asset [HeroEyesOpen]
register resource [costume:Assets:HeroEyesClosed] as asset [HeroEyesClosed]
register resource [costume:Assets:HeroMouthClosed] as asset [HeroMouthClosed]
register resource [costume:Assets:HeroMouthOpen] as asset [HeroMouthOpen]
register resource [costume:Assets:Next1] as asset [Next1]
register resource [costume:Assets:Next2] as asset [Next2]

URL画像を使う場合は、RESOURCE_IDへHTTPS URLを指定します。Bubbleに設定できるのは、Asset Managerへ登録済みでMIME typeがimage/*のアセットだけです。

3. 文字layout styleを選ぶ

standalone BubbleはSVG Text 0.8.1のlayout compositionを内包し、2つのBubble styleを組み込みます。sayはspeech本体とspeech tail、thinkはthought本体とround trailを持ち、本体とtail/trailの形は別項目ではなく1つのvisual styleとして選びます。短いsay [MESSAGE]／think [MESSAGE]ブロックが対応styleを自動選択するため、基本経路にはstyle定義もstyle入力も不要です。どちらも予約text profile default、内容に追従するサイズ、14px Helvetica、右側優先・収まりに応じた左反転、block入力の330文字上限、空文字でのcloseを使います。4pxのSVG strokeを白いfillより先に描き、内側半分を隠すことで、見かけの輪郭をTurboWarp標準と同じ細さにします。それ以外のtext style名やstyle設定ブロックを使うとcustom profileになります。custom text styleは初回参照時に背景透明のSVG Text既定styleとして初期化されます。stock SVG Text 0.8.1をBubbleより先に別拡張として読み込んだprojectでは、Bubbleが公開getLayoutCapability()を使い、SVG Text blockで定義したnamed styleを維持します。handoffのない古いSVG Textがロード済みならstyleを黙って置換せず互換errorを返し、必要な場合だけ文書化済みscratch-render fallbackを選択します。

define bubble style [hero-dialogue] using text style [default]

独自のfont、色、alignmentを使うアプリhostは、createSvgTextLayoutComposition()へstyleを定義し、createSvgTextOverlayTextCapability()でBubbleへ注入します。custom profileは同じlayoutText()を使い、既定overlay backendではSVG文字skinを生成しません。Bubbleの配置、tail、吹き出し外形はBubble側が担当します。

4. Bubble styleを定義する

基本Bubbleでは短いブロックをそのまま使います。組み込みBubble style say／thinkがそれぞれ自動選択されます。

say [こんにちは！]
think [うーん…]

TurboWarp標準との比較

次の画像は、1つのTurboWarp Editor projectで英語UIを使い、Cat spriteをx=-80、y=0、サイズ80%、Stageを白背景、入力をHello!／Hmm...に揃えて撮影した実画面です。左列はTurboWarp標準の見た目ブロックです。右列は対応する組み込みsay／think styleを使うBubbleの短い基本ブロックで、定義ブロックもsetterも使っていません。

Stage図では、右側配置、内容に追従する本体、Actor側へ向くspeech tail／thought trailを同じ条件で確認できます。Bubbleは独立したSVG surfaceを描画しており、全4panelとも実際のTurboWarp Stageを切り出したものです。

ブロック図は設定不要の基本経路と、custom style用の統合表示ブロックを示します。短いブロックは対応する組み込みstyleを自動選択します。calloutでは不可分な本体＋tail/trailの組、両styleが使う予約text profile default、共通のfont、行高、幅、padding、角丸、色、border描画順、配置を示します。named custom styleにはshow [MESSAGE] with bubble style [STYLE]を使います。旧styled say/think opcodeは保存済みproject互換用の非表示定義として残します。

次のsetterを使うと、意図的にcustom profileへ切り替わります。

define bubble style [hero-dialogue] using text style [default]
set bubble placement [up-right] for bubble style [hero-dialogue]
set bubble distance [12] for bubble style [hero-dialogue]
set bubble visual style [NORMAL] for bubble style [hero-dialogue]
set bubble tail length [18] for bubble style [hero-dialogue]
set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]

Actor相対と背景相対のplacement

Actor相対の16方向は、各方向をActor、Bubble外形、tail、文字を含む独立したミニシーンで示しています。三角形tailの基部2点は実際の本体border上にあり、本体polygonとのJSClipper union後の単一pathを描くため、接合部に内部border線は残りません。

背景相対3図はStage外枠、安全領域、Bubble外形寸法、水平中央線、基準辺／中心を示します。外形はBubble側の共有renderBubbleSvgで生成しており、TurboWarp Editorで本体drawableを生成するrendererと同じです。

Actor相対placementはcustom profileへ適用され、Actor中心からBubble全体の中心へ向かう方向を指定します。未変更の基本profileはScratch標準の右側優先・自動左反転を使います。menuには次の16正規方向があります。

up / up-up-right / up-right / right-up-right
right / right-down-right / down-right / down-down-right
down / down-down-left / down-left / left-down-left
left / left-up-left / up-left / up-up-left

north、north-northeast、northeastなどのcompass aliasも直接入力またはreporterから指定できます。数値はScratch方向と同じ0〜360度で、0は上、90は右、180は下、270は左、360は0へ正規化されます。任意角度は16方向へ丸めません。placementを設定しないstyleはup-rightになります。

背景相対はActorから生える方向を持たず、Stage安全領域へ配置します。

背景相対placementはActorの座標、bounds、可視性に依存しません。Stageからsay／thinkを実行する場合も、この3値のいずれかを設定します。背景相対のBubble bodyにはActorを指すtailを描画しません。

Actorとの距離、tail、本体の位置・拡大率

• distance（既定12）はActor boundsからtail先端までの距離です。Actor boundsとは、描画済みActorをStage座標で囲むAABB（上下左右のbounding box）です。
• tail length（既定18）は通常位置におけるBubble borderからtail先端までの基準長です。
• offset x/y/scale（既定[0, 0, 100]）は、xが右正、yが上正、scaleが百分率です。[10, -10, 120]なら、本体を右10・下10へ補正し、120%にします。

scaleは外形だけでなく、SVG Textの文字、表情ベース・目パチ・口パク、次へアイコン、内部余白へ一体で適用されるため、表示上のフォントサイズも同じ比率で変わります。scaleだけを変更すると、本体中心を拡大半径分だけActorから離してActor側の間隔を維持します。x/y offsetはその後に加算し、tail先端を固定したまま本体borderとのunionを再生成するため、offset後のtail実長は基準値から変化します。

Stage端では、拡大後のBubble全体を画面内へ収めるクランプが優先されるため、指定距離を保てない場合があります。背景相対のHEADER_LIKE／CENTER／FOOTER_LIKEでは、これらのActor相対設定を使用しません。

幅・自動改行・禁則処理

図の改行結果はproductionのwrapTextを直接実行して生成しています。@cto.af/linebreakがUnicode UAX #14の改行候補を返し、Intl.Segmenterの書記素境界で絞り込んだ後、実測幅の上限に収まる最後の候補を選びます。句読点、閉じ括弧、小書き仮名、長音、結合emojiの途中で不自然に分割しません。

Bubble visual styleの形状例

形状候補はNORMAL、THINKING、DREAMING、YELLING、OFF_PANEL、WAVY、WHISPERING、ANNOUNCEMENT、NARRATION、NO_BUBBLEです。次のblockでBubble styleごとに選択します。

set bubble visual style [YELLING] for bubble style [hero-dialogue]

図とTurboWarp Editorの本体drawableはBubble側の共有renderBubbleSvgから生成しています。三角形tailを持つ形状はplatener/jsclipperによる本体との和集合です。THINKING／DREAMINGは丸trailのためunion対象外です。Actor相対ではActorを向くtailを生成し、背景相対ではtailを付けません。NO_BUBBLEでは本体drawableを非表示にして文字・表情などだけを表示します。

visual styleを省略した場合はNORMALです。本体drawableは文字・portraitより先に生成して背面へ置きます。close this bubble、対象sprite／cloneの停止、runtime破棄時には、本体drawableとBubbleが所有するSVG skinも解放します。

NEGATIVEはfill colorとborder colorで表現できるため独立styleにはしません。orientationとsegmentsも公開入力にせず、幅、フォント、文字数、禁則処理後の行数から外形寸法を自動計算する方針です。

続けて、表情レイヤーと入力待ちアイコンを設定します。

set portrait base [HeroFace] for bubble style [hero-dialogue]
set portrait [top-left] offset x [-4] y [6] zoom [120] % corner radius [12] px for bubble style [hero-dialogue]

set blink frames [HeroEyesOpen,HeroEyesClosed]
  every [0.4] seconds for bubble style [hero-dialogue]

set lip-sync frames [HeroMouthClosed,HeroMouthOpen]
  every [0.1] seconds for bubble style [hero-dialogue]

set continue frames [Next1,Next2]
  every [0.2] seconds for bubble style [hero-dialogue]

ASSETSはカンマ区切りのAsset Managerアセット名です。名前の前後の空白は除去されます。アセット名自体にカンマは使用できません。

• 目パチと口パクは1枚以上指定できます。1枚だけなら表示は固定されます。
• 「次へ」はループが分かるよう2枚以上必要です。
• SECONDSは0より大きい秒数です。
• ASSETSを空にすると、そのアニメーション設定を解除します。
• portrait配置の既定値はleftです。left／rightは対応する端の上下中央、top-left／top-right／bottom-left／bottom-rightは対応する隅へ揃えます。portrait用の列は維持されるため、大きなoffsetで移動しない限り文字と重なりません。
• portraitのxは右正、yは上正です。zoomは96pxのportrait枠に対する0より大きい百分率で、Bubble全体のscaleより先に適用します。角丸半径は0以上のpixel値で、表示幅または表示高の半分を上限にします。
• noneを選ぶか表情ベースを空にすると、目パチ・口パク設定を含むportrait全体を解除します。別の配置へ戻すときは、先に表情ベースを再設定します。
• 角丸はBubbleのfill色でベース・目パチ・口パクの各レイヤーをmaskします。NO_BUBBLEにはmaskに使うfillがないため、portraitは矩形表示のままです。

5. 逐次表示、音声、表示サイズ

Bubbleはセリフ全体を一度に描画するだけでなく、CHARACTER、WORD、LINE、BLOCKの単位で順次表示できます。WORDは形態素解析を行わず、空白または指定した区切り文字集合で分割します。区切り文字を表示するかどうかも選べます。

set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
show [海へ出発！] with bubble style [hero-dialogue]
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds

DYNAMICは表示単位ごとに吹き出しの大きさと配置を再計算し、RESERVEDは最終的な文字量を先に計測して表示中の外形を予約します。set bubble reveal soundは単位ごと、set bubble voiceは表示開始時にAsset Managerの名前付き音声を再生します。音声がなくても文字表示は利用できます。

6. セリフを表示して入力を待つ

sayまたはthinkはBubbleを表示するとすぐ次のブロックへ進み、初期animation modeはtalkingになります。

set runtime variable [input] to []
listen for key [Space] set runtime var [input] to [pressed]
listen for touch on this sprite set runtime var [input] to [pressed]
show [海へ出発！] with bubble style [hero-dialogue]
wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
close this bubble

まずTemporary Variablesでinputを初期化してから、Async Inputのキー入力とタップのlistenerを登録します。Bubbleの待機ブロックは、input == "pressed"をRuntime Expressionへ委譲し、開始直後とVMの各フレームで評価します。待機中は自動的にawaiting-continueとなり、口パクを停止してset continue framesの画像をループします。条件成立またはtimeout後はidleへ移り、次のclose this bubbleへ進みます。timeoutを0にすると時間制限なしです。

次の待機に入る前にinputを空文字へ戻してください。前回のpressedが残っていると、次の条件が直ちに成立します。別のBubble表示、close、対象targetの停止、projectの開始・停止、runtime破棄では、targetが所有する待機とlistener、timerをキャンセルして解放します。

同じ終了規則を再利用する場合は、名前付きBubble close policyを使います。triggerはcondition、timeout、condition-or-timeoutから明示的に選びます。policyの適用は定義をsnapshotし、成立まで待ち、Bubbleのhide animationと解放までを1つの待機commandとして実行します。

define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == "pressed"] timeout [10] seconds
show [海へ出発！] with bubble style [hero-dialogue]
wait and close this bubble using close policy [advance-or-timeout]

timeoutだけのpolicyは現在のanimation modeを変えず、入力用拡張を必要としません。conditionを含むpolicyはawaiting-continueへ移り、既存の統合待機と同じAsync Input／Runtime Expression設定を使います。待機中に同じ名前を再定義しても、変更は次回の適用から有効です。Bubbleの置換やlifecycle cleanupは待機中policyをcancelし、置換後のBubbleを閉じません。

音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点でawaiting-continueへ切り替えます。

アニメーションGIFを再生できない環境では、次の比較図で各animation modeを確認できます。

7. Animation modeの使い分け

set this bubble animation mode [MODE]は、呼び出したsprite、clone、またはStageが所有するBubbleだけを変更します。先にsayまたはthinkを実行していない場合はエラーになります。

8. 表示開始・表示中・表示終了animation

表示開始はfadeIn、floatIn、zoomIn、riseUp、表示終了はfadeOut、floatOut、zoomOut、sinkから選べます。これらはDYNAMICとRESERVEDのどちらにも適用できます。

set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
animate this bubble [shake]
shake this bubble direction [90] count [2] ease [easeInOut]
explode this bubble relative scale [1.15] count [2] ease [easeOut]
animate bubble shape to [WAVY] speed [1] for [0.5] seconds

TurboWarp adapterはこれらをschedulerのフレームごとに進め、各フレームの進行率へeaseを適用します。shakeは吹き出し全体を方向・回数付きで揺らし、explodeはportraitと文字を含むsurface全体を拡大して元へ戻し、animate bubble shapeは指定時間中に現在の外形からTHINKING、DREAMING、YELLING、WAVY、WHISPERINGなどへcross-fadeします。仕様では、吹き出しが表示される時点を「表示開始」、隠れる時点を「表示終了」と呼びます。

表示中のBubbleを消すときはclose this bubbleを使います。設定済みの表示終了animationを実行してから、Bubbleのtimerと描画resourceを解放します。set bubble hide animation ...は終了時の演出を設定するだけで、このブロック自体はBubbleを消しません。組み込み基本profileでは、say／thinkへ空文字を渡してもTurboWarp標準と同様にcloseします。closeは非表示instanceを保持せず表示を破棄するため、別のhideブロックは公開しません。

9. named Bubble styleを表示する

show [MESSAGE] with bubble style [STYLE]

選択したBubble styleが、本体とtail/trailの形を一体で決め、text profile、表情レイヤー、placement、animation設定も保持します。set bubble visual styleはNORMAL（speech本体＋speech tail）やTHINKING（thought本体＋round trail）のような不可分の組を選ぶブロックで、tail形状だけを独立して指定する設定はありません。standalone extensionは、表示ブロックに競合し得る別の種類を選ばせず、そのstyleから内部描画kindを導きます。

同じsprite、clone、またはStageで新しいsay／thinkを実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。

10. cloneで使う

Bubble styleの定義は拡張機能内で共有されますが、表示中のBubbleはsprite／cloneごとに所有されます。

1. 元spriteで、緑の旗が押されたときにアセットとstyleを1回定義します。
2. 各clone自身からsayまたはthinkを実行します。
3. animation mode変更とcloseも、表示したのと同じcloneから実行します。

cloneが停止・削除された場合は、そのtargetに属するtimer、overlay DOM、画像leaseが自動解放されます。明示的なscratch-renderではskinとdrawableも解放されます。

11. ブロック一覧

旧say/think [MESSAGE] with bubble style [STYLE] opcodeを使う保存済みprojectは引き続き動作しますが、この互換ブロック2個はpaletteに表示しません。新しいscriptでは統合showブロックを使い、選択styleだけで本体とtail/trailの形を決めます。

12. よくあるエラー

13. 自動解放されるタイミング

次の場合、Bubbleが所有するtimer、overlay DOM、画像leaseは自動的に解放されます。scratch-renderを明示した場合はtext skinとrenderer drawableも解放されます。

• close this bubble
• 同じsprite／cloneで次のsayまたはthinkを実行したとき
• 対象sprite／cloneが停止したとき
• 緑の旗によるproject開始
• projectの全停止
• TurboWarp runtimeの破棄

Asset Managerへ登録したアセット自体はBubbleの所有物ではありません。不要になった登録画像をメモリから削除する場合は、Bubbleを閉じた後にAsset Managerのdelete asset [NAME] from memoryを使います。

14. マニュアル画像の再生成

図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickのmagickコマンドが必要です。

2つのturbowarp-say-think-*-comparison.pngはrenderer previewから生成した図ではなく、TurboWarp Editorの実画面です。第4章に記載した撮影条件を使い、docs:renderでは上書きしません。

pnpm docs:render
pnpm docs:check

docs:checkは、SVGのviewBox、production renderer／wrapText由来marker、全visual style、GIFの寸法・16フレーム・ループ設定、マニュアルから画像と全16ブロックへの参照、およびPages用HTMLが最新であることを検証します。