@kubohiroya/turbowarp-bubble 0.1.1 → 0.3.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.
- package/README.md +355 -79
- package/dist/composition.js +972 -597
- package/dist/extension-manifest.json +240 -16
- package/dist/turbowarp-adapter.js +1728 -626
- package/dist/turbowarp-bubble.js +2811 -233
- package/dist/types/bubble-svg.d.ts +10 -0
- package/dist/types/composition.d.ts +96 -18
- package/dist/types/reveal.d.ts +26 -0
- package/dist/types/turbowarp-adapter.d.ts +12 -2
- package/docs/assets/animation-mode-guide.svg +5 -14
- package/docs/assets/block-quick-start.svg +8 -8
- package/docs/assets/bubble-lifecycle.gif +0 -0
- package/docs/block-manual.ja.md +88 -47
- package/docs/block-manual.md +95 -54
- package/docs/index.html +103 -39
- package/docs/ja/index.html +95 -31
- package/package.json +20 -7
package/docs/block-manual.ja.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
## 1. 必要な拡張機能
|
|
8
8
|
|
|
9
|
-
入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variables
|
|
9
|
+
入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。文字BubbleにはSVG TextとBubbleが必要です。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
|
|
10
10
|
|
|
11
11
|
| 順番 | 拡張機能 | 読み込み先 |
|
|
12
12
|
| ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
|
|
@@ -14,10 +14,10 @@
|
|
|
14
14
|
| 2 | Async Input 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js` |
|
|
15
15
|
| 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
|
|
16
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.
|
|
18
|
-
| 6 | Bubble 0.
|
|
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.3.0 | npm公開後は`https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.3.0/dist/turbowarp-bubble.js` |
|
|
19
19
|
|
|
20
|
-
開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。表示時にAsset Manager
|
|
20
|
+
開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。表示時にSVG Textが、画像・メディア機能の使用時にAsset Managerが、待機開始時にAsync InputかRuntime Expressionが見つからなければ、Bubbleは明示的なエラーを返します。
|
|
21
21
|
|
|
22
22
|
参考:
|
|
23
23
|
|
|
@@ -72,7 +72,7 @@ define text style [dialogue-text]
|
|
|
72
72
|
|
|
73
73
|
Bubbleは`dialogue-text`という名前を参照します。文字styleとBubble styleはruntime状態なので、通常は緑の旗が押されたときに毎回定義します。
|
|
74
74
|
|
|
75
|
-
SVG Text 0.
|
|
75
|
+
SVG Text 0.4.xは文字providerです。名前付き文字styleの定義、SVG文字skinの生成、文字幅の測定を担当します。Bubbleの配置は`set bubble placement`で設定し、tailや吹き出し外形はSVG Text providerの責務ではありません。
|
|
76
76
|
|
|
77
77
|
## 4. Bubble styleを定義する
|
|
78
78
|
|
|
@@ -158,10 +158,10 @@ set portrait base [HeroFace] for bubble style [hero-dialogue]
|
|
|
158
158
|
set blink frames [HeroEyesOpen,HeroEyesClosed]
|
|
159
159
|
every [0.4] seconds for bubble style [hero-dialogue]
|
|
160
160
|
|
|
161
|
-
set
|
|
161
|
+
set lip-sync frames [HeroMouthClosed,HeroMouthOpen]
|
|
162
162
|
every [0.1] seconds for bubble style [hero-dialogue]
|
|
163
163
|
|
|
164
|
-
set
|
|
164
|
+
set continue frames [Next1,Next2]
|
|
165
165
|
every [0.2] seconds for bubble style [hero-dialogue]
|
|
166
166
|
```
|
|
167
167
|
|
|
@@ -173,7 +173,22 @@ set advance frames [Next1,Next2]
|
|
|
173
173
|
- `ASSETS`を空にすると、そのアニメーション設定を解除します。
|
|
174
174
|
- 表情ベースを空にするとportrait全体を解除します。
|
|
175
175
|
|
|
176
|
-
## 5.
|
|
176
|
+
## 5. 逐次表示、音声、表示サイズ
|
|
177
|
+
|
|
178
|
+
Bubbleはセリフ全体を一度に描画するだけでなく、`CHARACTER`、`WORD`、`LINE`、`BLOCK`の単位で順次表示できます。`WORD`は形態素解析を行わず、空白または指定した区切り文字集合で分割します。区切り文字を表示するかどうかも選べます。
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
|
|
182
|
+
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
183
|
+
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
184
|
+
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
185
|
+
say [海へ出発!] with bubble style [hero-dialogue]
|
|
186
|
+
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`DYNAMIC`は表示単位ごとに吹き出しの大きさと配置を再計算し、`RESERVED`は最終的な文字量を先に計測して表示中の外形を予約します。`set bubble reveal sound`は単位ごと、`set bubble voice`は表示開始時にAsset Managerの名前付き音声を再生します。音声がなくても文字表示は利用できます。
|
|
190
|
+
|
|
191
|
+
## 6. セリフを表示して入力を待つ
|
|
177
192
|
|
|
178
193
|
`say`または`think`はBubbleを表示するとすぐ次のブロックへ進み、初期animation modeは`talking`になります。
|
|
179
194
|
|
|
@@ -186,29 +201,44 @@ wait with this bubble until condition [input == "pressed"] or timeout after [10]
|
|
|
186
201
|
close this bubble
|
|
187
202
|
```
|
|
188
203
|
|
|
189
|
-
まずTemporary Variablesで`input`を初期化してから、Async Inputのキー入力とタップのlistenerを登録します。Bubbleの待機ブロックは、`input == "pressed"`をRuntime Expressionへ委譲し、開始直後とVMの各フレームで評価します。待機中は自動的に`awaiting-
|
|
204
|
+
まずTemporary Variablesで`input`を初期化してから、Async Inputのキー入力とタップのlistenerを登録します。Bubbleの待機ブロックは、`input == "pressed"`をRuntime Expressionへ委譲し、開始直後とVMの各フレームで評価します。待機中は自動的に`awaiting-continue`となり、口パクを停止して`set continue frames`の画像をループします。条件成立またはtimeout後は`idle`へ移り、次の`close this bubble`へ進みます。timeoutを`0`にすると時間制限なしです。
|
|
190
205
|
|
|
191
206
|
次の待機に入る前に`input`を空文字へ戻してください。前回の`pressed`が残っていると、次の条件が直ちに成立します。別のBubble表示、close、対象targetの停止、projectの開始・停止、runtime破棄では、targetが所有する待機とlistener、timerをキャンセルして解放します。
|
|
192
207
|
|
|
193
|
-
音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点で`awaiting-
|
|
208
|
+
音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点で`awaiting-continue`へ切り替えます。
|
|
194
209
|
|
|
195
|
-

|
|
196
211
|
|
|
197
212
|
アニメーションGIFを再生できない環境では、次の比較図で各animation modeを確認できます。
|
|
198
213
|
|
|
199
|
-

|
|
200
215
|
|
|
201
|
-
##
|
|
216
|
+
## 7. Animation modeの使い分け
|
|
202
217
|
|
|
203
|
-
| mode
|
|
204
|
-
|
|
|
205
|
-
| `talking`
|
|
206
|
-
| `awaiting-
|
|
207
|
-
| `idle`
|
|
218
|
+
| mode | 目パチ | 口パク | continue frames | 主な用途 |
|
|
219
|
+
| ------------------- | ------ | ------------ | --------------- | ---------------------------- |
|
|
220
|
+
| `talking` | 実行 | 実行 | 非表示 | セリフ表示中、音声再生中 |
|
|
221
|
+
| `awaiting-continue` | 実行 | 停止・非表示 | ループ | ユーザによる「次へ」操作待ち |
|
|
222
|
+
| `idle` | 実行 | 停止・非表示 | 停止・非表示 | Bubbleを表示したまま静止 |
|
|
208
223
|
|
|
209
224
|
`set this bubble animation mode [MODE]`は、呼び出したsprite、clone、またはStageが所有するBubbleだけを変更します。先に`say`または`think`を実行していない場合はエラーになります。
|
|
210
225
|
|
|
211
|
-
##
|
|
226
|
+
## 8. 表示開始・表示中・表示終了animation
|
|
227
|
+
|
|
228
|
+
表示開始は`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了は`fadeOut`、`floatOut`、`zoomOut`、`sink`から選べます。これらは`DYNAMIC`と`RESERVED`のどちらにも適用できます。
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
|
|
232
|
+
set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
|
|
233
|
+
animate this bubble [shake]
|
|
234
|
+
shake this bubble direction [90] count [2] ease [easeInOut]
|
|
235
|
+
explode this bubble relative scale [1.15] count [2] ease [easeOut]
|
|
236
|
+
animate bubble shape to [WAVY] speed [1] for [0.5] seconds
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
TurboWarp adapterはこれらをschedulerのフレームごとに進め、各フレームの進行率へ`ease`を適用します。`shake`は吹き出し全体を方向・回数付きで揺らし、`explode`はportraitと文字を含むsurface全体を拡大して元へ戻し、`animate bubble shape`は指定時間中に現在の外形から`THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などへcross-fadeします。仕様では、吹き出しが表示される時点を「表示開始」、隠れる時点を「表示終了」と呼びます。
|
|
240
|
+
|
|
241
|
+
## 9. sayとthink
|
|
212
242
|
|
|
213
243
|
```text
|
|
214
244
|
say [MESSAGE] with bubble style [STYLE]
|
|
@@ -219,7 +249,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
219
249
|
|
|
220
250
|
同じsprite、clone、またはStageで新しい`say`/`think`を実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。
|
|
221
251
|
|
|
222
|
-
##
|
|
252
|
+
## 10. cloneで使う
|
|
223
253
|
|
|
224
254
|
Bubble styleの定義は拡張機能内で共有されますが、表示中のBubbleはsprite/cloneごとに所有されます。
|
|
225
255
|
|
|
@@ -229,45 +259,56 @@ Bubble styleの定義は拡張機能内で共有されますが、表示中のBu
|
|
|
229
259
|
|
|
230
260
|
cloneが停止・削除された場合は、そのtargetに属するtimer、SVG Text skin、drawableが自動解放されます。
|
|
231
261
|
|
|
232
|
-
##
|
|
233
|
-
|
|
234
|
-
| ブロック
|
|
235
|
-
|
|
|
236
|
-
| `define bubble style [STYLE] using text style [TEXT_STYLE]`
|
|
237
|
-
| `set bubble placement [PLACEMENT] for bubble style [STYLE]`
|
|
238
|
-
| `set bubble distance [DISTANCE] for bubble style [STYLE]`
|
|
239
|
-
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]`
|
|
240
|
-
| `set bubble tail length [LENGTH] for bubble style [STYLE]`
|
|
241
|
-
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]`
|
|
242
|
-
| `set portrait base [ASSET] for bubble style [STYLE]`
|
|
243
|
-
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]`
|
|
244
|
-
| `set
|
|
245
|
-
| `set
|
|
246
|
-
| `
|
|
247
|
-
| `
|
|
248
|
-
| `set
|
|
249
|
-
| `
|
|
250
|
-
| `
|
|
251
|
-
| `
|
|
252
|
-
|
|
253
|
-
|
|
262
|
+
## 11. ブロック一覧
|
|
263
|
+
|
|
264
|
+
| ブロック | 説明 |
|
|
265
|
+
| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
|
|
266
|
+
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
|
|
267
|
+
| `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
|
|
268
|
+
| `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
|
|
269
|
+
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
|
|
270
|
+
| `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
|
|
271
|
+
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含む全体のscaleを設定する |
|
|
272
|
+
| `set portrait base [ASSET] for bubble style [STYLE]` | portraitのベース画像を設定する |
|
|
273
|
+
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分と間隔を設定する |
|
|
274
|
+
| `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分と間隔を設定する |
|
|
275
|
+
| `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-continue`中の「次へ」アニメーションを設定する |
|
|
276
|
+
| `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | CHARACTER/WORD/LINE/BLOCKの逐次表示を設定する |
|
|
277
|
+
| `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | WORDの区切り文字集合と表示可否を設定する |
|
|
278
|
+
| `set bubble reveal sound [ASSET] for bubble style [STYLE]` | 表示単位ごとの効果音を設定する |
|
|
279
|
+
| `set bubble voice [ASSET] for bubble style [STYLE]` | 表示開始時のフルボイスを設定する |
|
|
280
|
+
| `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | 未表示単位を最後まで進め、条件またはtimeoutを待つ |
|
|
281
|
+
| `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示開始animationを設定する |
|
|
282
|
+
| `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示終了animationを設定する |
|
|
283
|
+
| `animate this bubble [MOTION]` | Bubble全体のanimationを再生する |
|
|
284
|
+
| `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | 吹き出し全体を指定方向へ揺らす |
|
|
285
|
+
| `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | 吹き出し全体を相対倍率で変化させる |
|
|
286
|
+
| `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Bubble外形を時間経過で切り替える |
|
|
287
|
+
| `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始・置換する |
|
|
288
|
+
| `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始・置換する |
|
|
289
|
+
| `set this bubble animation mode [MODE]` | `talking`、`awaiting-continue`、`idle`からmodeを選ぶ |
|
|
290
|
+
| `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
|
|
291
|
+
| `close this bubble` | 自分のBubbleと所有resourceを解放する |
|
|
292
|
+
| `Bubble version` | Bubble実装versionを返す |
|
|
293
|
+
|
|
294
|
+
## 12. よくあるエラー
|
|
254
295
|
|
|
255
296
|
| 状況 | 原因と対処 |
|
|
256
297
|
| ---------------------------------- | ------------------------------------------------------------------------ |
|
|
257
|
-
| Asset Managerを要求するエラー | Asset Manager 0.7.x
|
|
258
|
-
| SVG Textを要求するエラー | SVG Text 0.
|
|
298
|
+
| Asset Managerを要求するエラー | 画像・メディアアセットを使う前にAsset Manager 0.7.xを読み込む |
|
|
299
|
+
| SVG Textを要求するエラー | SVG Text 0.4.xをサンドボックスなしで読み込む |
|
|
259
300
|
| Async Inputを要求するエラー | Bubble待機より前にAsync Input 0.3.xをサンドボックスなしで読み込む |
|
|
260
301
|
| Runtime Expressionを要求するエラー | Bubble待機より前にRuntime Expression 0.3.xをサンドボックスなしで読み込む |
|
|
261
302
|
| `bubble style is not defined` | `define bubble style`を先に実行する。緑の旗の再実行時も再定義する |
|
|
262
303
|
| image assetが未登録 | `register resource ... as asset ...`の完了後にBubbleを表示する |
|
|
263
304
|
| assetが画像ではない | `MIME type of asset [NAME]`で`image/*`か確認する |
|
|
264
|
-
|
|
|
305
|
+
| continue framesが1枚 | 2枚以上にするか、空にしてcontinue表示を解除する |
|
|
265
306
|
| frame intervalエラー | `SECONDS`を0より大きい有限値にする |
|
|
266
307
|
| StageからActor相対表示した | placementを`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`にする |
|
|
267
308
|
| placementが不正 | 16方向、alias、0〜360度、背景相対3値のいずれかを指定する |
|
|
268
309
|
| 目や口がずれる | ベースと全差分のcanvasサイズ、中心、透明領域を揃える |
|
|
269
310
|
|
|
270
|
-
##
|
|
311
|
+
## 13. 自動解放されるタイミング
|
|
271
312
|
|
|
272
313
|
次の場合、Bubbleが所有するtimer、SVG Text skin、renderer drawableは自動的に解放されます。
|
|
273
314
|
|
|
@@ -280,7 +321,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG
|
|
|
280
321
|
|
|
281
322
|
Asset Managerへ登録したアセット自体はBubbleの所有物ではありません。不要になった登録画像をメモリから削除する場合は、Bubbleを閉じた後にAsset Managerの`delete asset [NAME] from memory`を使います。
|
|
282
323
|
|
|
283
|
-
##
|
|
324
|
+
## 14. マニュアル画像の再生成
|
|
284
325
|
|
|
285
326
|
図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickの`magick`コマンドが必要です。
|
|
286
327
|
|
package/docs/block-manual.md
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
# TurboWarp Bubble Block Manual
|
|
2
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
|
|
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
5
|

|
|
6
6
|
|
|
7
7
|
## 1. Load the required extensions
|
|
8
8
|
|
|
9
|
-
The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the
|
|
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. SVG Text and Bubble are required 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.
|
|
10
10
|
|
|
11
11
|
| Order | Extension | URL |
|
|
12
12
|
| ----: | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
|
|
@@ -14,10 +14,10 @@ The complete input-wait example uses six extensions. Add Temporary Variables fro
|
|
|
14
14
|
| 2 | Async Input 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js` |
|
|
15
15
|
| 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
|
|
16
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.
|
|
18
|
-
| 6 | Bubble 0.
|
|
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.3.0 | After npm publication: `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.3.0/dist/turbowarp-bubble.js` |
|
|
19
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
|
|
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 SVG Text 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.
|
|
21
21
|
|
|
22
22
|
See also:
|
|
23
23
|
|
|
@@ -37,8 +37,8 @@ The following example stores costumes in a hidden asset sprite named `Assets`.
|
|
|
37
37
|
| `HeroEyesClosed` | `HeroEyesClosed` | Transparent overlay containing only the closed eyes |
|
|
38
38
|
| `HeroMouthClosed` | `HeroMouthClosed` | Transparent overlay containing only the closed mouth |
|
|
39
39
|
| `HeroMouthOpen` | `HeroMouthOpen` | Transparent overlay containing only the open mouth |
|
|
40
|
-
| `Next1` | `Next1` | First frame of the
|
|
41
|
-
| `Next2` | `Next2` | Second frame of the
|
|
40
|
+
| `Next1` | `Next1` | First frame of the continue indicator |
|
|
41
|
+
| `Next2` | `Next2` | Second frame of the continue indicator |
|
|
42
42
|
|
|
43
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
44
|
|
|
@@ -72,7 +72,7 @@ define text style [dialogue-text]
|
|
|
72
72
|
|
|
73
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
74
|
|
|
75
|
-
SVG Text 0.
|
|
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.
|
|
76
76
|
|
|
77
77
|
## 4. Define a Bubble style
|
|
78
78
|
|
|
@@ -124,7 +124,7 @@ These placements do not depend on actor coordinates, bounds, or visibility. Use
|
|
|
124
124
|
- `tail length` (default `18`) is the nominal distance from the Bubble border to the tail tip at the normal position.
|
|
125
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
126
|
|
|
127
|
-
Scale applies to the body, SVG Text, portrait base, blink/lip-sync layers,
|
|
127
|
+
Scale applies to the body, SVG Text, portrait base, blink/lip-sync layers, continue 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
128
|
|
|
129
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
130
|
|
|
@@ -150,7 +150,7 @@ The default visual style is `NORMAL`. The body drawable is created before text a
|
|
|
150
150
|
|
|
151
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
152
|
|
|
153
|
-
Now configure the portrait and
|
|
153
|
+
Now configure the portrait and continue animation layers:
|
|
154
154
|
|
|
155
155
|
```text
|
|
156
156
|
set portrait base [HeroFace] for bubble style [hero-dialogue]
|
|
@@ -158,22 +158,37 @@ set portrait base [HeroFace] for bubble style [hero-dialogue]
|
|
|
158
158
|
set blink frames [HeroEyesOpen,HeroEyesClosed]
|
|
159
159
|
every [0.4] seconds for bubble style [hero-dialogue]
|
|
160
160
|
|
|
161
|
-
set
|
|
161
|
+
set lip-sync frames [HeroMouthClosed,HeroMouthOpen]
|
|
162
162
|
every [0.1] seconds for bubble style [hero-dialogue]
|
|
163
163
|
|
|
164
|
-
set
|
|
164
|
+
set continue frames [Next1,Next2]
|
|
165
165
|
every [0.2] seconds for bubble style [hero-dialogue]
|
|
166
166
|
```
|
|
167
167
|
|
|
168
168
|
`ASSETS` is a comma-separated list of Asset Manager names. Surrounding whitespace is removed; commas cannot be part of an asset name.
|
|
169
169
|
|
|
170
|
-
- Blink and
|
|
171
|
-
- Use two or more
|
|
170
|
+
- Blink and lip-sync animations accept one or more frames. A single frame remains static.
|
|
171
|
+
- Use two or more continue frames so the loop is visible.
|
|
172
172
|
- `SECONDS` must be a finite number greater than zero.
|
|
173
173
|
- An empty `ASSETS` input removes that animation.
|
|
174
174
|
- An empty portrait base removes the whole portrait.
|
|
175
175
|
|
|
176
|
-
## 5.
|
|
176
|
+
## 5. Sequential reveal, audio, and layout
|
|
177
|
+
|
|
178
|
+
Bubble can reveal a message as `CHARACTER`, `WORD`, `LINE`, or `BLOCK` units. `WORD` does not perform morphological analysis; it uses whitespace or the configured delimiter character set. Delimiters can remain visible or be hidden.
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
|
|
182
|
+
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
183
|
+
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
184
|
+
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
185
|
+
say [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
186
|
+
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`DYNAMIC` recalculates the Bubble size and placement after each unit. `RESERVED` measures the final text first and reserves that layout while units appear. `set bubble reveal sound` plays a named Asset Manager audio asset per unit, while `set bubble voice` plays full voice audio when the Bubble starts. Text display remains available without audio.
|
|
190
|
+
|
|
191
|
+
## 6. Show dialogue and wait for input
|
|
177
192
|
|
|
178
193
|
`say` and `think` show a Bubble immediately, continue to the next block, and begin in `talking` animation mode.
|
|
179
194
|
|
|
@@ -186,29 +201,44 @@ wait with this bubble until condition [input == "pressed"] or timeout after [10]
|
|
|
186
201
|
close this bubble
|
|
187
202
|
```
|
|
188
203
|
|
|
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-
|
|
204
|
+
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-continue`, stops lip-sync, and loops the images configured by `set continue 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
205
|
|
|
191
206
|
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
207
|
|
|
193
|
-
When combining Bubble with audio or a separate text-reveal system, switch to `awaiting-
|
|
208
|
+
When combining Bubble with audio or a separate text-reveal system, switch to `awaiting-continue` when that process completes.
|
|
194
209
|
|
|
195
|
-

|
|
196
211
|
|
|
197
212
|
If animated GIF playback is unavailable, use this static animation-mode comparison:
|
|
198
213
|
|
|
199
|
-

|
|
200
215
|
|
|
201
|
-
##
|
|
216
|
+
## 7. Bubble animation modes
|
|
202
217
|
|
|
203
|
-
| Mode
|
|
204
|
-
|
|
|
205
|
-
| `talking`
|
|
206
|
-
| `awaiting-
|
|
207
|
-
| `idle`
|
|
218
|
+
| Mode | Blink | Lip-sync | Continue frames | Typical use |
|
|
219
|
+
| ------------------- | ----- | ------------ | --------------- | ------------------------------------ |
|
|
220
|
+
| `talking` | Runs | Runs | Hidden | Dialogue display or audio playback |
|
|
221
|
+
| `awaiting-continue` | Runs | Stops/hidden | Loops | Await the user's request to continue |
|
|
222
|
+
| `idle` | Runs | Stops/hidden | Stops/hidden | Keep a Bubble visible and still |
|
|
208
223
|
|
|
209
224
|
`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
225
|
|
|
211
|
-
##
|
|
226
|
+
## 8. Show, in-display, and hide animations
|
|
227
|
+
|
|
228
|
+
Use `fadeIn`, `floatIn`, `zoomIn`, or `riseUp` when a Bubble starts displaying, and `fadeOut`, `floatOut`, `zoomOut`, or `sink` when it finishes displaying. These animations work with both `DYNAMIC` and `RESERVED` layout.
|
|
229
|
+
|
|
230
|
+
```text
|
|
231
|
+
set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
|
|
232
|
+
set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
|
|
233
|
+
animate this bubble [shake]
|
|
234
|
+
shake this bubble direction [90] count [2] ease [easeInOut]
|
|
235
|
+
explode this bubble relative scale [1.15] count [2] ease [easeOut]
|
|
236
|
+
animate bubble shape to [WAVY] speed [1] for [0.5] seconds
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
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.
|
|
240
|
+
|
|
241
|
+
## 9. `say` and `think`
|
|
212
242
|
|
|
213
243
|
```text
|
|
214
244
|
say [MESSAGE] with bubble style [STYLE]
|
|
@@ -219,7 +249,7 @@ Both blocks support the same visual styles, portrait layers, placement, and anim
|
|
|
219
249
|
|
|
220
250
|
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
251
|
|
|
222
|
-
##
|
|
252
|
+
## 10. Using Bubble with clones
|
|
223
253
|
|
|
224
254
|
Bubble style definitions are shared within the extension, but each sprite or clone owns its currently displayed Bubble.
|
|
225
255
|
|
|
@@ -229,45 +259,56 @@ Bubble style definitions are shared within the extension, but each sprite or clo
|
|
|
229
259
|
|
|
230
260
|
When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables owned by that target are released automatically.
|
|
231
261
|
|
|
232
|
-
##
|
|
233
|
-
|
|
234
|
-
| Block
|
|
235
|
-
|
|
|
236
|
-
| `define bubble style [STYLE] using text style [TEXT_STYLE]`
|
|
237
|
-
| `set bubble placement [PLACEMENT] for bubble style [STYLE]`
|
|
238
|
-
| `set bubble distance [DISTANCE] for bubble style [STYLE]`
|
|
239
|
-
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]`
|
|
240
|
-
| `set bubble tail length [LENGTH] for bubble style [STYLE]`
|
|
241
|
-
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]`
|
|
242
|
-
| `set portrait base [ASSET] for bubble style [STYLE]`
|
|
243
|
-
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]`
|
|
244
|
-
| `set
|
|
245
|
-
| `set
|
|
246
|
-
| `
|
|
247
|
-
| `
|
|
248
|
-
| `set
|
|
249
|
-
| `
|
|
250
|
-
| `
|
|
251
|
-
| `
|
|
252
|
-
|
|
253
|
-
|
|
262
|
+
## 11. Block reference
|
|
263
|
+
|
|
264
|
+
| Block | Description |
|
|
265
|
+
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
|
|
266
|
+
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
|
|
267
|
+
| `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
|
|
268
|
+
| `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
|
|
269
|
+
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten SVG body shapes |
|
|
270
|
+
| `set bubble tail length [LENGTH] for bubble style [STYLE]` | Set the nominal border-to-tip tail length |
|
|
271
|
+
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Set body position and whole-Bubble scale, including text |
|
|
272
|
+
| `set portrait base [ASSET] for bubble style [STYLE]` | Set the portrait base image |
|
|
273
|
+
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set blink overlays and interval |
|
|
274
|
+
| `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set lip-sync overlays and interval |
|
|
275
|
+
| `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set the animation shown during `awaiting-continue` |
|
|
276
|
+
| `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | Configure CHARACTER/WORD/LINE/BLOCK sequential reveal |
|
|
277
|
+
| `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | Configure WORD delimiters and visibility |
|
|
278
|
+
| `set bubble reveal sound [ASSET] for bubble style [STYLE]` | Set the per-unit reveal sound |
|
|
279
|
+
| `set bubble voice [ASSET] for bubble style [STYLE]` | Set full voice played when display starts |
|
|
280
|
+
| `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | Reveal remaining units and wait for condition or timeout |
|
|
281
|
+
| `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configure show animation |
|
|
282
|
+
| `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configure hide animation |
|
|
283
|
+
| `animate this bubble [MOTION]` | Play a whole-Bubble animation |
|
|
284
|
+
| `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shake the complete Bubble surface |
|
|
285
|
+
| `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Apply relative scale cycles to the Bubble |
|
|
286
|
+
| `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transition the Bubble outline |
|
|
287
|
+
| `say [MESSAGE] with bubble style [STYLE]` | Start or replace a `say` Bubble in `talking` mode |
|
|
288
|
+
| `think [MESSAGE] with bubble style [STYLE]` | Start or replace a `think` Bubble in `talking` mode |
|
|
289
|
+
| `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-continue`, or `idle` for this Bubble |
|
|
290
|
+
| `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
|
|
291
|
+
| `close this bubble` | Release this target's Bubble and owned resources |
|
|
292
|
+
| `Bubble version` | Report the Bubble implementation version |
|
|
293
|
+
|
|
294
|
+
## 12. Troubleshooting
|
|
254
295
|
|
|
255
296
|
| Symptom | Cause and solution |
|
|
256
297
|
| ------------------------------------ | --------------------------------------------------------------------------- |
|
|
257
|
-
| Asset Manager required error | Load Asset Manager 0.7.x without sandbox
|
|
258
|
-
| SVG Text required error | Load SVG Text 0.
|
|
298
|
+
| Asset Manager required error | Load Asset Manager 0.7.x without sandbox before using image/media assets |
|
|
299
|
+
| SVG Text required error | Load SVG Text 0.4.x without sandbox |
|
|
259
300
|
| Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
|
|
260
301
|
| Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
|
|
261
302
|
| `bubble style is not defined` | Run `define bubble style` first, including after restarting with green flag |
|
|
262
303
|
| Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
|
|
263
304
|
| Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
|
|
264
|
-
| Only one
|
|
305
|
+
| Only one continue frame | Supply at least two frames, or clear the setting |
|
|
265
306
|
| Frame interval error | Use a finite `SECONDS` value greater than zero |
|
|
266
307
|
| Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
|
|
267
308
|
| Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
|
|
268
309
|
| Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
|
|
269
310
|
|
|
270
|
-
##
|
|
311
|
+
## 13. Automatic cleanup
|
|
271
312
|
|
|
272
313
|
Bubble automatically releases its owned timers, SVG Text skins, and renderer drawables when:
|
|
273
314
|
|
|
@@ -280,7 +321,7 @@ Bubble automatically releases its owned timers, SVG Text skins, and renderer dra
|
|
|
280
321
|
|
|
281
322
|
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
323
|
|
|
283
|
-
##
|
|
324
|
+
## 14. Regenerating the manual assets
|
|
284
325
|
|
|
285
326
|
The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick `magick` command.
|
|
286
327
|
|