@kubohiroya/turbowarp-bubble 0.8.0 → 0.10.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 +308 -242
- package/README_ja.md +709 -0
- package/dist/composition.js +835 -668
- package/dist/extension-manifest.json +71 -0
- package/dist/turbowarp-adapter.js +1911 -1337
- package/dist/turbowarp-bubble.js +1185 -146
- 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/svg-overlay-surface.d.ts +2 -2
- package/dist/types/turbowarp-adapter.d.ts +4 -1
- package/dist/types/turbowarp-svg-text-adapter.d.ts +5 -0
- package/docs/assets/block-quick-start.svg +8 -8
- 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 +96 -58
- package/docs/block-manual.md +69 -31
- package/docs/index.html +57 -23
- package/docs/ja/index.html +57 -23
- package/docs/release-notes-0.10.0.md +50 -0
- package/docs/release-notes-0.8.0.md +63 -12
- package/docs/release-notes-0.9.0.md +47 -0
- package/package.json +5 -3
package/docs/block-manual.md
CHANGED
|
@@ -8,17 +8,17 @@ This manual explains how to use `turbowarp-bubble` as an unsandboxed TurboWarp c
|
|
|
8
8
|
|
|
9
9
|
## 1. Load the required extensions
|
|
10
10
|
|
|
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.
|
|
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 for condition-based Bubble waits and close policies; a timeout-only close policy needs neither.
|
|
12
12
|
|
|
13
13
|
| Order | Extension | URL |
|
|
14
14
|
| ----: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
|
|
15
15
|
| 1 | Temporary Variables | Add from the TurboWarp extension library |
|
|
16
16
|
| 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
|
|
17
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.
|
|
19
|
-
| 5 | Bubble 0.
|
|
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.10.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js` |
|
|
20
20
|
|
|
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
|
+
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 condition-based Bubble wait. The lower-level Composition API can inject another text capability.
|
|
22
22
|
|
|
23
23
|
See also:
|
|
24
24
|
|
|
@@ -59,17 +59,36 @@ For a remote image, pass its HTTPS URL as `RESOURCE_ID`. Bubble accepts only ass
|
|
|
59
59
|
|
|
60
60
|
## 3. Select a text layout style
|
|
61
61
|
|
|
62
|
-
Standalone Bubble bundles the SVG Text 0.8.
|
|
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.
|
|
63
63
|
|
|
64
64
|
```text
|
|
65
65
|
define bubble style [hero-dialogue] using text style [default]
|
|
66
66
|
```
|
|
67
67
|
|
|
68
|
-
Application hosts that need custom fonts, colors, or alignment can define styles on `createSvgTextLayoutComposition()` and inject them through `createSvgTextOverlayTextCapability()`. The
|
|
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.
|
|
69
69
|
|
|
70
70
|
## 4. Define a Bubble style
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
For a basic Bubble, use the short blocks directly. They select the built-in Bubble styles `say` and `think`, respectively:
|
|
73
|
+
|
|
74
|
+
```text
|
|
75
|
+
say [Hello!]
|
|
76
|
+
think [Hmm…]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### TurboWarp standard comparison
|
|
80
|
+
|
|
81
|
+
These screenshots come from one TurboWarp Editor project using the English UI, a `Cat` sprite at `x=-80`, `y=0`, size `80%`, a white Stage, and matching `Hello!` / `Hmm...` inputs. The standard Looks blocks are on the left. Bubble's short basic blocks are on the right and use their matching built-in `say` / `think` styles; no definition or setter block is used.
|
|
82
|
+
|
|
83
|
+

|
|
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:
|
|
73
92
|
|
|
74
93
|
```text
|
|
75
94
|
define bubble style [hero-dialogue] using text style [default]
|
|
@@ -88,7 +107,7 @@ Each of the 16 actor-relative directions is shown as a complete mini-scene conta
|
|
|
88
107
|
|
|
89
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.
|
|
90
109
|
|
|
91
|
-
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:
|
|
92
111
|
|
|
93
112
|
```text
|
|
94
113
|
up / up-up-right / up-right / right-up-right
|
|
@@ -179,7 +198,7 @@ set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bu
|
|
|
179
198
|
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
180
199
|
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
181
200
|
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
182
|
-
|
|
201
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
183
202
|
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
|
|
184
203
|
```
|
|
185
204
|
|
|
@@ -193,7 +212,7 @@ finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] sec
|
|
|
193
212
|
set runtime variable [input] to []
|
|
194
213
|
listen for key [Space] set runtime var [input] to [pressed]
|
|
195
214
|
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
196
|
-
|
|
215
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
197
216
|
wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
|
|
198
217
|
close this bubble
|
|
199
218
|
```
|
|
@@ -202,6 +221,16 @@ Initialize `input` with Temporary Variables before registering the Async Input l
|
|
|
202
221
|
|
|
203
222
|
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.
|
|
204
223
|
|
|
224
|
+
Use a named Bubble close policy when the same closing rule is reused. The trigger is explicit: `condition`, `timeout`, or `condition-or-timeout`. Applying a policy snapshots its definition, waits, runs the Bubble's hide animation, and releases the Bubble in one blocking command.
|
|
225
|
+
|
|
226
|
+
```text
|
|
227
|
+
define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == "pressed"] timeout [10] seconds
|
|
228
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
229
|
+
wait and close this bubble using close policy [advance-or-timeout]
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
A timeout-only policy leaves the current animation mode unchanged and needs no input extension. A policy containing a condition enters `awaiting-continue` and uses the same Async Input and Runtime Expression setup as the integrated wait. Redefining the same name during a pending wait affects only later applications. Bubble replacement or lifecycle cleanup cancels the pending policy and does not close the replacement Bubble.
|
|
233
|
+
|
|
205
234
|
When combining Bubble with audio or a separate text-reveal system, switch to `awaiting-continue` when that process completes.
|
|
206
235
|
|
|
207
236
|

|
|
@@ -235,14 +264,15 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
|
|
|
235
264
|
|
|
236
265
|
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.
|
|
237
266
|
|
|
238
|
-
|
|
267
|
+
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.
|
|
268
|
+
|
|
269
|
+
## 9. Showing a named Bubble style
|
|
239
270
|
|
|
240
271
|
```text
|
|
241
|
-
|
|
242
|
-
think [MESSAGE] with bubble style [STYLE]
|
|
272
|
+
show [MESSAGE] with bubble style [STYLE]
|
|
243
273
|
```
|
|
244
274
|
|
|
245
|
-
|
|
275
|
+
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.
|
|
246
276
|
|
|
247
277
|
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.
|
|
248
278
|
|
|
@@ -261,9 +291,10 @@ When a clone stops or is deleted, its timers, overlay DOM, and image leases are
|
|
|
261
291
|
| Block | Description |
|
|
262
292
|
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
263
293
|
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
|
|
294
|
+
| `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | Define or replace a named closing condition |
|
|
264
295
|
| `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
|
|
265
296
|
| `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
|
|
266
|
-
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten SVG body
|
|
297
|
+
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten inseparable SVG body + tail/trail pairs |
|
|
267
298
|
| `set bubble tail length [LENGTH] for bubble style [STYLE]` | Set the nominal border-to-tip tail length |
|
|
268
299
|
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Set body position and whole-Bubble scale, including text |
|
|
269
300
|
| `set portrait base [ASSET] for bubble style [STYLE]` | Set the portrait base image |
|
|
@@ -282,29 +313,34 @@ When a clone stops or is deleted, its timers, overlay DOM, and image leases are
|
|
|
282
313
|
| `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shake the complete Bubble surface |
|
|
283
314
|
| `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Apply relative scale cycles to the Bubble |
|
|
284
315
|
| `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transition the Bubble outline |
|
|
285
|
-
| `say [MESSAGE]
|
|
286
|
-
| `think [MESSAGE]
|
|
316
|
+
| `say [MESSAGE]` | Show built-in style `say`: speech body and speech tail |
|
|
317
|
+
| `think [MESSAGE]` | Show built-in style `think`: thought body and round trail |
|
|
318
|
+
| `show [MESSAGE] with bubble style [STYLE]` | Show the complete body and tail/trail pair owned by a style |
|
|
287
319
|
| `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-continue`, or `idle` for this Bubble |
|
|
288
320
|
| `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
|
|
321
|
+
| `wait and close this bubble using close policy [POLICY]` | Snapshot a policy, wait for it, and close the Bubble |
|
|
289
322
|
| `close this bubble` | Release this target's Bubble and owned resources |
|
|
290
323
|
| `Bubble version` | Report the Bubble implementation version |
|
|
291
324
|
|
|
325
|
+
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.
|
|
326
|
+
|
|
292
327
|
## 12. Troubleshooting
|
|
293
328
|
|
|
294
|
-
| Symptom | Cause and solution
|
|
295
|
-
| ------------------------------------ |
|
|
296
|
-
| Asset Manager required error | Load Asset Manager 0.
|
|
297
|
-
| SVG overlay backend error | Use a host with `renderer.addOverlay()` or explicitly select `scratch-render`
|
|
298
|
-
| Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait
|
|
299
|
-
| Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait
|
|
300
|
-
| `bubble style is not defined` |
|
|
301
|
-
|
|
|
302
|
-
|
|
|
303
|
-
|
|
|
304
|
-
|
|
|
305
|
-
|
|
|
306
|
-
|
|
|
307
|
-
|
|
|
329
|
+
| Symptom | Cause and solution |
|
|
330
|
+
| ------------------------------------ | ------------------------------------------------------------------------------- |
|
|
331
|
+
| Asset Manager required error | Load Asset Manager 0.12.x without sandbox before using image/media assets |
|
|
332
|
+
| SVG overlay backend error | Use a host with `renderer.addOverlay()` or explicitly select `scratch-render` |
|
|
333
|
+
| Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
|
|
334
|
+
| Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
|
|
335
|
+
| `bubble style is not defined` | Use the built-in short say/think blocks, or define the named custom style first |
|
|
336
|
+
| `bubble close policy is not defined` | Define the named close policy before applying it |
|
|
337
|
+
| Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
|
|
338
|
+
| Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
|
|
339
|
+
| Only one continue frame | Supply at least two frames, or clear the setting |
|
|
340
|
+
| Frame interval error | Use a finite `SECONDS` value greater than zero |
|
|
341
|
+
| Actor-relative Bubble from the Stage | Use `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE` |
|
|
342
|
+
| Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
|
|
343
|
+
| Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
|
|
308
344
|
|
|
309
345
|
## 13. Automatic cleanup
|
|
310
346
|
|
|
@@ -323,6 +359,8 @@ Assets registered with Asset Manager are not owned by Bubble. To remove an unuse
|
|
|
323
359
|
|
|
324
360
|
The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick `magick` command.
|
|
325
361
|
|
|
362
|
+
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`.
|
|
363
|
+
|
|
326
364
|
```sh
|
|
327
365
|
pnpm docs:render
|
|
328
366
|
pnpm docs:check
|
package/docs/index.html
CHANGED
|
@@ -74,7 +74,7 @@
|
|
|
74
74
|
</blockquote>
|
|
75
75
|
<p><img src="./assets/block-quick-start.svg" alt="A quick-start block sequence that registers Next1 and Next2 separately, prepares input listeners, then uses Bubble's integrated wait"></p>
|
|
76
76
|
<h2 id="requirements">1. Load the required extensions</h2>
|
|
77
|
-
<p>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 <strong>Run without sandbox</strong> enabled. Bubble bundles the host-neutral SVG Text 0.8.
|
|
77
|
+
<p>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 <strong>Run without sandbox</strong> 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 for condition-based Bubble waits and close policies; a timeout-only close policy needs neither.</p>
|
|
78
78
|
<table>
|
|
79
79
|
<thead>
|
|
80
80
|
<tr>
|
|
@@ -100,16 +100,16 @@
|
|
|
100
100
|
</tr>
|
|
101
101
|
<tr>
|
|
102
102
|
<td align="right">4</td>
|
|
103
|
-
<td>Asset Manager 0.
|
|
104
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.
|
|
103
|
+
<td>Asset Manager 0.12.1</td>
|
|
104
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js</code></td>
|
|
105
105
|
</tr>
|
|
106
106
|
<tr>
|
|
107
107
|
<td align="right">5</td>
|
|
108
|
-
<td>Bubble 0.
|
|
109
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.
|
|
108
|
+
<td>Bubble 0.10.0</td>
|
|
109
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js</code></td>
|
|
110
110
|
</tr>
|
|
111
111
|
</tbody></table>
|
|
112
|
-
<p>To try a development build, load this repository's <code>dist/turbowarp-bubble.js</code> 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.</p>
|
|
112
|
+
<p>To try a development build, load this repository's <code>dist/turbowarp-bubble.js</code> 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 condition-based Bubble wait. The lower-level Composition API can inject another text capability.</p>
|
|
113
113
|
<p>See also:</p>
|
|
114
114
|
<ul>
|
|
115
115
|
<li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/">Asset Manager guide</a></li>
|
|
@@ -175,12 +175,22 @@ register resource [costume:Assets:Next2] as asset [Next2]
|
|
|
175
175
|
</code></pre>
|
|
176
176
|
<p>For a remote image, pass its HTTPS URL as <code>RESOURCE_ID</code>. Bubble accepts only assets already registered with Asset Manager whose MIME type is <code>image/*</code>.</p>
|
|
177
177
|
<h2 id="text-style">3. Select a text layout style</h2>
|
|
178
|
-
<p>Standalone Bubble bundles the SVG Text 0.8.
|
|
178
|
+
<p>Standalone Bubble bundles the SVG Text 0.8.1 layout composition and installs two Bubble styles: <code>say</code> owns the speech body and speech tail, while <code>think</code> 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 <code>say [MESSAGE]</code> and <code>think [MESSAGE]</code> 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 <code>default</code>, 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 <code>getLayoutCapability()</code> 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.</p>
|
|
179
179
|
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
|
|
180
180
|
</code></pre>
|
|
181
|
-
<p>Application hosts that need custom fonts, colors, or alignment can define styles on <code>createSvgTextLayoutComposition()</code> and inject them through <code>createSvgTextOverlayTextCapability()</code>. The
|
|
181
|
+
<p>Application hosts that need custom fonts, colors, or alignment can define styles on <code>createSvgTextLayoutComposition()</code> and inject them through <code>createSvgTextOverlayTextCapability()</code>. The custom profile uses the same <code>layoutText()</code> API and does not create an SVG text skin on the default overlay backend. Bubble owns placement, tail, and outer shape.</p>
|
|
182
182
|
<h2 id="bubble-style">4. Define a Bubble style</h2>
|
|
183
|
-
<p>
|
|
183
|
+
<p>For a basic Bubble, use the short blocks directly. They select the built-in Bubble styles <code>say</code> and <code>think</code>, respectively:</p>
|
|
184
|
+
<pre><code class="language-text">say [Hello!]
|
|
185
|
+
think [Hmm…]
|
|
186
|
+
</code></pre>
|
|
187
|
+
<h3>TurboWarp standard comparison</h3>
|
|
188
|
+
<p>These screenshots come from one TurboWarp Editor project using the English UI, a <code>Cat</code> sprite at <code>x=-80</code>, <code>y=0</code>, size <code>80%</code>, a white Stage, and matching <code>Hello!</code> / <code>Hmm...</code> inputs. The standard Looks blocks are on the left. Bubble's short basic blocks are on the right and use their matching built-in <code>say</code> / <code>think</code> styles; no definition or setter block is used.</p>
|
|
189
|
+
<p><img src="./assets/turbowarp-say-think-stage-comparison.png" alt="TurboWarp standard say and think bubbles compared on the Stage with Bubble's basic profile"></p>
|
|
190
|
+
<p>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.</p>
|
|
191
|
+
<p><img src="./assets/turbowarp-say-think-block-comparison.png" alt="TurboWarp standard say and think blocks compared with Bubble's no-setup basic say and think blocks and built-in default profile values"></p>
|
|
192
|
+
<p>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 <code>default</code>, and lists the shared typography, geometry, colors, border paint order, and placement. Use <code>show [MESSAGE] with bubble style [STYLE]</code> for named custom styles. The former styled say/think opcodes remain hidden compatibility definitions for saved projects.</p>
|
|
193
|
+
<p>The following setters intentionally switch the style to the custom profile:</p>
|
|
184
194
|
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
|
|
185
195
|
set bubble placement [up-right] for bubble style [hero-dialogue]
|
|
186
196
|
set bubble distance [12] for bubble style [hero-dialogue]
|
|
@@ -192,7 +202,7 @@ set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
|
|
|
192
202
|
<p><img src="./assets/placement-guide.svg" alt="Actor-relative 16-way and angle placement compared with three stage-relative placements"></p>
|
|
193
203
|
<p>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.</p>
|
|
194
204
|
<p>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 <code>renderBubbleSvg</code> implementation.</p>
|
|
195
|
-
<p>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:</p>
|
|
205
|
+
<p>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:</p>
|
|
196
206
|
<pre><code class="language-text">up / up-up-right / up-right / right-up-right
|
|
197
207
|
right / right-down-right / down-right / down-down-right
|
|
198
208
|
down / down-down-left / down-left / left-down-left
|
|
@@ -271,7 +281,7 @@ set continue frames [Next1,Next2]
|
|
|
271
281
|
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
272
282
|
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
273
283
|
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
274
|
-
|
|
284
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
275
285
|
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
|
|
276
286
|
</code></pre>
|
|
277
287
|
<p><code>DYNAMIC</code> recalculates the Bubble size and placement after each unit. <code>RESERVED</code> measures the final text first and reserves that layout while units appear. <code>set bubble reveal sound</code> plays a named Asset Manager audio asset per unit, while <code>set bubble voice</code> plays full voice audio when the Bubble starts. Text display remains available without audio.</p>
|
|
@@ -280,12 +290,18 @@ finish [CHARACTER] with condition [input == "pressed"] or timeout afte
|
|
|
280
290
|
<pre><code class="language-text">set runtime variable [input] to []
|
|
281
291
|
listen for key [Space] set runtime var [input] to [pressed]
|
|
282
292
|
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
283
|
-
|
|
293
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
284
294
|
wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
|
|
285
295
|
close this bubble
|
|
286
296
|
</code></pre>
|
|
287
297
|
<p>Initialize <code>input</code> 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 <code>input == "pressed"</code> to Runtime Expression immediately and once per VM frame. While waiting it automatically enters <code>awaiting-continue</code>, stops lip-sync, and loops the images configured by <code>set continue frames</code>. When the condition becomes true or the timeout expires, it enters <code>idle</code> and continues to <code>close this bubble</code>. Set the timeout to <code>0</code> to wait without a timeout.</p>
|
|
288
298
|
<p>Reset <code>input</code> to an empty string before each later wait; otherwise the previous <code>pressed</code> 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.</p>
|
|
299
|
+
<p>Use a named Bubble close policy when the same closing rule is reused. The trigger is explicit: <code>condition</code>, <code>timeout</code>, or <code>condition-or-timeout</code>. Applying a policy snapshots its definition, waits, runs the Bubble's hide animation, and releases the Bubble in one blocking command.</p>
|
|
300
|
+
<pre><code class="language-text">define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == "pressed"] timeout [10] seconds
|
|
301
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
302
|
+
wait and close this bubble using close policy [advance-or-timeout]
|
|
303
|
+
</code></pre>
|
|
304
|
+
<p>A timeout-only policy leaves the current animation mode unchanged and needs no input extension. A policy containing a condition enters <code>awaiting-continue</code> and uses the same Async Input and Runtime Expression setup as the integrated wait. Redefining the same name during a pending wait affects only later applications. Bubble replacement or lifecycle cleanup cancels the pending policy and does not close the replacement Bubble.</p>
|
|
289
305
|
<p>When combining Bubble with audio or a separate text-reveal system, switch to <code>awaiting-continue</code> when that process completes.</p>
|
|
290
306
|
<p><img src="./assets/bubble-lifecycle.gif" alt="A say Bubble lip-syncs, shows continue frames while awaiting continue, then closes after input"></p>
|
|
291
307
|
<p>If animated GIF playback is unavailable, use this static animation-mode comparison:</p>
|
|
@@ -334,11 +350,11 @@ explode this bubble relative scale [1.15] count [2] ease [easeOut]
|
|
|
334
350
|
animate bubble shape to [WAVY] speed [1] for [0.5] seconds
|
|
335
351
|
</code></pre>
|
|
336
352
|
<p>The TurboWarp adapter advances these motions on scheduler frames and applies <code>ease</code> to each frame. <code>shake</code> applies direction and count to the complete Bubble surface, <code>explode</code> expands and returns the relative scale of text and portrait together, and <code>animate bubble shape</code> cross-fades the current outline into styles such as <code>THINKING</code>, <code>DREAMING</code>, <code>YELLING</code>, <code>WAVY</code>, or <code>WHISPERING</code> during the requested speed and duration.</p>
|
|
337
|
-
<
|
|
338
|
-
<
|
|
339
|
-
|
|
353
|
+
<p>Use <code>close this bubble</code> to remove the current Bubble. It runs the configured hide animation and then releases the Bubble's timers and rendering resources. <code>set bubble hide animation ...</code> only configures that exit effect; it does not remove a Bubble by itself. For the built-in basic profile, passing an empty value to <code>say</code> or <code>think</code> also closes the Bubble, matching TurboWarp's standard behavior. Bubble does not expose a separate <code>hide</code> block because closing destroys the display rather than preserving a hidden instance for later reuse.</p>
|
|
354
|
+
<h2 id="reference">9. Showing a named Bubble style</h2>
|
|
355
|
+
<pre><code class="language-text">show [MESSAGE] with bubble style [STYLE]
|
|
340
356
|
</code></pre>
|
|
341
|
-
<p>
|
|
357
|
+
<p>The selected Bubble style determines the body and tail/trail together, along with its text profile, portrait layers, placement, and animation settings. <code>set bubble visual style</code> selects an inseparable pair such as <code>NORMAL</code> (speech body + speech tail) or <code>THINKING</code> (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.</p>
|
|
342
358
|
<p>Running a new <code>say</code> or <code>think</code> 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.</p>
|
|
343
359
|
<h2 id="troubleshooting">10. Using Bubble with clones</h2>
|
|
344
360
|
<p>Bubble style definitions are shared within the extension, but each sprite or clone owns its currently displayed Bubble.</p>
|
|
@@ -361,6 +377,10 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
361
377
|
<td>Define or redefine a Bubble style</td>
|
|
362
378
|
</tr>
|
|
363
379
|
<tr>
|
|
380
|
+
<td><code>define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds</code></td>
|
|
381
|
+
<td>Define or replace a named closing condition</td>
|
|
382
|
+
</tr>
|
|
383
|
+
<tr>
|
|
364
384
|
<td><code>set bubble placement [PLACEMENT] for bubble style [STYLE]</code></td>
|
|
365
385
|
<td>Set an actor direction/angle or a stage-relative region</td>
|
|
366
386
|
</tr>
|
|
@@ -370,7 +390,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
370
390
|
</tr>
|
|
371
391
|
<tr>
|
|
372
392
|
<td><code>set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]</code></td>
|
|
373
|
-
<td>Select one of ten SVG body
|
|
393
|
+
<td>Select one of ten inseparable SVG body + tail/trail pairs</td>
|
|
374
394
|
</tr>
|
|
375
395
|
<tr>
|
|
376
396
|
<td><code>set bubble tail length [LENGTH] for bubble style [STYLE]</code></td>
|
|
@@ -445,12 +465,16 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
445
465
|
<td>Transition the Bubble outline</td>
|
|
446
466
|
</tr>
|
|
447
467
|
<tr>
|
|
448
|
-
<td><code>say [MESSAGE]
|
|
449
|
-
<td>
|
|
468
|
+
<td><code>say [MESSAGE]</code></td>
|
|
469
|
+
<td>Show built-in style <code>say</code>: speech body and speech tail</td>
|
|
470
|
+
</tr>
|
|
471
|
+
<tr>
|
|
472
|
+
<td><code>think [MESSAGE]</code></td>
|
|
473
|
+
<td>Show built-in style <code>think</code>: thought body and round trail</td>
|
|
450
474
|
</tr>
|
|
451
475
|
<tr>
|
|
452
|
-
<td><code>
|
|
453
|
-
<td>
|
|
476
|
+
<td><code>show [MESSAGE] with bubble style [STYLE]</code></td>
|
|
477
|
+
<td>Show the complete body and tail/trail pair owned by a style</td>
|
|
454
478
|
</tr>
|
|
455
479
|
<tr>
|
|
456
480
|
<td><code>set this bubble animation mode [MODE]</code></td>
|
|
@@ -461,6 +485,10 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
461
485
|
<td>Await a Runtime Expression condition or optional timeout</td>
|
|
462
486
|
</tr>
|
|
463
487
|
<tr>
|
|
488
|
+
<td><code>wait and close this bubble using close policy [POLICY]</code></td>
|
|
489
|
+
<td>Snapshot a policy, wait for it, and close the Bubble</td>
|
|
490
|
+
</tr>
|
|
491
|
+
<tr>
|
|
464
492
|
<td><code>close this bubble</code></td>
|
|
465
493
|
<td>Release this target's Bubble and owned resources</td>
|
|
466
494
|
</tr>
|
|
@@ -469,6 +497,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
469
497
|
<td>Report the Bubble implementation version</td>
|
|
470
498
|
</tr>
|
|
471
499
|
</tbody></table>
|
|
500
|
+
<p>Saved projects using the former <code>say/think [MESSAGE] with bubble style [STYLE]</code> opcodes continue to run, but those two compatibility blocks are hidden from the palette. New scripts use the unified <code>show</code> block so the selected style alone determines the complete body and tail/trail shape.</p>
|
|
472
501
|
<h2 id="regeneration">12. Troubleshooting</h2>
|
|
473
502
|
<table>
|
|
474
503
|
<thead>
|
|
@@ -479,7 +508,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
479
508
|
</thead>
|
|
480
509
|
<tbody><tr>
|
|
481
510
|
<td>Asset Manager required error</td>
|
|
482
|
-
<td>Load Asset Manager 0.
|
|
511
|
+
<td>Load Asset Manager 0.12.x without sandbox before using image/media assets</td>
|
|
483
512
|
</tr>
|
|
484
513
|
<tr>
|
|
485
514
|
<td>SVG overlay backend error</td>
|
|
@@ -495,7 +524,11 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
495
524
|
</tr>
|
|
496
525
|
<tr>
|
|
497
526
|
<td><code>bubble style is not defined</code></td>
|
|
498
|
-
<td>
|
|
527
|
+
<td>Use the built-in short say/think blocks, or define the named custom style first</td>
|
|
528
|
+
</tr>
|
|
529
|
+
<tr>
|
|
530
|
+
<td><code>bubble close policy is not defined</code></td>
|
|
531
|
+
<td>Define the named close policy before applying it</td>
|
|
499
532
|
</tr>
|
|
500
533
|
<tr>
|
|
501
534
|
<td>Image asset is not registered</td>
|
|
@@ -539,6 +572,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
539
572
|
<p>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 <code>delete asset [NAME] from memory</code> block.</p>
|
|
540
573
|
<h2>14. Regenerating the manual assets</h2>
|
|
541
574
|
<p>The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick <code>magick</code> command.</p>
|
|
575
|
+
<p>The two <code>turbowarp-say-think-*-comparison.png</code> 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 <code>docs:render</code>.</p>
|
|
542
576
|
<pre><code class="language-sh">pnpm docs:render
|
|
543
577
|
pnpm docs:check
|
|
544
578
|
</code></pre>
|