@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/index.html
CHANGED
|
@@ -69,9 +69,12 @@
|
|
|
69
69
|
<main id="manual" class="manual">
|
|
70
70
|
<h1>TurboWarp Bubble Block Manual</h1>
|
|
71
71
|
<p>This manual explains how to use <code>turbowarp-bubble</code> 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.</p>
|
|
72
|
+
<blockquote>
|
|
73
|
+
<p><strong>Kamishibai DSL 4.0 bundle:</strong> In the combined runtime palette, click the documentation button directly below the <strong>Bubble</strong> 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.</p>
|
|
74
|
+
</blockquote>
|
|
72
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>
|
|
73
76
|
<h2 id="requirements">1. Load the required extensions</h2>
|
|
74
|
-
<p>The complete input-wait example uses
|
|
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 before using a Bubble wait.</p>
|
|
75
78
|
<table>
|
|
76
79
|
<thead>
|
|
77
80
|
<tr>
|
|
@@ -87,31 +90,26 @@
|
|
|
87
90
|
</tr>
|
|
88
91
|
<tr>
|
|
89
92
|
<td align="right">2</td>
|
|
90
|
-
<td>Async Input 0.
|
|
91
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.
|
|
93
|
+
<td>Async Input 0.4.0</td>
|
|
94
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js</code></td>
|
|
92
95
|
</tr>
|
|
93
96
|
<tr>
|
|
94
97
|
<td align="right">3</td>
|
|
95
|
-
<td>Runtime Expression 0.
|
|
96
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.
|
|
98
|
+
<td>Runtime Expression 0.4.0</td>
|
|
99
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js</code></td>
|
|
97
100
|
</tr>
|
|
98
101
|
<tr>
|
|
99
102
|
<td align="right">4</td>
|
|
100
|
-
<td>Asset Manager 0.
|
|
101
|
-
<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>
|
|
102
105
|
</tr>
|
|
103
106
|
<tr>
|
|
104
107
|
<td align="right">5</td>
|
|
105
|
-
<td>
|
|
106
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-
|
|
107
|
-
</tr>
|
|
108
|
-
<tr>
|
|
109
|
-
<td align="right">6</td>
|
|
110
|
-
<td>Bubble 0.7.0</td>
|
|
111
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js</code></td>
|
|
108
|
+
<td>Bubble 0.9.0</td>
|
|
109
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js</code></td>
|
|
112
110
|
</tr>
|
|
113
111
|
</tbody></table>
|
|
114
|
-
<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
|
|
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>
|
|
115
113
|
<p>See also:</p>
|
|
116
114
|
<ul>
|
|
117
115
|
<li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/">Asset Manager guide</a></li>
|
|
@@ -176,21 +174,24 @@ register resource [costume:Assets:Next1] as asset [Next1]
|
|
|
176
174
|
register resource [costume:Assets:Next2] as asset [Next2]
|
|
177
175
|
</code></pre>
|
|
178
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>
|
|
179
|
-
<h2 id="text-style">3.
|
|
180
|
-
<p>
|
|
181
|
-
<pre><code class="language-text">define
|
|
182
|
-
background [#fff4cc]
|
|
183
|
-
text [#332200]
|
|
184
|
-
font [Noto Sans JP]
|
|
185
|
-
size [100]
|
|
186
|
-
align [left]
|
|
187
|
-
bubble direction [up]
|
|
177
|
+
<h2 id="text-style">3. Select a text layout style</h2>
|
|
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
|
+
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
|
|
188
180
|
</code></pre>
|
|
189
|
-
<p>
|
|
190
|
-
<p>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 <code>set bubble placement</code>; the SVG Text provider does not own Bubble direction, tail, or outer shape.</p>
|
|
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>
|
|
191
182
|
<h2 id="bubble-style">4. Define a Bubble style</h2>
|
|
192
|
-
<p>
|
|
193
|
-
<pre><code class="language-text">
|
|
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>
|
|
194
|
+
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
|
|
194
195
|
set bubble placement [up-right] for bubble style [hero-dialogue]
|
|
195
196
|
set bubble distance [12] for bubble style [hero-dialogue]
|
|
196
197
|
set bubble visual style [NORMAL] for bubble style [hero-dialogue]
|
|
@@ -201,7 +202,7 @@ set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
|
|
|
201
202
|
<p><img src="./assets/placement-guide.svg" alt="Actor-relative 16-way and angle placement compared with three stage-relative placements"></p>
|
|
202
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>
|
|
203
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>
|
|
204
|
-
<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>
|
|
205
206
|
<pre><code class="language-text">up / up-up-right / up-right / right-up-right
|
|
206
207
|
right / right-down-right / down-right / down-down-right
|
|
207
208
|
down / down-down-left / down-left / left-down-left
|
|
@@ -280,7 +281,7 @@ set continue frames [Next1,Next2]
|
|
|
280
281
|
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
281
282
|
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
282
283
|
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
283
|
-
|
|
284
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
284
285
|
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
|
|
285
286
|
</code></pre>
|
|
286
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>
|
|
@@ -289,7 +290,7 @@ finish [CHARACTER] with condition [input == "pressed"] or timeout afte
|
|
|
289
290
|
<pre><code class="language-text">set runtime variable [input] to []
|
|
290
291
|
listen for key [Space] set runtime var [input] to [pressed]
|
|
291
292
|
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
292
|
-
|
|
293
|
+
show [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
293
294
|
wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
|
|
294
295
|
close this bubble
|
|
295
296
|
</code></pre>
|
|
@@ -343,11 +344,11 @@ explode this bubble relative scale [1.15] count [2] ease [easeOut]
|
|
|
343
344
|
animate bubble shape to [WAVY] speed [1] for [0.5] seconds
|
|
344
345
|
</code></pre>
|
|
345
346
|
<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>
|
|
346
|
-
<
|
|
347
|
-
<
|
|
348
|
-
|
|
347
|
+
<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>
|
|
348
|
+
<h2 id="reference">9. Showing a named Bubble style</h2>
|
|
349
|
+
<pre><code class="language-text">show [MESSAGE] with bubble style [STYLE]
|
|
349
350
|
</code></pre>
|
|
350
|
-
<p>
|
|
351
|
+
<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>
|
|
351
352
|
<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>
|
|
352
353
|
<h2 id="troubleshooting">10. Using Bubble with clones</h2>
|
|
353
354
|
<p>Bubble style definitions are shared within the extension, but each sprite or clone owns its currently displayed Bubble.</p>
|
|
@@ -356,7 +357,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
356
357
|
<li>Run <code>say</code> or <code>think</code> from each clone itself.</li>
|
|
357
358
|
<li>Change the animation mode and close the Bubble from the same clone that displayed it.</li>
|
|
358
359
|
</ol>
|
|
359
|
-
<p>When a clone stops or is deleted, timers,
|
|
360
|
+
<p>When a clone stops or is deleted, its timers, overlay DOM, and image leases are released automatically. Explicit <code>scratch-render</code> mode also releases skins and drawables.</p>
|
|
360
361
|
<h2 id="cleanup">11. Block reference</h2>
|
|
361
362
|
<table>
|
|
362
363
|
<thead>
|
|
@@ -379,7 +380,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
379
380
|
</tr>
|
|
380
381
|
<tr>
|
|
381
382
|
<td><code>set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]</code></td>
|
|
382
|
-
<td>Select one of ten SVG body
|
|
383
|
+
<td>Select one of ten inseparable SVG body + tail/trail pairs</td>
|
|
383
384
|
</tr>
|
|
384
385
|
<tr>
|
|
385
386
|
<td><code>set bubble tail length [LENGTH] for bubble style [STYLE]</code></td>
|
|
@@ -454,12 +455,16 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
454
455
|
<td>Transition the Bubble outline</td>
|
|
455
456
|
</tr>
|
|
456
457
|
<tr>
|
|
457
|
-
<td><code>say [MESSAGE]
|
|
458
|
-
<td>
|
|
458
|
+
<td><code>say [MESSAGE]</code></td>
|
|
459
|
+
<td>Show built-in style <code>say</code>: speech body and speech tail</td>
|
|
460
|
+
</tr>
|
|
461
|
+
<tr>
|
|
462
|
+
<td><code>think [MESSAGE]</code></td>
|
|
463
|
+
<td>Show built-in style <code>think</code>: thought body and round trail</td>
|
|
459
464
|
</tr>
|
|
460
465
|
<tr>
|
|
461
|
-
<td><code>
|
|
462
|
-
<td>
|
|
466
|
+
<td><code>show [MESSAGE] with bubble style [STYLE]</code></td>
|
|
467
|
+
<td>Show the complete body and tail/trail pair owned by a style</td>
|
|
463
468
|
</tr>
|
|
464
469
|
<tr>
|
|
465
470
|
<td><code>set this bubble animation mode [MODE]</code></td>
|
|
@@ -478,6 +483,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
478
483
|
<td>Report the Bubble implementation version</td>
|
|
479
484
|
</tr>
|
|
480
485
|
</tbody></table>
|
|
486
|
+
<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>
|
|
481
487
|
<h2 id="regeneration">12. Troubleshooting</h2>
|
|
482
488
|
<table>
|
|
483
489
|
<thead>
|
|
@@ -488,11 +494,11 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
488
494
|
</thead>
|
|
489
495
|
<tbody><tr>
|
|
490
496
|
<td>Asset Manager required error</td>
|
|
491
|
-
<td>Load Asset Manager 0.
|
|
497
|
+
<td>Load Asset Manager 0.12.x without sandbox before using image/media assets</td>
|
|
492
498
|
</tr>
|
|
493
499
|
<tr>
|
|
494
|
-
<td>
|
|
495
|
-
<td>
|
|
500
|
+
<td>SVG overlay backend error</td>
|
|
501
|
+
<td>Use a host with <code>renderer.addOverlay()</code> or explicitly select <code>scratch-render</code></td>
|
|
496
502
|
</tr>
|
|
497
503
|
<tr>
|
|
498
504
|
<td>Async Input required error</td>
|
|
@@ -504,7 +510,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
504
510
|
</tr>
|
|
505
511
|
<tr>
|
|
506
512
|
<td><code>bubble style is not defined</code></td>
|
|
507
|
-
<td>
|
|
513
|
+
<td>Use the built-in short say/think blocks, or define the named custom style first</td>
|
|
508
514
|
</tr>
|
|
509
515
|
<tr>
|
|
510
516
|
<td>Image asset is not registered</td>
|
|
@@ -536,7 +542,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
536
542
|
</tr>
|
|
537
543
|
</tbody></table>
|
|
538
544
|
<h2>13. Automatic cleanup</h2>
|
|
539
|
-
<p>Bubble automatically releases its owned timers, text skins
|
|
545
|
+
<p>Bubble automatically releases its owned timers, overlay DOM, and image leases in the following cases. Explicit <code>scratch-render</code> mode also releases its text skins and renderer drawables.</p>
|
|
540
546
|
<ul>
|
|
541
547
|
<li><code>close this bubble</code> runs;</li>
|
|
542
548
|
<li>the same sprite or clone runs another <code>say</code> or <code>think</code>;</li>
|
|
@@ -548,6 +554,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
548
554
|
<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>
|
|
549
555
|
<h2>14. Regenerating the manual assets</h2>
|
|
550
556
|
<p>The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick <code>magick</code> command.</p>
|
|
557
|
+
<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>
|
|
551
558
|
<pre><code class="language-sh">pnpm docs:render
|
|
552
559
|
pnpm docs:check
|
|
553
560
|
</code></pre>
|
package/docs/ja/index.html
CHANGED
|
@@ -69,9 +69,12 @@
|
|
|
69
69
|
<main id="manual" class="manual">
|
|
70
70
|
<h1>TurboWarp Bubble ブロック利用マニュアル</h1>
|
|
71
71
|
<p>このマニュアルでは、<code>turbowarp-bubble</code>をTurboWarpのカスタム拡張機能として使い、SVG本体、文字、キャラクター表情、目パチ、口パク、「次へ」アイコンを組み合わせたBubbleを表示します。</p>
|
|
72
|
+
<blockquote>
|
|
73
|
+
<p><strong>紙芝居DSL 4.0集約ランタイム:</strong> 集約ランタイムのパレットで<strong>Bubble</strong>見出し直下のドキュメントボタンを押すと、このマニュアルを開けます。集約されたブロックも、ここで説明するstyle、配置、portrait、逐次表示、音声、待機、animation、clone、自動解放の動作を保ち、拡張機能別の名前空間とBubbleアイコンで由来を識別できます。</p>
|
|
74
|
+
</blockquote>
|
|
72
75
|
<p><img src="../assets/block-quick-start.svg" alt="Next1とNext2を個別登録し、入力listenerを準備してBubble内蔵待機を使うブロック例"></p>
|
|
73
76
|
<h2 id="requirements">1. 必要な拡張機能</h2>
|
|
74
|
-
<p>入力待ちを含む完全な例では
|
|
77
|
+
<p>入力待ちを含む完全な例では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待機を使う場合だけ必要です。</p>
|
|
75
78
|
<table>
|
|
76
79
|
<thead>
|
|
77
80
|
<tr>
|
|
@@ -87,31 +90,26 @@
|
|
|
87
90
|
</tr>
|
|
88
91
|
<tr>
|
|
89
92
|
<td align="right">2</td>
|
|
90
|
-
<td>Async Input 0.
|
|
91
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.
|
|
93
|
+
<td>Async Input 0.4.0</td>
|
|
94
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js</code></td>
|
|
92
95
|
</tr>
|
|
93
96
|
<tr>
|
|
94
97
|
<td align="right">3</td>
|
|
95
|
-
<td>Runtime Expression 0.
|
|
96
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.
|
|
98
|
+
<td>Runtime Expression 0.4.0</td>
|
|
99
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js</code></td>
|
|
97
100
|
</tr>
|
|
98
101
|
<tr>
|
|
99
102
|
<td align="right">4</td>
|
|
100
|
-
<td>Asset Manager 0.
|
|
101
|
-
<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>
|
|
102
105
|
</tr>
|
|
103
106
|
<tr>
|
|
104
107
|
<td align="right">5</td>
|
|
105
|
-
<td>
|
|
106
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-
|
|
107
|
-
</tr>
|
|
108
|
-
<tr>
|
|
109
|
-
<td align="right">6</td>
|
|
110
|
-
<td>Bubble 0.7.0</td>
|
|
111
|
-
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.7.0/dist/turbowarp-bubble.js</code></td>
|
|
108
|
+
<td>Bubble 0.9.0</td>
|
|
109
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js</code></td>
|
|
112
110
|
</tr>
|
|
113
111
|
</tbody></table>
|
|
114
|
-
<p>開発中のBubbleを試す場合は、このリポジトリの<code>dist/turbowarp-bubble.js</code
|
|
112
|
+
<p>開発中のBubbleを試す場合は、このリポジトリの<code>dist/turbowarp-bubble.js</code>をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、待機開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。</p>
|
|
115
113
|
<p>参考:</p>
|
|
116
114
|
<ul>
|
|
117
115
|
<li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/ja/">Asset Manager 日本語ガイド</a></li>
|
|
@@ -176,21 +174,24 @@ register resource [costume:Assets:Next1] as asset [Next1]
|
|
|
176
174
|
register resource [costume:Assets:Next2] as asset [Next2]
|
|
177
175
|
</code></pre>
|
|
178
176
|
<p>URL画像を使う場合は、<code>RESOURCE_ID</code>へHTTPS URLを指定します。Bubbleに設定できるのは、Asset Managerへ登録済みでMIME typeが<code>image/*</code>のアセットだけです。</p>
|
|
179
|
-
<h2 id="text-style">3. 文字style
|
|
180
|
-
<p>SVG Text
|
|
181
|
-
<pre><code class="language-text">define
|
|
182
|
-
background [#fff4cc]
|
|
183
|
-
text [#332200]
|
|
184
|
-
font [Noto Sans JP]
|
|
185
|
-
size [100]
|
|
186
|
-
align [left]
|
|
187
|
-
bubble direction [up]
|
|
177
|
+
<h2 id="text-style">3. 文字layout styleを選ぶ</h2>
|
|
178
|
+
<p>standalone BubbleはSVG Text 0.8.1のlayout compositionを内包し、2つのBubble styleを組み込みます。<code>say</code>はspeech本体とspeech tail、<code>think</code>はthought本体とround trailを持ち、本体とtail/trailの形は別項目ではなく1つのvisual styleとして選びます。短い<code>say [MESSAGE]</code>/<code>think [MESSAGE]</code>ブロックが対応styleを自動選択するため、基本経路にはstyle定義もstyle入力も不要です。どちらも予約text profile <code>default</code>、内容に追従するサイズ、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が公開<code>getLayoutCapability()</code>を使い、SVG Text blockで定義したnamed styleを維持します。handoffのない古いSVG Textがロード済みならstyleを黙って置換せず互換errorを返し、必要な場合だけ文書化済みscratch-render fallbackを選択します。</p>
|
|
179
|
+
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
|
|
188
180
|
</code></pre>
|
|
189
|
-
<p>Bubble
|
|
190
|
-
<p>SVG Text 0.4.xは文字providerです。名前付き文字styleの定義、SVG文字skinの生成、文字幅の測定を担当します。Bubbleの配置は<code>set bubble placement</code>で設定し、tailや吹き出し外形はSVG Text providerの責務ではありません。</p>
|
|
181
|
+
<p>独自のfont、色、alignmentを使うアプリhostは、<code>createSvgTextLayoutComposition()</code>へstyleを定義し、<code>createSvgTextOverlayTextCapability()</code>でBubbleへ注入します。custom profileは同じ<code>layoutText()</code>を使い、既定overlay backendではSVG文字skinを生成しません。Bubbleの配置、tail、吹き出し外形はBubble側が担当します。</p>
|
|
191
182
|
<h2 id="bubble-style">4. Bubble styleを定義する</h2>
|
|
192
|
-
<p
|
|
193
|
-
<pre><code class="language-text">
|
|
183
|
+
<p>基本Bubbleでは短いブロックをそのまま使います。組み込みBubble style <code>say</code>/<code>think</code>がそれぞれ自動選択されます。</p>
|
|
184
|
+
<pre><code class="language-text">say [こんにちは!]
|
|
185
|
+
think [うーん…]
|
|
186
|
+
</code></pre>
|
|
187
|
+
<h3>TurboWarp標準との比較</h3>
|
|
188
|
+
<p>次の画像は、1つのTurboWarp Editor projectで英語UIを使い、<code>Cat</code> spriteを<code>x=-80</code>、<code>y=0</code>、サイズ<code>80%</code>、Stageを白背景、入力を<code>Hello!</code>/<code>Hmm...</code>に揃えて撮影した実画面です。左列はTurboWarp標準の見た目ブロックです。右列は対応する組み込み<code>say</code>/<code>think</code> styleを使うBubbleの短い基本ブロックで、定義ブロックもsetterも使っていません。</p>
|
|
189
|
+
<p><img src="../assets/turbowarp-say-think-stage-comparison.png" alt="TurboWarp標準のsay・think吹き出しとBubble基本profileを同じStageで比較した実画面"></p>
|
|
190
|
+
<p>Stage図では、右側配置、内容に追従する本体、Actor側へ向くspeech tail/thought trailを同じ条件で確認できます。Bubbleは独立したSVG surfaceを描画しており、全4panelとも実際のTurboWarp Stageを切り出したものです。</p>
|
|
191
|
+
<p><img src="../assets/turbowarp-say-think-block-comparison.png" alt="TurboWarp標準のsay・thinkブロックと、設定不要のBubble基本say・thinkブロックおよび組み込みdefault profile値を比較したスクリーンショット"></p>
|
|
192
|
+
<p>ブロック図は設定不要の基本経路と、custom style用の統合表示ブロックを示します。短いブロックは対応する組み込みstyleを自動選択します。calloutでは不可分な本体+tail/trailの組、両styleが使う予約text profile <code>default</code>、共通のfont、行高、幅、padding、角丸、色、border描画順、配置を示します。named custom styleには<code>show [MESSAGE] with bubble style [STYLE]</code>を使います。旧styled say/think opcodeは保存済みproject互換用の非表示定義として残します。</p>
|
|
193
|
+
<p>次のsetterを使うと、意図的にcustom profileへ切り替わります。</p>
|
|
194
|
+
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [default]
|
|
194
195
|
set bubble placement [up-right] for bubble style [hero-dialogue]
|
|
195
196
|
set bubble distance [12] for bubble style [hero-dialogue]
|
|
196
197
|
set bubble visual style [NORMAL] for bubble style [hero-dialogue]
|
|
@@ -201,7 +202,7 @@ set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
|
|
|
201
202
|
<p><img src="../assets/placement-guide.svg" alt="Actor相対の16方向・角度指定と、背景相対の3配置を比較する図"></p>
|
|
202
203
|
<p>Actor相対の16方向は、各方向をActor、Bubble外形、tail、文字を含む独立したミニシーンで示しています。三角形tailの基部2点は実際の本体border上にあり、本体polygonとのJSClipper union後の単一pathを描くため、接合部に内部border線は残りません。</p>
|
|
203
204
|
<p>背景相対3図はStage外枠、安全領域、Bubble外形寸法、水平中央線、基準辺/中心を示します。外形はBubble側の共有<code>renderBubbleSvg</code>で生成しており、TurboWarp Editorで本体drawableを生成するrendererと同じです。</p>
|
|
204
|
-
<p>Actor
|
|
205
|
+
<p>Actor相対placementはcustom profileへ適用され、Actor中心からBubble全体の中心へ向かう方向を指定します。未変更の基本profileはScratch標準の右側優先・自動左反転を使います。menuには次の16正規方向があります。</p>
|
|
205
206
|
<pre><code class="language-text">up / up-up-right / up-right / right-up-right
|
|
206
207
|
right / right-down-right / down-right / down-down-right
|
|
207
208
|
down / down-down-left / down-left / left-down-left
|
|
@@ -280,7 +281,7 @@ set continue frames [Next1,Next2]
|
|
|
280
281
|
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
281
282
|
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
282
283
|
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
283
|
-
|
|
284
|
+
show [海へ出発!] with bubble style [hero-dialogue]
|
|
284
285
|
finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
|
|
285
286
|
</code></pre>
|
|
286
287
|
<p><code>DYNAMIC</code>は表示単位ごとに吹き出しの大きさと配置を再計算し、<code>RESERVED</code>は最終的な文字量を先に計測して表示中の外形を予約します。<code>set bubble reveal sound</code>は単位ごと、<code>set bubble voice</code>は表示開始時にAsset Managerの名前付き音声を再生します。音声がなくても文字表示は利用できます。</p>
|
|
@@ -289,7 +290,7 @@ finish [CHARACTER] with condition [input == "pressed"] or timeout afte
|
|
|
289
290
|
<pre><code class="language-text">set runtime variable [input] to []
|
|
290
291
|
listen for key [Space] set runtime var [input] to [pressed]
|
|
291
292
|
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
292
|
-
|
|
293
|
+
show [海へ出発!] with bubble style [hero-dialogue]
|
|
293
294
|
wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
|
|
294
295
|
close this bubble
|
|
295
296
|
</code></pre>
|
|
@@ -343,11 +344,11 @@ explode this bubble relative scale [1.15] count [2] ease [easeOut]
|
|
|
343
344
|
animate bubble shape to [WAVY] speed [1] for [0.5] seconds
|
|
344
345
|
</code></pre>
|
|
345
346
|
<p>TurboWarp adapterはこれらをschedulerのフレームごとに進め、各フレームの進行率へ<code>ease</code>を適用します。<code>shake</code>は吹き出し全体を方向・回数付きで揺らし、<code>explode</code>はportraitと文字を含むsurface全体を拡大して元へ戻し、<code>animate bubble shape</code>は指定時間中に現在の外形から<code>THINKING</code>、<code>DREAMING</code>、<code>YELLING</code>、<code>WAVY</code>、<code>WHISPERING</code>などへcross-fadeします。仕様では、吹き出しが表示される時点を「表示開始」、隠れる時点を「表示終了」と呼びます。</p>
|
|
346
|
-
<
|
|
347
|
-
<
|
|
348
|
-
|
|
347
|
+
<p>表示中のBubbleを消すときは<code>close this bubble</code>を使います。設定済みの表示終了animationを実行してから、Bubbleのtimerと描画resourceを解放します。<code>set bubble hide animation ...</code>は終了時の演出を設定するだけで、このブロック自体はBubbleを消しません。組み込み基本profileでは、<code>say</code>/<code>think</code>へ空文字を渡してもTurboWarp標準と同様にcloseします。closeは非表示instanceを保持せず表示を破棄するため、別の<code>hide</code>ブロックは公開しません。</p>
|
|
348
|
+
<h2 id="reference">9. named Bubble styleを表示する</h2>
|
|
349
|
+
<pre><code class="language-text">show [MESSAGE] with bubble style [STYLE]
|
|
349
350
|
</code></pre>
|
|
350
|
-
<p
|
|
351
|
+
<p>選択したBubble styleが、本体とtail/trailの形を一体で決め、text profile、表情レイヤー、placement、animation設定も保持します。<code>set bubble visual style</code>は<code>NORMAL</code>(speech本体+speech tail)や<code>THINKING</code>(thought本体+round trail)のような不可分の組を選ぶブロックで、tail形状だけを独立して指定する設定はありません。standalone extensionは、表示ブロックに競合し得る別の種類を選ばせず、そのstyleから内部描画kindを導きます。</p>
|
|
351
352
|
<p>同じsprite、clone、またはStageで新しい<code>say</code>/<code>think</code>を実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。</p>
|
|
352
353
|
<h2 id="troubleshooting">10. cloneで使う</h2>
|
|
353
354
|
<p>Bubble styleの定義は拡張機能内で共有されますが、表示中のBubbleはsprite/cloneごとに所有されます。</p>
|
|
@@ -356,7 +357,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
356
357
|
<li>各clone自身から<code>say</code>または<code>think</code>を実行します。</li>
|
|
357
358
|
<li>animation mode変更とcloseも、表示したのと同じcloneから実行します。</li>
|
|
358
359
|
</ol>
|
|
359
|
-
<p>cloneが停止・削除された場合は、そのtargetに属するtimer、
|
|
360
|
+
<p>cloneが停止・削除された場合は、そのtargetに属するtimer、overlay DOM、画像leaseが自動解放されます。明示的な<code>scratch-render</code>ではskinとdrawableも解放されます。</p>
|
|
360
361
|
<h2 id="cleanup">11. ブロック一覧</h2>
|
|
361
362
|
<table>
|
|
362
363
|
<thead>
|
|
@@ -379,7 +380,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
379
380
|
</tr>
|
|
380
381
|
<tr>
|
|
381
382
|
<td><code>set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]</code></td>
|
|
382
|
-
<td
|
|
383
|
+
<td>不可分なSVG本体+tail/trailの組を10種類から設定する</td>
|
|
383
384
|
</tr>
|
|
384
385
|
<tr>
|
|
385
386
|
<td><code>set bubble tail length [LENGTH] for bubble style [STYLE]</code></td>
|
|
@@ -454,12 +455,16 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
454
455
|
<td>Bubble外形を時間経過で切り替える</td>
|
|
455
456
|
</tr>
|
|
456
457
|
<tr>
|
|
457
|
-
<td><code>say [MESSAGE]
|
|
458
|
-
<td
|
|
458
|
+
<td><code>say [MESSAGE]</code></td>
|
|
459
|
+
<td>組み込み<code>say</code> styleのspeech本体+tailを表示する</td>
|
|
460
|
+
</tr>
|
|
461
|
+
<tr>
|
|
462
|
+
<td><code>think [MESSAGE]</code></td>
|
|
463
|
+
<td>組み込み<code>think</code> styleのthought本体+round trailを表示する</td>
|
|
459
464
|
</tr>
|
|
460
465
|
<tr>
|
|
461
|
-
<td><code>
|
|
462
|
-
<td
|
|
466
|
+
<td><code>show [MESSAGE] with bubble style [STYLE]</code></td>
|
|
467
|
+
<td>styleが持つ本体+tail/trailの一組を表示する</td>
|
|
463
468
|
</tr>
|
|
464
469
|
<tr>
|
|
465
470
|
<td><code>set this bubble animation mode [MODE]</code></td>
|
|
@@ -478,6 +483,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
478
483
|
<td>Bubble実装versionを返す</td>
|
|
479
484
|
</tr>
|
|
480
485
|
</tbody></table>
|
|
486
|
+
<p>旧<code>say/think [MESSAGE] with bubble style [STYLE]</code> opcodeを使う保存済みprojectは引き続き動作しますが、この互換ブロック2個はpaletteに表示しません。新しいscriptでは統合<code>show</code>ブロックを使い、選択styleだけで本体とtail/trailの形を決めます。</p>
|
|
481
487
|
<h2 id="regeneration">12. よくあるエラー</h2>
|
|
482
488
|
<table>
|
|
483
489
|
<thead>
|
|
@@ -488,11 +494,11 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
488
494
|
</thead>
|
|
489
495
|
<tbody><tr>
|
|
490
496
|
<td>Asset Managerを要求するエラー</td>
|
|
491
|
-
<td>画像・メディアアセットを使う前にAsset Manager 0.
|
|
497
|
+
<td>画像・メディアアセットを使う前にAsset Manager 0.12.xを読み込む</td>
|
|
492
498
|
</tr>
|
|
493
499
|
<tr>
|
|
494
|
-
<td
|
|
495
|
-
<td>
|
|
500
|
+
<td>SVG overlay backendのエラー</td>
|
|
501
|
+
<td><code>renderer.addOverlay()</code>対応hostを使うか<code>scratch-render</code>を明示する</td>
|
|
496
502
|
</tr>
|
|
497
503
|
<tr>
|
|
498
504
|
<td>Async Inputを要求するエラー</td>
|
|
@@ -504,7 +510,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
504
510
|
</tr>
|
|
505
511
|
<tr>
|
|
506
512
|
<td><code>bubble style is not defined</code></td>
|
|
507
|
-
<td
|
|
513
|
+
<td>組み込みの短いsay/thinkを使うか、named custom styleを先に定義する</td>
|
|
508
514
|
</tr>
|
|
509
515
|
<tr>
|
|
510
516
|
<td>image assetが未登録</td>
|
|
@@ -536,7 +542,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
536
542
|
</tr>
|
|
537
543
|
</tbody></table>
|
|
538
544
|
<h2>13. 自動解放されるタイミング</h2>
|
|
539
|
-
<p>次の場合、Bubbleが所有するtimer、text skin
|
|
545
|
+
<p>次の場合、Bubbleが所有するtimer、overlay DOM、画像leaseは自動的に解放されます。<code>scratch-render</code>を明示した場合はtext skinとrenderer drawableも解放されます。</p>
|
|
540
546
|
<ul>
|
|
541
547
|
<li><code>close this bubble</code></li>
|
|
542
548
|
<li>同じsprite/cloneで次の<code>say</code>または<code>think</code>を実行したとき</li>
|
|
@@ -548,6 +554,7 @@ think [MESSAGE] with bubble style [STYLE]
|
|
|
548
554
|
<p>Asset Managerへ登録したアセット自体はBubbleの所有物ではありません。不要になった登録画像をメモリから削除する場合は、Bubbleを閉じた後にAsset Managerの<code>delete asset [NAME] from memory</code>を使います。</p>
|
|
549
555
|
<h2>14. マニュアル画像の再生成</h2>
|
|
550
556
|
<p>図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickの<code>magick</code>コマンドが必要です。</p>
|
|
557
|
+
<p>2つの<code>turbowarp-say-think-*-comparison.png</code>はrenderer previewから生成した図ではなく、TurboWarp Editorの実画面です。第4章に記載した撮影条件を使い、<code>docs:render</code>では上書きしません。</p>
|
|
551
558
|
<pre><code class="language-sh">pnpm docs:render
|
|
552
559
|
pnpm docs:check
|
|
553
560
|
</code></pre>
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# 0.8.0: default SVG overlay backend
|
|
2
|
+
|
|
3
|
+
## 追加内容
|
|
4
|
+
|
|
5
|
+
- `bubbleRenderBackend`の既定値を`"svg-overlay"`へ変更する。
|
|
6
|
+
- `"scratch-render"`は明示指定できるrollback backendとして保持する。
|
|
7
|
+
- `renderer.addOverlay(root, "scale")`上の共有SVG rootにBubble surfaceを描画する。
|
|
8
|
+
- host-neutralな`svgOverlayTextCapability`と、解放可能な`svgOverlayImageCapability`を公開する。
|
|
9
|
+
- SVG Text 0.8.1を通常dependencyとし、standalone拡張がない場合は`createSvgTextLayoutComposition().layoutText()`、ロード済みの場合は公開`getLayoutCapability()`から同じnamed-style registryの行layoutを変換する。
|
|
10
|
+
- handoffのない古いstandalone SVG Textが存在する場合、named styleを既定値へ黙って置換せず、明示errorまたは設定済みscratch-render fallbackを使う。
|
|
11
|
+
- Bubble側の`createAssetManagerSvgOverlayImageCapability()`でAsset Managerの汎用DOM resourceを変換する。依存方向はBubbleからAsset Managerへの一方向を維持する。
|
|
12
|
+
- stock Asset Manager 0.12.1を別拡張として読み込んだ場合、Bubbleが公開`getDOMImageCapability()`を遅延取得し、Asset Managerブロックで登録された同じregistryへ自動接続する。
|
|
13
|
+
- overlay API未対応hostは`BUBBLE-RUNTIME-004`を返す。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ既存backendへ戻る。
|
|
14
|
+
|
|
15
|
+
## 自動検証結果
|
|
16
|
+
|
|
17
|
+
2026-08-19時点のunit testでは、次を合格条件としている。
|
|
18
|
+
|
|
19
|
+
- optionsを省略した既定経路でshow、text更新、shake、shape animationを行っても、Bubbleから`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばない(許容値: 0回)。
|
|
20
|
+
- 2つのBubbleが1つのrootを共有し、最後のclose後に`removeOverlay()`を1回呼ぶ(許容値: 残存root 0、重複remove 0)。
|
|
21
|
+
- native size変更後にrootの`viewBox`を同期し、現在表示中のtextと`RESERVED`全文layoutを再計算する。
|
|
22
|
+
- `script`、event handler、`foreignObject`、未許可data URLを拒否する。
|
|
23
|
+
- capability所有のblob URLをreplacement/close時に各1回解放する。
|
|
24
|
+
- renderer cleanupが失敗した場合も、残りのlistener、DOM、image leaseの解放を継続してerrorを集約する。
|
|
25
|
+
- Asset Managerのsanitize済みSVG resourceをBubble側adapter経由で描画し、close時にleaseを1回解放する。
|
|
26
|
+
- SVG Textのhost-neutral layoutをBubble側adapterで変換し、renderer skinを生成せず行座標を維持する。stock named styleの再定義後は、同じ公開handoffから次回layoutへ新しいfont、color、size、alignment、改行layoutを反映する。
|
|
27
|
+
|
|
28
|
+
## Web smoke結果
|
|
29
|
+
|
|
30
|
+
2026-08-20にcommit `9b01605`からbuildしたrelease候補の`dist/turbowarp-bubble.js`を、TurboWarp Webのカスタム拡張機能へtext入力し、unsandboxedで読み込んだ。Chrome/macOSで`define bubble style`、say/think、style/reveal/animation/closeの各blockを実行した結果は次のとおり。
|
|
31
|
+
|
|
32
|
+
- Bubble paletteが登録され、sprite上方に`NORMAL`のsay bubbleが表示された。
|
|
33
|
+
- `[data-bubble-render-backend="svg-overlay"]`は1個で、DOMへ接続済みだった。
|
|
34
|
+
- rootは`viewBox="0 0 480 360"`、属性上の幅・高さとCSS上の表示領域はいずれも480×360だった。
|
|
35
|
+
- `NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`の全10styleを表示した。`THINKING`はbody `path` 1個とtrail `circle` 2個、`DREAMING`は`circle` 3個、`NO_BUBBLE`はbodyを非表示にしてtextだけを維持した。
|
|
36
|
+
- short textの`THINKING`/`DREAMING`で固定Bezier制御点が自己交差する問題をこの確認で検出した。cloud bodyへ176×96の最小viewportと比例制御点によるclosed splineを導入し、修正版で滑らかな輪郭を再確認した。
|
|
37
|
+
- root内の`script`、`foreignObject`、inline event handlerは0個だった。
|
|
38
|
+
- 初回登録時に検出したTurboWarp VMの`Unexpected input recieved in replaceUnsafeChars`は、`color2`/`color3`の明示後のrelease候補bundleでは再現せず、extension登録から全smoke終了まで新規warning/errorは0件だった。
|
|
39
|
+
- revealを`CHARACTER`、0.05秒に設定したsayは`H`、`Hello`、`Hello!`の順に進み、Chromiumのreadback、`Silhouette.unlazy()`、`getImageData()`関連warningは0件だった。
|
|
40
|
+
- shake中はsurface transformが変化して終了時に基準位置へ戻り、shape animationは`NORMAL`から`WAVY`へ完了した。close後はrootが0個となり、再度sayするとroot 1個へ復帰した。
|
|
41
|
+
|
|
42
|
+
stageはnative 480×360、small表示240×180、fullscreen表示3152×2364、custom native 640×480で確認した。各表示でrootの属性と`viewBox`はnative sizeに一致し、CSS表示領域はhostの拡大縮小へ追随した。sprite相対配置に加え、Stage targetの`HEADER_LIKE`も640×480上端のsafe area内へ表示された。最後に480×360、sprite相対`NORMAL`へ戻した。
|
|
43
|
+
|
|
44
|
+
## Desktop smoke結果
|
|
45
|
+
|
|
46
|
+
2026-08-20にTurboWarp Desktop 1.16.0へ同じrelease候補をtext入力し、unsandboxedで読み込んだ。実アプリのsprite/Stage targetとVM primitiveを使って確認した結果は次のとおり。
|
|
47
|
+
|
|
48
|
+
- Bubble paletteと全28 primitiveが登録され、say/thinkと全10 visual styleが表示された。short textの`THINKING`は176×96・trail `circle` 2個、`DREAMING`は176×96・`circle` 3個だった。
|
|
49
|
+
- revealは`H`、`Hell`、`Hello!`の順に進んだ。shakeはsurface transformを変化させて基準位置へ戻り、shape animationは`NORMAL`から`WAVY`へ完了した。
|
|
50
|
+
- native 480×360、small表示240×180、fullscreen表示955×716、custom native 640×480でrootがstageへ追随した。sprite相対配置とStage targetの`HEADER_LIKE`を確認した。
|
|
51
|
+
- spriteとStageの2 surfaceを同時表示した後、Stageのcloseで1 surface、spriteのcloseでroot 0となった。
|
|
52
|
+
- 正しいstage sizeを設定して再実行した区間では、consoleのwarning/errorは0件だった。最後にstageを480×360へ戻し、root 0を確認した。
|
|
53
|
+
|
|
54
|
+
## Packager smoke結果
|
|
55
|
+
|
|
56
|
+
2026-08-20にTurboWarp Packager Standalone 3.13.0で、Bubble blockを含むDesktopプロジェクトからプレーンHTMLのpreviewを生成した。Packagerの高度な設定ではrelease候補のdata URLがcustom extensionとして検出され、cached copyの埋め込みが有効だった。生成playerではBubbleの全28 primitiveがロードされた。
|
|
57
|
+
|
|
58
|
+
- sayで全10 visual styleを表示し、明示したthinkでもshort `DREAMING`が176×96・trail `circle` 3個となった。short `THINKING`は176×96・`circle` 2個だった。
|
|
59
|
+
- revealは`H`、`Hel`、`Hello!`の順に進んだ。`zoomIn`はscale 0.01から1へ完了し、shakeは位置を変化させて基準位置へ戻り、shape animationは`WAVY`へ完了した。
|
|
60
|
+
- sprite相対配置に加え、Stage targetの`HEADER_LIKE`をnative 480×360のsafe area内で確認した。
|
|
61
|
+
- Bubble表示中にcanvasの`toDataURL()`はPNG data URLを返し、`captureStream()`はvideo trackを1本返した。Bubble rootはcanvasの子ではなく、隣接する`.scratch-render-overlays`内にあるため、両APIにBubbleが含まれない既知制約を確認した。
|
|
62
|
+
- show/replace/closeを100回実行した後、Bubble root、surface、overlay childは0で、runtime listener数の増分も0だった。
|
|
63
|
+
- 全smoke終了までconsoleのwarning/errorは0件だった。
|
|
64
|
+
|
|
65
|
+
## deterministic benchmark結果
|
|
66
|
+
|
|
67
|
+
`pnpm benchmark:render-backends`は、happy-dom上の同一fake rendererと決定的schedulerを使い、`svg-overlay`とrollback用`scratch-render`を同じ入力で比較する。2026-08-20にNode.js v26.7.0/arm64 macOSで実行した代表値は次のとおり。
|
|
68
|
+
|
|
69
|
+
| workload | svg-overlay | scratch-render | 判定 |
|
|
70
|
+
| ---------------------------------------------- | ---------------------------------------- | ---------------------------------------- | ----------------------------------- |
|
|
71
|
+
| typewriter、1,000回 | 62.254 ms、skin/drawable生成0 | 8.720 ms、skin 1,002、drawable 2 | overlayのrenderer resource生成0 |
|
|
72
|
+
| shape/shake/zoom、各10秒・合計1,875 callback | callback超過0%、p95 0.352 ms | callback超過0%、p95 0.157 ms | 差0 percentage points、許容値+5以内 |
|
|
73
|
+
| show/text・style更新/close、100回 | DOM/listener/skin/drawable残存すべて0 | DOM/listener/skin/drawable残存すべて0 | lifecycle residual 0 |
|
|
74
|
+
|
|
75
|
+
このbenchmarkが測るのはJavaScript callbackのCPU時間、renderer API呼び出し数、明示resourceの解放である。実browserのlayout/paint/composite、GC後の保持heap、host固有のframe dropを代替しない。数値は環境と実行ごとに変動するため、release判定ではresource残存とpercentage-point基準を主要判定値とする。
|
|
76
|
+
|
|
77
|
+
## release前のmanual gate
|
|
78
|
+
|
|
79
|
+
上流の[turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26)で公開されたhost-neutral layoutを0.8.0の通常dependencyとして採用する。[turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103)のDOM image resourceをBubble所有adapterで変換し、stock拡張間のhandoffには[turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106)で公開された0.12.1 APIを使う。既定値変更後も次のmanual gateをrelease前に実施し、実測値をこの表へ記録する。
|
|
80
|
+
|
|
81
|
+
| 項目 | host | 許容基準 | 結果 |
|
|
82
|
+
| -------------------------- | ------------------------------------ | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
|
83
|
+
| say/think、全visual style | Web、Desktop、Packager | reference screenshotの主要geometry差異なし | 3 hostでsay/thinkと全10styleを確認。short cloudの最小寸法とtrail数も一致 |
|
|
84
|
+
| actor/background配置 | native 480×360と変更size、fullscreen | stage外clip、tail方向、centerに回帰なし | Web/Desktopで480×360、small、fullscreen、640×480、Packagerで480×360のactor/backgroundを確認 |
|
|
85
|
+
| typewriter | 1,000 update | Chromium readback警告0、`Silhouette.unlazy()`増分0 | harnessで1,000 updateとresource生成0。3 hostの実revealで関連warning 0 |
|
|
86
|
+
| shape/shake/zoom | 各10秒 | dropped frame率が既存backend比+5 percentage points以内 | harnessで各10秒・0%対0%、差0 points。Web/Desktopでshape/shake、Packagerでshape/shake/zoomをsmoke済み |
|
|
87
|
+
| memory/lifecycle | show/replace/stopを100回 | close後のBubble DOM、object URL、animation、listener残存0 | harnessの全resource残存0。Packager実hostの100回後にDOM、surface、overlay child、listener増分0 |
|
|
88
|
+
| raw canvas capture | `toDataURL()`、`captureStream()` | Bubbleが含まれない既知制約を確認 | Packagerで両APIの成功と、Bubble rootがcanvas外のsibling overlayにあることを確認 |
|
|
89
|
+
|
|
90
|
+
## capture制約
|
|
91
|
+
|
|
92
|
+
SVG overlayはbrowser/OSの最終compositeには含まれるが、WebGL canvasだけを取得する`renderer.canvas.toDataURL()`、`toBlob()`、`captureStream()`には含まれない。初期実装では専用compositorを提供しない。
|
|
93
|
+
|
|
94
|
+
## rollback
|
|
95
|
+
|
|
96
|
+
設定へ`bubbleRenderBackend: "scratch-render"`を明示する。公開済みの設定値と既存backendは削除せず、重大なhost回帰がある場合は明示errorまたはpatch releaseで対処する。暗黙fallbackは行わないため、rollbackはhost側で確認できる。
|