@kubohiroya/turbowarp-bubble 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,22 +2,23 @@
2
2
 
3
3
  このマニュアルでは、`turbowarp-bubble`をTurboWarpのカスタム拡張機能として使い、SVG本体、文字、キャラクター表情、目パチ、口パク、「次へ」アイコンを組み合わせたBubbleを表示します。
4
4
 
5
+ > **紙芝居DSL 4.0集約ランタイム:** 集約ランタイムのパレットで**Bubble**見出し直下のドキュメントボタンを押すと、このマニュアルを開けます。集約されたブロックも、ここで説明するstyle、配置、portrait、逐次表示、音声、待機、animation、clone、自動解放の動作を保ち、拡張機能別の名前空間とBubbleアイコンで由来を識別できます。
6
+
5
7
  ![Next1とNext2を個別登録し、入力listenerを準備してBubble内蔵待機を使うブロック例](./assets/block-quick-start.svg)
6
8
 
7
9
  ## 1. 必要な拡張機能
8
10
 
9
- 入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。Bubbleは文字Bubbleの既定`BubbleTextCapability` adapterとしてSVG Textを使います。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
11
+ 入力待ちを含む完全な例では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はBubble待機を使う場合だけ必要です。
10
12
 
11
13
  | 順番 | 拡張機能 | 読み込み先 |
12
14
  | ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
13
15
  | 1 | Temporary Variables | TurboWarpの拡張機能ライブラリから追加 |
14
- | 2 | Async Input 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js` |
15
- | 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
16
- | 4 | Asset Manager 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js` |
17
- | 5 | SVG Text 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js` |
18
- | 6 | Bubble 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js` |
16
+ | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
17
+ | 3 | Runtime Expression 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js` |
18
+ | 4 | Asset Manager 0.12.1 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js` |
19
+ | 5 | Bubble 0.9.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js` |
19
20
 
20
- 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。表示時に既定のSVG Text adapterが、画像・メディア機能の使用時にAsset Managerが、待機開始時にAsync InputかRuntime Expressionが見つからなければ、Bubbleは明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入でき、その場合SVG Textは不要です。
21
+ 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、待機開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。
21
22
 
22
23
  参考:
23
24
 
@@ -56,30 +57,41 @@ register resource [costume:Assets:Next2] as asset [Next2]
56
57
 
57
58
  URL画像を使う場合は、`RESOURCE_ID`へHTTPS URLを指定します。Bubbleに設定できるのは、Asset Managerへ登録済みでMIME typeが`image/*`のアセットだけです。
58
59
 
59
- ## 3. 文字styleを定義する
60
+ ## 3. 文字layout styleを選ぶ
60
61
 
61
- SVG Textで、Bubbleの文字部分に使う名前付きstyleを定義します。
62
+ 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を選択します。
62
63
 
63
64
  ```text
64
- define text style [dialogue-text]
65
- background [#fff4cc]
66
- text [#332200]
67
- font [Noto Sans JP]
68
- size [100]
69
- align [left]
70
- bubble direction [up]
65
+ define bubble style [hero-dialogue] using text style [default]
71
66
  ```
72
67
 
73
- Bubbleは`dialogue-text`という名前を参照します。文字styleとBubble styleはruntime状態なので、通常は緑の旗が押されたときに毎回定義します。
74
-
75
- SVG Text 0.4.xは文字providerです。名前付き文字styleの定義、SVG文字skinの生成、文字幅の測定を担当します。Bubbleの配置は`set bubble placement`で設定し、tailや吹き出し外形はSVG Text providerの責務ではありません。
68
+ 独自のfont、色、alignmentを使うアプリhostは、`createSvgTextLayoutComposition()`へstyleを定義し、`createSvgTextOverlayTextCapability()`でBubbleへ注入します。custom profileは同じ`layoutText()`を使い、既定overlay backendではSVG文字skinを生成しません。Bubbleの配置、tail、吹き出し外形はBubble側が担当します。
76
69
 
77
70
  ## 4. Bubble styleを定義する
78
71
 
79
- まず、Bubble style名とSVG Textのstyle名を関連付けます。
72
+ 基本Bubbleでは短いブロックをそのまま使います。組み込みBubble style `say`/`think`がそれぞれ自動選択されます。
73
+
74
+ ```text
75
+ say [こんにちは!]
76
+ think [うーん…]
77
+ ```
78
+
79
+ ### TurboWarp標準との比較
80
+
81
+ 次の画像は、1つのTurboWarp Editor projectで英語UIを使い、`Cat` spriteを`x=-80`、`y=0`、サイズ`80%`、Stageを白背景、入力を`Hello!`/`Hmm...`に揃えて撮影した実画面です。左列はTurboWarp標準の見た目ブロックです。右列は対応する組み込み`say`/`think` styleを使うBubbleの短い基本ブロックで、定義ブロックもsetterも使っていません。
82
+
83
+ ![TurboWarp標準のsay・think吹き出しとBubble基本profileを同じStageで比較した実画面](./assets/turbowarp-say-think-stage-comparison.png)
84
+
85
+ Stage図では、右側配置、内容に追従する本体、Actor側へ向くspeech tail/thought trailを同じ条件で確認できます。Bubbleは独立したSVG surfaceを描画しており、全4panelとも実際のTurboWarp Stageを切り出したものです。
86
+
87
+ ![TurboWarp標準のsay・thinkブロックと、設定不要のBubble基本say・thinkブロックおよび組み込みdefault profile値を比較したスクリーンショット](./assets/turbowarp-say-think-block-comparison.png)
88
+
89
+ ブロック図は設定不要の基本経路と、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互換用の非表示定義として残します。
90
+
91
+ 次のsetterを使うと、意図的にcustom profileへ切り替わります。
80
92
 
81
93
  ```text
82
- define bubble style [hero-dialogue] using text style [dialogue-text]
94
+ define bubble style [hero-dialogue] using text style [default]
83
95
  set bubble placement [up-right] for bubble style [hero-dialogue]
84
96
  set bubble distance [12] for bubble style [hero-dialogue]
85
97
  set bubble visual style [NORMAL] for bubble style [hero-dialogue]
@@ -95,7 +107,7 @@ Actor相対の16方向は、各方向をActor、Bubble外形、tail、文字を
95
107
 
96
108
  背景相対3図はStage外枠、安全領域、Bubble外形寸法、水平中央線、基準辺/中心を示します。外形はBubble側の共有`renderBubbleSvg`で生成しており、TurboWarp Editorで本体drawableを生成するrendererと同じです。
97
109
 
98
- Actor相対では、Actor中心からBubble全体の中心へ向かう方向を指定します。menuには次の16正規方向があります。
110
+ Actor相対placementはcustom profileへ適用され、Actor中心からBubble全体の中心へ向かう方向を指定します。未変更の基本profileはScratch標準の右側優先・自動左反転を使います。menuには次の16正規方向があります。
99
111
 
100
112
  ```text
101
113
  up / up-up-right / up-right / right-up-right
@@ -186,7 +198,7 @@ set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bu
186
198
  set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
187
199
  set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
188
200
  set bubble voice [HeroVoice] for bubble style [hero-dialogue]
189
- say [海へ出発!] with bubble style [hero-dialogue]
201
+ show [海へ出発!] with bubble style [hero-dialogue]
190
202
  finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
191
203
  ```
192
204
 
@@ -200,7 +212,7 @@ finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] sec
200
212
  set runtime variable [input] to []
201
213
  listen for key [Space] set runtime var [input] to [pressed]
202
214
  listen for touch on this sprite set runtime var [input] to [pressed]
203
- say [海へ出発!] with bubble style [hero-dialogue]
215
+ show [海へ出発!] with bubble style [hero-dialogue]
204
216
  wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
205
217
  close this bubble
206
218
  ```
@@ -242,14 +254,15 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
242
254
 
243
255
  TurboWarp adapterはこれらをschedulerのフレームごとに進め、各フレームの進行率へ`ease`を適用します。`shake`は吹き出し全体を方向・回数付きで揺らし、`explode`はportraitと文字を含むsurface全体を拡大して元へ戻し、`animate bubble shape`は指定時間中に現在の外形から`THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などへcross-fadeします。仕様では、吹き出しが表示される時点を「表示開始」、隠れる時点を「表示終了」と呼びます。
244
256
 
245
- ## 9. sayとthink
257
+ 表示中のBubbleを消すときは`close this bubble`を使います。設定済みの表示終了animationを実行してから、Bubbleのtimerと描画resourceを解放します。`set bubble hide animation ...`は終了時の演出を設定するだけで、このブロック自体はBubbleを消しません。組み込み基本profileでは、`say`/`think`へ空文字を渡してもTurboWarp標準と同様にcloseします。closeは非表示instanceを保持せず表示を破棄するため、別の`hide`ブロックは公開しません。
258
+
259
+ ## 9. named Bubble styleを表示する
246
260
 
247
261
  ```text
248
- say [MESSAGE] with bubble style [STYLE]
249
- think [MESSAGE] with bubble style [STYLE]
262
+ show [MESSAGE] with bubble style [STYLE]
250
263
  ```
251
264
 
252
- どちらも同じvisual style、表情レイヤー、placement、animation mode制御を使えます。`say`/`think`だけで形状を固定せず、`set bubble visual style`で`NORMAL`、`THINKING`などを明示的に選びます。Composition APIのsurfaceには`say`/`think`のkindも渡されるため、独自hostではkindに応じた追加表現も可能です。
265
+ 選択した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を導きます。
253
266
 
254
267
  同じsprite、clone、またはStageで新しい`say`/`think`を実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。
255
268
 
@@ -261,50 +274,53 @@ Bubble styleの定義は拡張機能内で共有されますが、表示中のBu
261
274
  2. 各clone自身から`say`または`think`を実行します。
262
275
  3. animation mode変更とcloseも、表示したのと同じcloneから実行します。
263
276
 
264
- cloneが停止・削除された場合は、そのtargetに属するtimer、SVG Text skin、drawableが自動解放されます。
277
+ cloneが停止・削除された場合は、そのtargetに属するtimer、overlay DOM、画像leaseが自動解放されます。明示的な`scratch-render`ではskinとdrawableも解放されます。
265
278
 
266
279
  ## 11. ブロック一覧
267
280
 
268
- | ブロック | 説明 |
269
- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
270
- | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
271
- | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
272
- | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
273
- | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
274
- | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
275
- | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含む全体のscaleを設定する |
276
- | `set portrait base [ASSET] for bubble style [STYLE]` | portraitのベース画像を設定する |
277
- | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | portraitの有無、端/隅の配置、変形、角丸を設定する |
278
- | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分と間隔を設定する |
279
- | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分と間隔を設定する |
280
- | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-continue`中の「次へ」アニメーションを設定する |
281
- | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | CHARACTER/WORD/LINE/BLOCKの逐次表示を設定する |
282
- | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | WORDの区切り文字集合と表示可否を設定する |
283
- | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | 表示単位ごとの効果音を設定する |
284
- | `set bubble voice [ASSET] for bubble style [STYLE]` | 表示開始時のフルボイスを設定する |
285
- | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | 未表示単位を最後まで進め、条件またはtimeoutを待つ |
286
- | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示開始animationを設定する |
287
- | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示終了animationを設定する |
288
- | `animate this bubble [MOTION]` | Bubble全体のanimationを再生する |
289
- | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | 吹き出し全体を指定方向へ揺らす |
290
- | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | 吹き出し全体を相対倍率で変化させる |
291
- | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Bubble外形を時間経過で切り替える |
292
- | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始・置換する |
293
- | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始・置換する |
294
- | `set this bubble animation mode [MODE]` | `talking`、`awaiting-continue`、`idle`からmodeを選ぶ |
295
- | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
296
- | `close this bubble` | 自分のBubbleと所有resourceを解放する |
297
- | `Bubble version` | Bubble実装versionを返す |
281
+ | ブロック | 説明 |
282
+ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
283
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
284
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
285
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
286
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | 不可分なSVG本体+tail/trailの組を10種類から設定する |
287
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
288
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含む全体のscaleを設定する |
289
+ | `set portrait base [ASSET] for bubble style [STYLE]` | portraitのベース画像を設定する |
290
+ | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | portraitの有無、端/隅の配置、変形、角丸を設定する |
291
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分と間隔を設定する |
292
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分と間隔を設定する |
293
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-continue`中の「次へ」アニメーションを設定する |
294
+ | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | CHARACTER/WORD/LINE/BLOCKの逐次表示を設定する |
295
+ | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | WORDの区切り文字集合と表示可否を設定する |
296
+ | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | 表示単位ごとの効果音を設定する |
297
+ | `set bubble voice [ASSET] for bubble style [STYLE]` | 表示開始時のフルボイスを設定する |
298
+ | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | 未表示単位を最後まで進め、条件またはtimeoutを待つ |
299
+ | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示開始animationを設定する |
300
+ | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示終了animationを設定する |
301
+ | `animate this bubble [MOTION]` | Bubble全体のanimationを再生する |
302
+ | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | 吹き出し全体を指定方向へ揺らす |
303
+ | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | 吹き出し全体を相対倍率で変化させる |
304
+ | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Bubble外形を時間経過で切り替える |
305
+ | `say [MESSAGE]` | 組み込み`say` styleのspeech本体+tailを表示する |
306
+ | `think [MESSAGE]` | 組み込み`think` styleのthought本体+round trailを表示する |
307
+ | `show [MESSAGE] with bubble style [STYLE]` | styleが持つ本体+tail/trailの一組を表示する |
308
+ | `set this bubble animation mode [MODE]` | `talking`、`awaiting-continue`、`idle`からmodeを選ぶ |
309
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
310
+ | `close this bubble` | 自分のBubbleと所有resourceを解放する |
311
+ | `Bubble version` | Bubble実装versionを返す |
312
+
313
+ 旧`say/think [MESSAGE] with bubble style [STYLE]` opcodeを使う保存済みprojectは引き続き動作しますが、この互換ブロック2個はpaletteに表示しません。新しいscriptでは統合`show`ブロックを使い、選択styleだけで本体とtail/trailの形を決めます。
298
314
 
299
315
  ## 12. よくあるエラー
300
316
 
301
317
  | 状況 | 原因と対処 |
302
318
  | ---------------------------------- | ------------------------------------------------------------------------ |
303
- | Asset Managerを要求するエラー | 画像・メディアアセットを使う前にAsset Manager 0.7.xを読み込む |
304
- | 既定text adapterを要求するエラー | SVG Text 0.4.xをサンドボックスなしで読み込む |
319
+ | Asset Managerを要求するエラー | 画像・メディアアセットを使う前にAsset Manager 0.12.xを読み込む |
320
+ | SVG overlay backendのエラー | `renderer.addOverlay()`対応hostを使うか`scratch-render`を明示する |
305
321
  | Async Inputを要求するエラー | Bubble待機より前にAsync Input 0.3.xをサンドボックスなしで読み込む |
306
322
  | Runtime Expressionを要求するエラー | Bubble待機より前にRuntime Expression 0.3.xをサンドボックスなしで読み込む |
307
- | `bubble style is not defined` | `define bubble style`を先に実行する。緑の旗の再実行時も再定義する |
323
+ | `bubble style is not defined` | 組み込みの短いsay/thinkを使うか、named custom styleを先に定義する |
308
324
  | image assetが未登録 | `register resource ... as asset ...`の完了後にBubbleを表示する |
309
325
  | assetが画像ではない | `MIME type of asset [NAME]`で`image/*`か確認する |
310
326
  | continue framesが1枚 | 2枚以上にするか、空にしてcontinue表示を解除する |
@@ -315,7 +331,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG
315
331
 
316
332
  ## 13. 自動解放されるタイミング
317
333
 
318
- 次の場合、Bubbleが所有するtimer、text skin、renderer drawableは自動的に解放されます。
334
+ 次の場合、Bubbleが所有するtimer、overlay DOM、画像leaseは自動的に解放されます。`scratch-render`を明示した場合はtext skinとrenderer drawableも解放されます。
319
335
 
320
336
  - `close this bubble`
321
337
  - 同じsprite/cloneで次の`say`または`think`を実行したとき
@@ -330,6 +346,8 @@ Asset Managerへ登録したアセット自体はBubbleの所有物ではあり
330
346
 
331
347
  図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickの`magick`コマンドが必要です。
332
348
 
349
+ 2つの`turbowarp-say-think-*-comparison.png`はrenderer previewから生成した図ではなく、TurboWarp Editorの実画面です。第4章に記載した撮影条件を使い、`docs:render`では上書きしません。
350
+
333
351
  ```sh
334
352
  pnpm docs:render
335
353
  pnpm docs:check
@@ -2,22 +2,23 @@
2
2
 
3
3
  This manual explains how to use `turbowarp-bubble` as an unsandboxed TurboWarp custom extension. A Bubble combines an SVG body, text, a character portrait, blinking and lip-sync layers, and an animated continue indicator.
4
4
 
5
+ > **Kamishibai DSL 4.0 bundle:** In the combined runtime palette, click the documentation button directly below the **Bubble** member heading to open this manual. The bundled blocks keep the styles, placement, portrait, reveal, audio, wait, animation, clone, and cleanup behavior documented here; their member namespace and Bubble icon identify their origin.
6
+
5
7
  ![A quick-start block sequence that registers Next1 and Next2 separately, prepares input listeners, then uses Bubble's integrated wait](./assets/block-quick-start.svg)
6
8
 
7
9
  ## 1. Load the required extensions
8
10
 
9
- The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. Bubble uses SVG Text as its default `BubbleTextCapability` adapter for text bubbles. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
11
+ The complete input-wait example uses five extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. Bubble bundles the host-neutral SVG Text 0.8.1 layout provider and creates no text skin on its default SVG overlay. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
10
12
 
11
13
  | Order | Extension | URL |
12
14
  | ----: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
13
15
  | 1 | Temporary Variables | Add from the TurboWarp extension library |
14
- | 2 | Async Input 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js` |
15
- | 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
16
- | 4 | Asset Manager 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js` |
17
- | 5 | SVG Text 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js` |
18
- | 6 | Bubble 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js` |
16
+ | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
17
+ | 3 | Runtime Expression 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js` |
18
+ | 4 | Asset Manager 0.12.1 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js` |
19
+ | 5 | Bubble 0.9.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js` |
19
20
 
20
- To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if the default SVG Text adapter is missing when it displays a Bubble, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait. The lower-level Composition API can use another text capability and does not require SVG Text.
21
+ To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if the renderer lacks the default SVG overlay APIs, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait. The lower-level Composition API can inject another text capability.
21
22
 
22
23
  See also:
23
24
 
@@ -56,30 +57,41 @@ register resource [costume:Assets:Next2] as asset [Next2]
56
57
 
57
58
  For a remote image, pass its HTTPS URL as `RESOURCE_ID`. Bubble accepts only assets already registered with Asset Manager whose MIME type is `image/*`.
58
59
 
59
- ## 3. Define a text style
60
+ ## 3. Select a text layout style
60
61
 
61
- Use SVG Text to define the named style for the Bubble's text layer.
62
+ Standalone Bubble bundles the SVG Text 0.8.1 layout composition and installs two Bubble styles: `say` owns the speech body and speech tail, while `think` owns the thought body and round trail. A style's body and tail/trail shapes are one visual choice, not separately selected properties. The short `say [MESSAGE]` and `think [MESSAGE]` blocks select the matching style automatically, so the basic path needs neither a style definition nor a style input. Both styles use the reserved text profile `default`, a content-sized body, 14px Helvetica text, right-first placement with a fit-dependent left flip, 330-character block-input limit, and empty-message close behavior. Their 4px SVG stroke is painted before the white fill, hiding the inner half so the visible outline matches TurboWarp's standard bubble. Any other text style name or explicit style-setting block selects the custom profile. Custom text styles are initialized on first use with transparent-background SVG Text defaults. If a project separately loads the stock SVG Text 0.8.1 extension before Bubble, Bubble uses its public `getLayoutCapability()` instead and preserves the named styles defined by SVG Text blocks. An older loaded SVG Text extension without that handoff produces an explicit compatibility error rather than silently replacing the style; select the documented scratch-render fallback only when needed.
62
63
 
63
64
  ```text
64
- define text style [dialogue-text]
65
- background [#fff4cc]
66
- text [#332200]
67
- font [Noto Sans JP]
68
- size [100]
69
- align [left]
70
- bubble direction [up]
65
+ define bubble style [hero-dialogue] using text style [default]
71
66
  ```
72
67
 
73
- Bubble refers to this style as `dialogue-text`. Text and Bubble styles are runtime state, so normally define them again whenever the green flag is clicked.
74
-
75
- SVG Text 0.4.x is a text provider: it defines named text styles, creates SVG text skins, and measures text. Bubble placement is configured by `set bubble placement`; the SVG Text provider does not own Bubble direction, tail, or outer shape.
68
+ Application hosts that need custom fonts, colors, or alignment can define styles on `createSvgTextLayoutComposition()` and inject them through `createSvgTextOverlayTextCapability()`. The custom profile uses the same `layoutText()` API and does not create an SVG text skin on the default overlay backend. Bubble owns placement, tail, and outer shape.
76
69
 
77
70
  ## 4. Define a Bubble style
78
71
 
79
- First associate a Bubble style name with an SVG Text style name.
72
+ For a basic Bubble, use the short blocks directly. They select the built-in Bubble styles `say` and `think`, respectively:
80
73
 
81
74
  ```text
82
- define bubble style [hero-dialogue] using text style [dialogue-text]
75
+ say [Hello!]
76
+ think [Hmm…]
77
+ ```
78
+
79
+ ### TurboWarp standard comparison
80
+
81
+ These screenshots come from one TurboWarp Editor project using the English UI, a `Cat` sprite at `x=-80`, `y=0`, size `80%`, a white Stage, and matching `Hello!` / `Hmm...` inputs. The standard Looks blocks are on the left. Bubble's short basic blocks are on the right and use their matching built-in `say` / `think` styles; no definition or setter block is used.
82
+
83
+ ![TurboWarp standard say and think bubbles compared on the Stage with Bubble's basic profile](./assets/turbowarp-say-think-stage-comparison.png)
84
+
85
+ The Stage panels show the right-side placement, content-sized body, and the speech tail or thought trail pointing back toward the Actor in each implementation. Bubble renders an independent SVG surface, and every panel is a crop of the actual TurboWarp Stage.
86
+
87
+ ![TurboWarp standard say and think blocks compared with Bubble's no-setup basic say and think blocks and built-in default profile values](./assets/turbowarp-say-think-block-comparison.png)
88
+
89
+ The block image shows the no-setup path and the unified custom-style block. The short blocks select the matching built-in styles automatically. The callout shows each inseparable body-plus-tail/trail pair, maps both styles to the reserved text profile `default`, and lists the shared typography, geometry, colors, border paint order, and placement. Use `show [MESSAGE] with bubble style [STYLE]` for named custom styles. The former styled say/think opcodes remain hidden compatibility definitions for saved projects.
90
+
91
+ The following setters intentionally switch the style to the custom profile:
92
+
93
+ ```text
94
+ define bubble style [hero-dialogue] using text style [default]
83
95
  set bubble placement [up-right] for bubble style [hero-dialogue]
84
96
  set bubble distance [12] for bubble style [hero-dialogue]
85
97
  set bubble visual style [NORMAL] for bubble style [hero-dialogue]
@@ -95,7 +107,7 @@ Each of the 16 actor-relative directions is shown as a complete mini-scene conta
95
107
 
96
108
  The three stage-relative diagrams show the Stage frame, safe area, Bubble dimensions, horizontal centerline, and relevant reference edge or center. The diagrams and the TurboWarp drawable are generated by the same shared `renderBubbleSvg` implementation.
97
109
 
98
- Actor-relative placement specifies the direction from the actor's center toward the center of the entire Bubble. The menu provides these 16 canonical directions:
110
+ Actor-relative placement applies to the custom profile and specifies the direction from the actor's center toward the center of the entire Bubble. The untouched basic profile uses Scratch's right-first placement and automatic left flip. The menu provides these 16 canonical directions:
99
111
 
100
112
  ```text
101
113
  up / up-up-right / up-right / right-up-right
@@ -186,7 +198,7 @@ set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bu
186
198
  set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
187
199
  set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
188
200
  set bubble voice [HeroVoice] for bubble style [hero-dialogue]
189
- say [Let's head for the sea!] with bubble style [hero-dialogue]
201
+ show [Let's head for the sea!] with bubble style [hero-dialogue]
190
202
  finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
191
203
  ```
192
204
 
@@ -200,7 +212,7 @@ finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] sec
200
212
  set runtime variable [input] to []
201
213
  listen for key [Space] set runtime var [input] to [pressed]
202
214
  listen for touch on this sprite set runtime var [input] to [pressed]
203
- say [Let's head for the sea!] with bubble style [hero-dialogue]
215
+ show [Let's head for the sea!] with bubble style [hero-dialogue]
204
216
  wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
205
217
  close this bubble
206
218
  ```
@@ -242,14 +254,15 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
242
254
 
243
255
  The TurboWarp adapter advances these motions on scheduler frames and applies `ease` to each frame. `shake` applies direction and count to the complete Bubble surface, `explode` expands and returns the relative scale of text and portrait together, and `animate bubble shape` cross-fades the current outline into styles such as `THINKING`, `DREAMING`, `YELLING`, `WAVY`, or `WHISPERING` during the requested speed and duration.
244
256
 
245
- ## 9. `say` and `think`
257
+ Use `close this bubble` to remove the current Bubble. It runs the configured hide animation and then releases the Bubble's timers and rendering resources. `set bubble hide animation ...` only configures that exit effect; it does not remove a Bubble by itself. For the built-in basic profile, passing an empty value to `say` or `think` also closes the Bubble, matching TurboWarp's standard behavior. Bubble does not expose a separate `hide` block because closing destroys the display rather than preserving a hidden instance for later reuse.
258
+
259
+ ## 9. Showing a named Bubble style
246
260
 
247
261
  ```text
248
- say [MESSAGE] with bubble style [STYLE]
249
- think [MESSAGE] with bubble style [STYLE]
262
+ show [MESSAGE] with bubble style [STYLE]
250
263
  ```
251
264
 
252
- Both blocks support the same visual styles, portrait layers, placement, and animation-mode control. The block name does not force a shape; explicitly choose `NORMAL`, `THINKING`, or another shape with `set bubble visual style`. The Composition API surface still receives a `say`/`think` kind, so a custom host can add its own kind-dependent behavior.
265
+ The selected Bubble style determines the body and tail/trail together, along with its text profile, portrait layers, placement, and animation settings. `set bubble visual style` selects an inseparable pair such as `NORMAL` (speech body + speech tail) or `THINKING` (thought body + round trail); there is no independent tail-shape setting. The standalone extension derives its internal rendering kind from that style instead of asking the display block for a second, potentially conflicting choice.
253
266
 
254
267
  Running a new `say` or `think` on the same sprite, clone, or Stage disposes the previous Bubble and its timers/drawables before replacing it. The Stage supports stage-relative placement only.
255
268
 
@@ -261,7 +274,7 @@ Bubble style definitions are shared within the extension, but each sprite or clo
261
274
  2. Run `say` or `think` from each clone itself.
262
275
  3. Change the animation mode and close the Bubble from the same clone that displayed it.
263
276
 
264
- When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables owned by that target are released automatically.
277
+ When a clone stops or is deleted, its timers, overlay DOM, and image leases are released automatically. Explicit `scratch-render` mode also releases skins and drawables.
265
278
 
266
279
  ## 11. Block reference
267
280
 
@@ -270,7 +283,7 @@ When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables
270
283
  | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
271
284
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
272
285
  | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
273
- | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten SVG body shapes |
286
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten inseparable SVG body + tail/trail pairs |
274
287
  | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Set the nominal border-to-tip tail length |
275
288
  | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Set body position and whole-Bubble scale, including text |
276
289
  | `set portrait base [ASSET] for bubble style [STYLE]` | Set the portrait base image |
@@ -289,33 +302,36 @@ When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables
289
302
  | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shake the complete Bubble surface |
290
303
  | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Apply relative scale cycles to the Bubble |
291
304
  | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transition the Bubble outline |
292
- | `say [MESSAGE] with bubble style [STYLE]` | Start or replace a `say` Bubble in `talking` mode |
293
- | `think [MESSAGE] with bubble style [STYLE]` | Start or replace a `think` Bubble in `talking` mode |
305
+ | `say [MESSAGE]` | Show built-in style `say`: speech body and speech tail |
306
+ | `think [MESSAGE]` | Show built-in style `think`: thought body and round trail |
307
+ | `show [MESSAGE] with bubble style [STYLE]` | Show the complete body and tail/trail pair owned by a style |
294
308
  | `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-continue`, or `idle` for this Bubble |
295
309
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
296
310
  | `close this bubble` | Release this target's Bubble and owned resources |
297
311
  | `Bubble version` | Report the Bubble implementation version |
298
312
 
313
+ Saved projects using the former `say/think [MESSAGE] with bubble style [STYLE]` opcodes continue to run, but those two compatibility blocks are hidden from the palette. New scripts use the unified `show` block so the selected style alone determines the complete body and tail/trail shape.
314
+
299
315
  ## 12. Troubleshooting
300
316
 
301
- | Symptom | Cause and solution |
302
- | ------------------------------------ | --------------------------------------------------------------------------- |
303
- | Asset Manager required error | Load Asset Manager 0.7.x without sandbox before using image/media assets |
304
- | Default text adapter required error | Load SVG Text 0.4.x without sandbox |
305
- | Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
306
- | Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
307
- | `bubble style is not defined` | Run `define bubble style` first, including after restarting with green flag |
308
- | Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
309
- | Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
310
- | Only one continue frame | Supply at least two frames, or clear the setting |
311
- | Frame interval error | Use a finite `SECONDS` value greater than zero |
312
- | Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
313
- | Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
314
- | Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
317
+ | Symptom | Cause and solution |
318
+ | ------------------------------------ | ------------------------------------------------------------------------------- |
319
+ | Asset Manager required error | Load Asset Manager 0.12.x without sandbox before using image/media assets |
320
+ | SVG overlay backend error | Use a host with `renderer.addOverlay()` or explicitly select `scratch-render` |
321
+ | Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
322
+ | Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
323
+ | `bubble style is not defined` | Use the built-in short say/think blocks, or define the named custom style first |
324
+ | Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
325
+ | Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
326
+ | Only one continue frame | Supply at least two frames, or clear the setting |
327
+ | Frame interval error | Use a finite `SECONDS` value greater than zero |
328
+ | Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
329
+ | Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
330
+ | Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
315
331
 
316
332
  ## 13. Automatic cleanup
317
333
 
318
- Bubble automatically releases its owned timers, text skins, and renderer drawables when:
334
+ Bubble automatically releases its owned timers, overlay DOM, and image leases in the following cases. Explicit `scratch-render` mode also releases its text skins and renderer drawables.
319
335
 
320
336
  - `close this bubble` runs;
321
337
  - the same sprite or clone runs another `say` or `think`;
@@ -330,6 +346,8 @@ Assets registered with Asset Manager are not owned by Bubble. To remove an unuse
330
346
 
331
347
  The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick `magick` command.
332
348
 
349
+ The two `turbowarp-say-think-*-comparison.png` files are real TurboWarp Editor screenshots rather than generated renderer previews. They use the capture conditions documented in section 4 and are not overwritten by `docs:render`.
350
+
333
351
  ```sh
334
352
  pnpm docs:render
335
353
  pnpm docs:check