@kubohiroya/turbowarp-bubble 0.1.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.
@@ -0,0 +1,292 @@
1
+ # TurboWarp Bubble ブロック利用マニュアル
2
+
3
+ このマニュアルでは、`turbowarp-bubble`をTurboWarpのカスタム拡張機能として使い、SVG本体、文字、キャラクター表情、目パチ、口パク、「次へ」アイコンを組み合わせたBubbleを表示します。
4
+
5
+ ![Next1とNext2を個別登録し、入力listenerを準備してBubble内蔵待機を使うブロック例](./assets/block-quick-start.svg)
6
+
7
+ ## 1. 必要な拡張機能
8
+
9
+ 入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、残る5つのカスタム拡張機能は「サンドボックスなしで実行」を許可して読み込みます。Async InputとRuntime ExpressionはBubbleの待機ブロックより前に、Asset ManagerとSVG Textは最初のBubble表示より前に読み込みます。
10
+
11
+ | 順番 | 拡張機能 | 読み込み先 |
12
+ | ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
13
+ | 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.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.3.0/dist/svg-text.js` |
18
+ | 6 | Bubble 0.1.0 | npm公開後は`https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.1.0/dist/turbowarp-bubble.js` |
19
+
20
+ 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。表示時にAsset ManagerかSVG Textが、待機開始時にAsync InputかRuntime Expressionが見つからなければ、Bubbleは明示的なエラーを返します。
21
+
22
+ 参考:
23
+
24
+ - [Asset Manager 日本語ガイド](https://kubohiroya.github.io/turbowarp-asset-manager/ja/)
25
+ - [Async Input 日本語ガイド](https://kubohiroya.github.io/turbowarp-async-input/ja/)
26
+ - [Runtime Expression 日本語ガイド](https://kubohiroya.github.io/turbowarp-runtime-expression/ja/)
27
+ - [SVG Text 日本語ガイド](https://kubohiroya.github.io/turbowarp-svg-text/ja/)
28
+
29
+ ## 2. 表情画像を準備する
30
+
31
+ 例では`Assets`という素材用spriteに、次のcostumeを入れます。素材用spriteは画面上で非表示でも構いません。
32
+
33
+ | costume | Asset Managerへ登録する名前 | 内容 |
34
+ | ----------------- | --------------------------- | ------------------------------------------------ |
35
+ | `HeroFace` | `HeroFace` | 顔、髪、輪郭などのベース。動かす目と口は含めない |
36
+ | `HeroEyesOpen` | `HeroEyesOpen` | 開いた目だけを描いた透明差分 |
37
+ | `HeroEyesClosed` | `HeroEyesClosed` | 閉じた目だけを描いた透明差分 |
38
+ | `HeroMouthClosed` | `HeroMouthClosed` | 閉じた口だけを描いた透明差分 |
39
+ | `HeroMouthOpen` | `HeroMouthOpen` | 開いた口だけを描いた透明差分 |
40
+ | `Next1` | `Next1` | 「次へ」アイコンの1枚目 |
41
+ | `Next2` | `Next2` | 「次へ」アイコンの2枚目 |
42
+
43
+ ベース、目、口の画像は同じcanvasサイズと同じ中心位置で作ります。差分画像の背景は透明にしてください。位置やcanvasサイズが異なると、レイヤーを重ねたときに目や口がずれます。
44
+
45
+ Asset Managerのブロックで各costumeを登録します。
46
+
47
+ ```text
48
+ register resource [costume:Assets:HeroFace] as asset [HeroFace]
49
+ register resource [costume:Assets:HeroEyesOpen] as asset [HeroEyesOpen]
50
+ register resource [costume:Assets:HeroEyesClosed] as asset [HeroEyesClosed]
51
+ register resource [costume:Assets:HeroMouthClosed] as asset [HeroMouthClosed]
52
+ register resource [costume:Assets:HeroMouthOpen] as asset [HeroMouthOpen]
53
+ register resource [costume:Assets:Next1] as asset [Next1]
54
+ register resource [costume:Assets:Next2] as asset [Next2]
55
+ ```
56
+
57
+ URL画像を使う場合は、`RESOURCE_ID`へHTTPS URLを指定します。Bubbleに設定できるのは、Asset Managerへ登録済みでMIME typeが`image/*`のアセットだけです。
58
+
59
+ ## 3. 文字styleを定義する
60
+
61
+ SVG Textで、Bubbleの文字部分に使う名前付きstyleを定義します。
62
+
63
+ ```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]
71
+ ```
72
+
73
+ Bubbleは`dialogue-text`という名前を参照します。文字styleとBubble styleはruntime状態なので、通常は緑の旗が押されたときに毎回定義します。
74
+
75
+ SVG Text 0.3.xではblock contract上`bubble direction`入力が残っていますが、Bubbleが`setText`で生成する文字drawableの配置には使われません。Bubbleの配置は次節の`set bubble placement`で設定します。SVG Textからのdirection削除は、破壊的変更が可能な次版で行います。
76
+
77
+ ## 4. Bubble styleを定義する
78
+
79
+ まず、Bubble style名とSVG Textのstyle名を関連付けます。
80
+
81
+ ```text
82
+ define bubble style [hero-dialogue] using text style [dialogue-text]
83
+ set bubble placement [up-right] for bubble style [hero-dialogue]
84
+ set bubble distance [12] for bubble style [hero-dialogue]
85
+ set bubble visual style [NORMAL] for bubble style [hero-dialogue]
86
+ set bubble tail length [18] for bubble style [hero-dialogue]
87
+ set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
88
+ ```
89
+
90
+ ### Actor相対と背景相対のplacement
91
+
92
+ ![Actor相対の16方向・角度指定と、背景相対の3配置を比較する図](./assets/placement-guide.svg)
93
+
94
+ Actor相対の16方向は、各方向をActor、Bubble外形、tail、文字を含む独立したミニシーンで示しています。三角形tailの基部2点は実際の本体border上にあり、本体polygonとのJSClipper union後の単一pathを描くため、接合部に内部border線は残りません。
95
+
96
+ 背景相対3図はStage外枠、安全領域、Bubble外形寸法、水平中央線、基準辺/中心を示します。外形はBubble側の共有`renderBubbleSvg`で生成しており、TurboWarp Editorで本体drawableを生成するrendererと同じです。
97
+
98
+ Actor相対では、Actor中心からBubble全体の中心へ向かう方向を指定します。menuには次の16正規方向があります。
99
+
100
+ ```text
101
+ up / up-up-right / up-right / right-up-right
102
+ right / right-down-right / down-right / down-down-right
103
+ down / down-down-left / down-left / left-down-left
104
+ left / left-up-left / up-left / up-up-left
105
+ ```
106
+
107
+ `north`、`north-northeast`、`northeast`などのcompass aliasも直接入力またはreporterから指定できます。数値はScratch方向と同じ0〜360度で、`0`は上、`90`は右、`180`は下、`270`は左、`360`は`0`へ正規化されます。任意角度は16方向へ丸めません。placementを設定しないstyleは`up-right`になります。
108
+
109
+ 背景相対はActorから生える方向を持たず、Stage安全領域へ配置します。
110
+
111
+ | placement | 配置 |
112
+ | ------------- | ----------------------------- |
113
+ | `HEADER_LIKE` | Stage安全領域上部、水平中央 |
114
+ | `CENTER` | Stage安全領域の水平・垂直中央 |
115
+ | `FOOTER_LIKE` | Stage安全領域下部、水平中央 |
116
+
117
+ 背景相対placementはActorの座標、bounds、可視性に依存しません。Stageから`say`/`think`を実行する場合も、この3値のいずれかを設定します。背景相対のBubble bodyにはActorを指すtailを描画しません。
118
+
119
+ ### Actorとの距離、tail、本体の位置・拡大率
120
+
121
+ ![Actor相対のdistance、tail length、offset、scaleを実際のBubble SVGで比較する図](./assets/actor-transform-guide.svg)
122
+
123
+ - `distance`(既定`12`)はActor boundsからtail先端までの距離です。Actor boundsとは、描画済みActorをStage座標で囲むAABB(上下左右のbounding box)です。
124
+ - `tail length`(既定`18`)は通常位置におけるBubble borderからtail先端までの基準長です。
125
+ - `offset x/y/scale`(既定`[0, 0, 100]`)は、xが右正、yが上正、scaleが百分率です。`[10, -10, 120]`なら、本体を右10・下10へ補正し、120%にします。
126
+
127
+ scaleは外形だけでなく、SVG Textの文字、表情ベース・目パチ・口パク、次へアイコン、内部余白へ一体で適用されるため、表示上のフォントサイズも同じ比率で変わります。scaleだけを変更すると、本体中心を拡大半径分だけActorから離してActor側の間隔を維持します。x/y offsetはその後に加算し、tail先端を固定したまま本体borderとのunionを再生成するため、offset後のtail実長は基準値から変化します。
128
+
129
+ Stage端では、拡大後のBubble全体を画面内へ収めるクランプが優先されるため、指定距離を保てない場合があります。背景相対の`HEADER_LIKE`/`CENTER`/`FOOTER_LIKE`では、これらのActor相対設定を使用しません。
130
+
131
+ ### 幅・自動改行・禁則処理
132
+
133
+ ![maxWidthの違いによる自動改行と、日本語禁則処理の例](./assets/width-linebreak-guide.svg)
134
+
135
+ 図の改行結果はproductionの`wrapText`を直接実行して生成しています。`@cto.af/linebreak`がUnicode UAX #14の改行候補を返し、`Intl.Segmenter`の書記素境界で絞り込んだ後、実測幅の上限に収まる最後の候補を選びます。句読点、閉じ括弧、小書き仮名、長音、結合emojiの途中で不自然に分割しません。
136
+
137
+ ### Bubble visual styleの形状例
138
+
139
+ ![10種類のBubble visual styleを同じSVG rendererで比較する図](./assets/bubble-style-gallery.svg)
140
+
141
+ 形状候補は`NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`です。次のblockでBubble styleごとに選択します。
142
+
143
+ ```text
144
+ set bubble visual style [YELLING] for bubble style [hero-dialogue]
145
+ ```
146
+
147
+ 図とTurboWarp Editorの本体drawableはBubble側の共有`renderBubbleSvg`から生成しています。三角形tailを持つ形状は[platener/jsclipper](https://github.com/platener/jsclipper)による本体との和集合です。`THINKING`/`DREAMING`は丸trailのためunion対象外です。Actor相対ではActorを向くtailを生成し、背景相対ではtailを付けません。`NO_BUBBLE`では本体drawableを非表示にして文字・表情などだけを表示します。
148
+
149
+ visual styleを省略した場合は`NORMAL`です。本体drawableは文字・portraitより先に生成して背面へ置きます。`close this bubble`、対象sprite/cloneの停止、runtime破棄時には、本体drawableとBubbleが所有するSVG skinも解放します。
150
+
151
+ `NEGATIVE`はfill colorとborder colorで表現できるため独立styleにはしません。orientationとsegmentsも公開入力にせず、幅、フォント、文字数、禁則処理後の行数から外形寸法を自動計算する方針です。
152
+
153
+ 続けて、表情レイヤーと入力待ちアイコンを設定します。
154
+
155
+ ```text
156
+ set portrait base [HeroFace] for bubble style [hero-dialogue]
157
+
158
+ set blink frames [HeroEyesOpen,HeroEyesClosed]
159
+ every [0.4] seconds for bubble style [hero-dialogue]
160
+
161
+ set talk frames [HeroMouthClosed,HeroMouthOpen]
162
+ every [0.1] seconds for bubble style [hero-dialogue]
163
+
164
+ set advance frames [Next1,Next2]
165
+ every [0.2] seconds for bubble style [hero-dialogue]
166
+ ```
167
+
168
+ `ASSETS`はカンマ区切りのAsset Managerアセット名です。名前の前後の空白は除去されます。アセット名自体にカンマは使用できません。
169
+
170
+ - 目パチと口パクは1枚以上指定できます。1枚だけなら表示は固定されます。
171
+ - 「次へ」はループが分かるよう2枚以上必要です。
172
+ - `SECONDS`は0より大きい秒数です。
173
+ - `ASSETS`を空にすると、そのアニメーション設定を解除します。
174
+ - 表情ベースを空にするとportrait全体を解除します。
175
+
176
+ ## 5. セリフを表示して入力を待つ
177
+
178
+ `say`または`think`はBubbleを表示するとすぐ次のブロックへ進み、初期animation modeは`talking`になります。
179
+
180
+ ```text
181
+ set runtime variable [input] to []
182
+ listen for key [Space] set runtime var [input] to [pressed]
183
+ listen for touch on this sprite set runtime var [input] to [pressed]
184
+ say [海へ出発!] with bubble style [hero-dialogue]
185
+ wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
186
+ close this bubble
187
+ ```
188
+
189
+ まずTemporary Variablesで`input`を初期化してから、Async Inputのキー入力とタップのlistenerを登録します。Bubbleの待機ブロックは、`input == "pressed"`をRuntime Expressionへ委譲し、開始直後とVMの各フレームで評価します。待機中は自動的に`awaiting-advance`となり、口パクを停止して`set advance frames`の画像をループします。条件成立またはtimeout後は`idle`へ移り、次の`close this bubble`へ進みます。timeoutを`0`にすると時間制限なしです。
190
+
191
+ 次の待機に入る前に`input`を空文字へ戻してください。前回の`pressed`が残っていると、次の条件が直ちに成立します。別のBubble表示、close、対象targetの停止、projectの開始・停止、runtime破棄では、targetが所有する待機とlistener、timerをキャンセルして解放します。
192
+
193
+ 音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点で`awaiting-advance`へ切り替えます。
194
+
195
+ ![sayで口パクし、awaiting-advanceでadvance framesを動かし、入力成立後にBubbleを閉じるアニメーション](./assets/bubble-lifecycle.gif)
196
+
197
+ アニメーションGIFを再生できない環境では、次の比較図で各animation modeを確認できます。
198
+
199
+ ![talking、awaiting-advance、idleの目パチ、口パク、advance framesの状態比較](./assets/animation-mode-guide.svg)
200
+
201
+ ## 6. Animation modeの使い分け
202
+
203
+ | mode | 目パチ | 口パク | advance frames | 主な用途 |
204
+ | ------------------ | ------ | ------------ | -------------- | ---------------------------- |
205
+ | `talking` | 実行 | 実行 | 非表示 | セリフ表示中、音声再生中 |
206
+ | `awaiting-advance` | 実行 | 停止・非表示 | ループ | ユーザによる「次へ」操作待ち |
207
+ | `idle` | 実行 | 停止・非表示 | 停止・非表示 | Bubbleを表示したまま静止 |
208
+
209
+ `set this bubble animation mode [MODE]`は、呼び出したsprite、clone、またはStageが所有するBubbleだけを変更します。先に`say`または`think`を実行していない場合はエラーになります。
210
+
211
+ ## 7. sayとthink
212
+
213
+ ```text
214
+ say [MESSAGE] with bubble style [STYLE]
215
+ think [MESSAGE] with bubble style [STYLE]
216
+ ```
217
+
218
+ どちらも同じvisual style、表情レイヤー、placement、animation mode制御を使えます。`say`/`think`だけで形状を固定せず、`set bubble visual style`で`NORMAL`、`THINKING`などを明示的に選びます。Composition APIのsurfaceには`say`/`think`のkindも渡されるため、独自hostではkindに応じた追加表現も可能です。
219
+
220
+ 同じsprite、clone、またはStageで新しい`say`/`think`を実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。
221
+
222
+ ## 8. cloneで使う
223
+
224
+ Bubble styleの定義は拡張機能内で共有されますが、表示中のBubbleはsprite/cloneごとに所有されます。
225
+
226
+ 1. 元spriteで、緑の旗が押されたときにアセットとstyleを1回定義します。
227
+ 2. 各clone自身から`say`または`think`を実行します。
228
+ 3. animation mode変更とcloseも、表示したのと同じcloneから実行します。
229
+
230
+ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG Text skin、drawableが自動解放されます。
231
+
232
+ ## 9. ブロック一覧
233
+
234
+ | ブロック | 説明 |
235
+ | -------------------------------------------------------------------------------------- | ------------------------------------------------------ |
236
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
237
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
238
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
239
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
240
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
241
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含む全体のscaleを設定する |
242
+ | `set portrait base [ASSET] for bubble style [STYLE]` | portraitのベース画像を設定する |
243
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分と間隔を設定する |
244
+ | `set talk frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分と間隔を設定する |
245
+ | `set advance frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-advance`中の「次へ」アニメーションを設定する |
246
+ | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始・置換する |
247
+ | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始・置換する |
248
+ | `set this bubble animation mode [MODE]` | `talking`、`awaiting-advance`、`idle`からmodeを選ぶ |
249
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
250
+ | `close this bubble` | 自分のBubbleと所有resourceを解放する |
251
+ | `Bubble version` | Bubble実装versionを返す |
252
+
253
+ ## 10. よくあるエラー
254
+
255
+ | 状況 | 原因と対処 |
256
+ | ---------------------------------- | ------------------------------------------------------------------------ |
257
+ | Asset Managerを要求するエラー | Asset Manager 0.7.xをサンドボックスなしで読み込む |
258
+ | SVG Textを要求するエラー | SVG Text 0.3.xをサンドボックスなしで読み込む |
259
+ | Async Inputを要求するエラー | Bubble待機より前にAsync Input 0.3.xをサンドボックスなしで読み込む |
260
+ | Runtime Expressionを要求するエラー | Bubble待機より前にRuntime Expression 0.3.xをサンドボックスなしで読み込む |
261
+ | `bubble style is not defined` | `define bubble style`を先に実行する。緑の旗の再実行時も再定義する |
262
+ | image assetが未登録 | `register resource ... as asset ...`の完了後にBubbleを表示する |
263
+ | assetが画像ではない | `MIME type of asset [NAME]`で`image/*`か確認する |
264
+ | advance framesが1枚 | 2枚以上にするか、空にしてadvance表示を解除する |
265
+ | frame intervalエラー | `SECONDS`を0より大きい有限値にする |
266
+ | StageからActor相対表示した | placementを`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`にする |
267
+ | placementが不正 | 16方向、alias、0〜360度、背景相対3値のいずれかを指定する |
268
+ | 目や口がずれる | ベースと全差分のcanvasサイズ、中心、透明領域を揃える |
269
+
270
+ ## 11. 自動解放されるタイミング
271
+
272
+ 次の場合、Bubbleが所有するtimer、SVG Text skin、renderer drawableは自動的に解放されます。
273
+
274
+ - `close this bubble`
275
+ - 同じsprite/cloneで次の`say`または`think`を実行したとき
276
+ - 対象sprite/cloneが停止したとき
277
+ - 緑の旗によるproject開始
278
+ - projectの全停止
279
+ - TurboWarp runtimeの破棄
280
+
281
+ Asset Managerへ登録したアセット自体はBubbleの所有物ではありません。不要になった登録画像をメモリから削除する場合は、Bubbleを閉じた後にAsset Managerの`delete asset [NAME] from memory`を使います。
282
+
283
+ ## 12. マニュアル画像の再生成
284
+
285
+ 図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickの`magick`コマンドが必要です。
286
+
287
+ ```sh
288
+ pnpm docs:render
289
+ pnpm docs:check
290
+ ```
291
+
292
+ `docs:check`は、SVGのviewBox、production renderer/wrapText由来marker、全visual style、GIFの寸法・16フレーム・ループ設定、マニュアルから画像と全16ブロックへの参照、およびPages用HTMLが最新であることを検証します。
@@ -0,0 +1,292 @@
1
+ # TurboWarp Bubble Block Manual
2
+
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 advance indicator.
4
+
5
+ ![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
+
7
+ ## 1. Load the required extensions
8
+
9
+ The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the five custom extensions with **Run without sandbox** enabled. Async Input and Runtime Expression must be available before a Bubble wait; Asset Manager and SVG Text must be available before the first Bubble is shown.
10
+
11
+ | Order | Extension | URL |
12
+ | ----: | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
13
+ | 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.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.3.0/dist/svg-text.js` |
18
+ | 6 | Bubble 0.1.0 | After npm publication: `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.1.0/dist/turbowarp-bubble.js` |
19
+
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 Asset Manager or SVG Text is missing when it displays a Bubble, or if Async Input or Runtime Expression is missing when it starts a Bubble wait.
21
+
22
+ See also:
23
+
24
+ - [Asset Manager guide](https://kubohiroya.github.io/turbowarp-asset-manager/)
25
+ - [Async Input guide](https://kubohiroya.github.io/turbowarp-async-input/)
26
+ - [Runtime Expression guide](https://kubohiroya.github.io/turbowarp-runtime-expression/)
27
+ - [SVG Text guide](https://kubohiroya.github.io/turbowarp-svg-text/)
28
+
29
+ ## 2. Prepare portrait assets
30
+
31
+ The following example stores costumes in a hidden asset sprite named `Assets`.
32
+
33
+ | Costume | Asset Manager name | Contents |
34
+ | ----------------- | ------------------ | ---------------------------------------------------------- |
35
+ | `HeroFace` | `HeroFace` | Face, hair, and outline, excluding the animated eyes/mouth |
36
+ | `HeroEyesOpen` | `HeroEyesOpen` | Transparent overlay containing only the open eyes |
37
+ | `HeroEyesClosed` | `HeroEyesClosed` | Transparent overlay containing only the closed eyes |
38
+ | `HeroMouthClosed` | `HeroMouthClosed` | Transparent overlay containing only the closed mouth |
39
+ | `HeroMouthOpen` | `HeroMouthOpen` | Transparent overlay containing only the open mouth |
40
+ | `Next1` | `Next1` | First frame of the advance indicator |
41
+ | `Next2` | `Next2` | Second frame of the advance indicator |
42
+
43
+ Use the same canvas size and center point for the base, eye, and mouth images. Keep overlay backgrounds transparent; mismatched canvases or centers make the layers drift when composed.
44
+
45
+ Register each costume with Asset Manager:
46
+
47
+ ```text
48
+ register resource [costume:Assets:HeroFace] as asset [HeroFace]
49
+ register resource [costume:Assets:HeroEyesOpen] as asset [HeroEyesOpen]
50
+ register resource [costume:Assets:HeroEyesClosed] as asset [HeroEyesClosed]
51
+ register resource [costume:Assets:HeroMouthClosed] as asset [HeroMouthClosed]
52
+ register resource [costume:Assets:HeroMouthOpen] as asset [HeroMouthOpen]
53
+ register resource [costume:Assets:Next1] as asset [Next1]
54
+ register resource [costume:Assets:Next2] as asset [Next2]
55
+ ```
56
+
57
+ 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
+ ## 3. Define a text style
60
+
61
+ Use SVG Text to define the named style for the Bubble's text layer.
62
+
63
+ ```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]
71
+ ```
72
+
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.3.x retains a `bubble direction` input in its block contract, but Bubble does not use it when creating the text drawable through `setText`. Use `set bubble placement` in the next section instead. The obsolete SVG Text direction input is intended to be removed in a later breaking release.
76
+
77
+ ## 4. Define a Bubble style
78
+
79
+ First associate a Bubble style name with an SVG Text style name.
80
+
81
+ ```text
82
+ define bubble style [hero-dialogue] using text style [dialogue-text]
83
+ set bubble placement [up-right] for bubble style [hero-dialogue]
84
+ set bubble distance [12] for bubble style [hero-dialogue]
85
+ set bubble visual style [NORMAL] for bubble style [hero-dialogue]
86
+ set bubble tail length [18] for bubble style [hero-dialogue]
87
+ set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
88
+ ```
89
+
90
+ ### Actor-relative and stage-relative placement
91
+
92
+ ![Actor-relative 16-way and angle placement compared with three stage-relative placements](./assets/placement-guide.svg)
93
+
94
+ Each of the 16 actor-relative directions is shown as a complete mini-scene containing an actor, Bubble body, tail, and text. The two tail-base points lie on the body border. The renderer uses a JSClipper union to produce a single path, so no internal border remains at the join.
95
+
96
+ 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
+
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:
99
+
100
+ ```text
101
+ up / up-up-right / up-right / right-up-right
102
+ right / right-down-right / down-right / down-down-right
103
+ down / down-down-left / down-left / left-down-left
104
+ left / left-up-left / up-left / up-up-left
105
+ ```
106
+
107
+ Compass aliases such as `north`, `north-northeast`, and `northeast` may also be typed directly or supplied by a reporter. A number uses Scratch direction semantics from 0 through 360 degrees: `0` is up, `90` right, `180` down, `270` left, and `360` normalizes to `0`. Arbitrary angles are not rounded to the 16 menu directions. The default is `up-right`.
108
+
109
+ Stage-relative placements do not point at an actor and are positioned within the Stage safe area.
110
+
111
+ | Placement | Position |
112
+ | ------------- | ------------------------------------------- |
113
+ | `HEADER_LIKE` | Top of the Stage safe area, centered |
114
+ | `CENTER` | Horizontal and vertical center of the Stage |
115
+ | `FOOTER_LIKE` | Bottom of the Stage safe area, centered |
116
+
117
+ These placements do not depend on actor coordinates, bounds, or visibility. Use one of them when running `say` or `think` from the Stage. A stage-relative Bubble has no actor-pointing tail.
118
+
119
+ ### Actor distance, tail, body offset, and scale
120
+
121
+ ![Real Bubble SVGs comparing distance, tail length, offset, and scale](./assets/actor-transform-guide.svg)
122
+
123
+ - `distance` (default `12`) is the gap between the actor bounds and the tail tip. Actor bounds means the axis-aligned bounding box (AABB) of the rendered actor in Stage coordinates.
124
+ - `tail length` (default `18`) is the nominal distance from the Bubble border to the tail tip at the normal position.
125
+ - `offset x/y/scale` (default `[0, 0, 100]`) uses positive x to the right, positive y upward, and scale as a percentage. `[10, -10, 120]` moves the body 10 right and 10 down, then scales it to 120%.
126
+
127
+ Scale applies to the body, SVG Text, portrait base, blink/lip-sync layers, advance indicator, and internal padding as one unit, so the displayed font size scales by the same factor. When scale alone changes, the body center moves away from the actor by the increase in radius, preserving the actor-side gap. The x/y offset is added afterward. The tail tip remains fixed and the union with the body border is regenerated, so an offset can change the effective tail length.
128
+
129
+ Near a Stage edge, keeping the scaled Bubble on-screen takes priority and can reduce the requested distance. Actor-relative distance, tail, offset, and scale settings do not apply to `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE`.
130
+
131
+ ### Width, automatic wrapping, and Japanese line-breaking rules
132
+
133
+ ![Automatic wrapping at different maxWidth values and Japanese line-breaking examples](./assets/width-linebreak-guide.svg)
134
+
135
+ The diagram is generated by running the production `wrapText` implementation. `@cto.af/linebreak` supplies Unicode UAX #14 break opportunities, which are filtered against `Intl.Segmenter` grapheme boundaries. The renderer then chooses the last candidate that fits the measured width. It avoids unnatural breaks before punctuation, closing brackets, small kana and prolonged sound marks, and inside a combined emoji grapheme.
136
+
137
+ ### Bubble visual styles
138
+
139
+ ![Ten Bubble visual styles rendered by the production SVG renderer](./assets/bubble-style-gallery.svg)
140
+
141
+ Available shapes are `NORMAL`, `THINKING`, `DREAMING`, `YELLING`, `OFF_PANEL`, `WAVY`, `WHISPERING`, `ANNOUNCEMENT`, `NARRATION`, and `NO_BUBBLE`.
142
+
143
+ ```text
144
+ set bubble visual style [YELLING] for bubble style [hero-dialogue]
145
+ ```
146
+
147
+ The diagram and TurboWarp drawable both use Bubble's shared `renderBubbleSvg` function. Shapes with triangular tails use a [platener/jsclipper](https://github.com/platener/jsclipper) union between the body and tail. `THINKING` and `DREAMING` use circular trails and are excluded from that union. Actor-relative placement points the tail toward the actor; stage-relative placement has no tail. `NO_BUBBLE` hides the body drawable and displays only text, portrait, and other layers.
148
+
149
+ The default visual style is `NORMAL`. The body drawable is created before text and portrait drawables so it remains behind them. `close this bubble`, target/clone disposal, and runtime disposal release the body drawable and its owned SVG skin.
150
+
151
+ `NEGATIVE` is not a separate style because it can be expressed with fill and border colors. Orientation and segments are also not public inputs; dimensions are calculated from width, font, character count, and the number of lines after wrapping.
152
+
153
+ Now configure the portrait and advance animation layers:
154
+
155
+ ```text
156
+ set portrait base [HeroFace] for bubble style [hero-dialogue]
157
+
158
+ set blink frames [HeroEyesOpen,HeroEyesClosed]
159
+ every [0.4] seconds for bubble style [hero-dialogue]
160
+
161
+ set talk frames [HeroMouthClosed,HeroMouthOpen]
162
+ every [0.1] seconds for bubble style [hero-dialogue]
163
+
164
+ set advance frames [Next1,Next2]
165
+ every [0.2] seconds for bubble style [hero-dialogue]
166
+ ```
167
+
168
+ `ASSETS` is a comma-separated list of Asset Manager names. Surrounding whitespace is removed; commas cannot be part of an asset name.
169
+
170
+ - Blink and talk animations accept one or more frames. A single frame remains static.
171
+ - Use two or more advance frames so the loop is visible.
172
+ - `SECONDS` must be a finite number greater than zero.
173
+ - An empty `ASSETS` input removes that animation.
174
+ - An empty portrait base removes the whole portrait.
175
+
176
+ ## 5. Show dialogue and wait for input
177
+
178
+ `say` and `think` show a Bubble immediately, continue to the next block, and begin in `talking` animation mode.
179
+
180
+ ```text
181
+ set runtime variable [input] to []
182
+ listen for key [Space] set runtime var [input] to [pressed]
183
+ listen for touch on this sprite set runtime var [input] to [pressed]
184
+ say [Let's head for the sea!] with bubble style [hero-dialogue]
185
+ wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
186
+ close this bubble
187
+ ```
188
+
189
+ Initialize `input` with Temporary Variables before registering the Async Input listeners. The listeners update that runtime variable when Space is pressed or the sprite is tapped. The Bubble wait delegates `input == "pressed"` to Runtime Expression immediately and once per VM frame. While waiting it automatically enters `awaiting-advance`, stops lip-sync, and loops the images configured by `set advance frames`. When the condition becomes true or the timeout expires, it enters `idle` and continues to `close this bubble`. Set the timeout to `0` to wait without a timeout.
190
+
191
+ Reset `input` to an empty string before each later wait; otherwise the previous `pressed` value makes the next condition succeed immediately. Starting another Bubble, closing it, stopping its target, restarting or stopping the project, and disposing the runtime all cancel the target-owned wait and release its listener and timer.
192
+
193
+ When combining Bubble with audio or a separate text-reveal system, switch to `awaiting-advance` when that process completes.
194
+
195
+ ![A say Bubble lip-syncs, shows advance frames while awaiting advance, then closes after input](./assets/bubble-lifecycle.gif)
196
+
197
+ If animated GIF playback is unavailable, use this static animation-mode comparison:
198
+
199
+ ![Blink, lip-sync, and advance-frame states in talking, awaiting-advance, and idle modes](./assets/animation-mode-guide.svg)
200
+
201
+ ## 6. Bubble animation modes
202
+
203
+ | Mode | Blink | Lip-sync | Advance frames | Typical use |
204
+ | ------------------ | ----- | ------------ | -------------- | ----------------------------------- |
205
+ | `talking` | Runs | Runs | Hidden | Dialogue display or audio playback |
206
+ | `awaiting-advance` | Runs | Stops/hidden | Loops | Await the user's request to advance |
207
+ | `idle` | Runs | Stops/hidden | Stops/hidden | Keep a Bubble visible and still |
208
+
209
+ `set this bubble animation mode [MODE]` changes only the Bubble owned by the calling sprite, clone, or Stage. It reports an error if that target has not first run `say` or `think`.
210
+
211
+ ## 7. `say` and `think`
212
+
213
+ ```text
214
+ say [MESSAGE] with bubble style [STYLE]
215
+ think [MESSAGE] with bubble style [STYLE]
216
+ ```
217
+
218
+ 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.
219
+
220
+ 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.
221
+
222
+ ## 8. Using Bubble with clones
223
+
224
+ Bubble style definitions are shared within the extension, but each sprite or clone owns its currently displayed Bubble.
225
+
226
+ 1. Define assets and styles once from the original sprite when the green flag is clicked.
227
+ 2. Run `say` or `think` from each clone itself.
228
+ 3. Change the animation mode and close the Bubble from the same clone that displayed it.
229
+
230
+ When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables owned by that target are released automatically.
231
+
232
+ ## 9. Block reference
233
+
234
+ | Block | Description |
235
+ | -------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
236
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
237
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
238
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
239
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten SVG body shapes |
240
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Set the nominal border-to-tip tail length |
241
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Set body position and whole-Bubble scale, including text |
242
+ | `set portrait base [ASSET] for bubble style [STYLE]` | Set the portrait base image |
243
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set blink overlays and interval |
244
+ | `set talk frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set lip-sync overlays and interval |
245
+ | `set advance frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set the animation shown during `awaiting-advance` |
246
+ | `say [MESSAGE] with bubble style [STYLE]` | Start or replace a `say` Bubble in `talking` mode |
247
+ | `think [MESSAGE] with bubble style [STYLE]` | Start or replace a `think` Bubble in `talking` mode |
248
+ | `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-advance`, or `idle` for this Bubble |
249
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
250
+ | `close this bubble` | Release this target's Bubble and owned resources |
251
+ | `Bubble version` | Report the Bubble implementation version |
252
+
253
+ ## 10. Troubleshooting
254
+
255
+ | Symptom | Cause and solution |
256
+ | ------------------------------------ | --------------------------------------------------------------------------- |
257
+ | Asset Manager required error | Load Asset Manager 0.7.x without sandbox |
258
+ | SVG Text required error | Load SVG Text 0.3.x without sandbox |
259
+ | Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
260
+ | Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
261
+ | `bubble style is not defined` | Run `define bubble style` first, including after restarting with green flag |
262
+ | Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
263
+ | Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
264
+ | Only one advance frame | Supply at least two frames, or clear the setting |
265
+ | Frame interval error | Use a finite `SECONDS` value greater than zero |
266
+ | Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
267
+ | Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
268
+ | Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
269
+
270
+ ## 11. Automatic cleanup
271
+
272
+ Bubble automatically releases its owned timers, SVG Text skins, and renderer drawables when:
273
+
274
+ - `close this bubble` runs;
275
+ - the same sprite or clone runs another `say` or `think`;
276
+ - the target sprite or clone stops;
277
+ - the green flag starts the project;
278
+ - the whole project stops; or
279
+ - the TurboWarp runtime is disposed.
280
+
281
+ Assets registered with Asset Manager are not owned by Bubble. To remove an unused registered image from memory, close the Bubble first and then use Asset Manager's `delete asset [NAME] from memory` block.
282
+
283
+ ## 12. Regenerating the manual assets
284
+
285
+ The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick `magick` command.
286
+
287
+ ```sh
288
+ pnpm docs:render
289
+ pnpm docs:check
290
+ ```
291
+
292
+ `docs:check` verifies SVG viewBoxes, production-renderer and `wrapText` markers, every visual style, the GIF dimensions/frame count/loop setting, references to all images and 16 blocks in both language manuals, and that the generated GitHub Pages HTML is current.