@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.
- package/README.md +327 -236
- package/README_ja.md +693 -0
- package/THIRD_PARTY_NOTICES.md +10 -0
- package/dist/composition.js +835 -668
- package/dist/extension-manifest.json +34 -0
- package/dist/turbowarp-adapter.js +2789 -1056
- package/dist/turbowarp-bubble.js +2620 -209
- package/dist/types/asset-manager-image-adapter.d.ts +18 -0
- package/dist/types/bubble-svg.d.ts +4 -0
- package/dist/types/composition.d.ts +5 -0
- package/dist/types/scratch-default.d.ts +67 -0
- package/dist/types/surface-motion.d.ts +8 -0
- package/dist/types/svg-overlay-surface.d.ts +97 -0
- package/dist/types/text-capability.d.ts +2 -2
- package/dist/types/turbowarp-adapter.d.ts +22 -2
- package/dist/types/turbowarp-svg-text-adapter.d.ts +40 -0
- package/docs/assets/block-quick-start.svg +35 -60
- package/docs/assets/bubble-lifecycle.gif +0 -0
- package/docs/assets/bubble-style-gallery.svg +2 -20
- package/docs/assets/turbowarp-say-think-block-comparison.png +0 -0
- package/docs/assets/turbowarp-say-think-stage-comparison.png +0 -0
- package/docs/block-manual.ja.md +81 -63
- package/docs/block-manual.md +65 -47
- package/docs/index.html +53 -46
- package/docs/ja/index.html +53 -46
- package/docs/release-notes-0.8.0.md +96 -0
- package/docs/release-notes-0.9.0.md +47 -0
- package/package.json +8 -9
package/docs/block-manual.ja.md
CHANGED
|
@@ -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
|

|
|
6
8
|
|
|
7
9
|
## 1. 必要な拡張機能
|
|
8
10
|
|
|
9
|
-
入力待ちを含む完全な例では
|
|
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.
|
|
15
|
-
| 3 | Runtime Expression 0.
|
|
16
|
-
| 4 | Asset Manager 0.
|
|
17
|
-
| 5 |
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+

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

|
|
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 [
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
249
|
-
think [MESSAGE] with bubble style [STYLE]
|
|
262
|
+
show [MESSAGE] with bubble style [STYLE]
|
|
250
263
|
```
|
|
251
264
|
|
|
252
|
-
|
|
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、
|
|
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]` |
|
|
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]
|
|
293
|
-
| `think [MESSAGE]
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
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.
|
|
304
|
-
|
|
|
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` |
|
|
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
|
|
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
|
package/docs/block-manual.md
CHANGED
|
@@ -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
|

|
|
6
8
|
|
|
7
9
|
## 1. Load the required extensions
|
|
8
10
|
|
|
9
|
-
The complete input-wait example uses
|
|
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.
|
|
15
|
-
| 3 | Runtime Expression 0.
|
|
16
|
-
| 4 | Asset Manager 0.
|
|
17
|
-
| 5 |
|
|
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
|
|
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.
|
|
60
|
+
## 3. Select a text layout style
|
|
60
61
|
|
|
61
|
-
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+

|
|
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
|
+

|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
249
|
-
think [MESSAGE] with bubble style [STYLE]
|
|
262
|
+
show [MESSAGE] with bubble style [STYLE]
|
|
250
263
|
```
|
|
251
264
|
|
|
252
|
-
|
|
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,
|
|
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
|
|
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]
|
|
293
|
-
| `think [MESSAGE]
|
|
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.
|
|
304
|
-
|
|
|
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` |
|
|
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
|
|
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
|