@kubohiroya/turbowarp-bubble 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +8 -0
- package/README.md +293 -0
- package/THIRD_PARTY_NOTICES.md +123 -0
- package/dist/composition.js +4317 -0
- package/dist/extension-manifest.json +245 -0
- package/dist/turbowarp-adapter.js +3977 -0
- package/dist/turbowarp-bubble.js +7887 -0
- package/dist/types/actor-transform.d.ts +36 -0
- package/dist/types/bubble-svg.d.ts +36 -0
- package/dist/types/composition.d.ts +121 -0
- package/dist/types/placement.d.ts +24 -0
- package/dist/types/text-layout.d.ts +42 -0
- package/dist/types/turbowarp-adapter.d.ts +69 -0
- package/docs/.nojekyll +1 -0
- package/docs/assets/actor-transform-guide.svg +68 -0
- package/docs/assets/animation-mode-guide.svg +126 -0
- package/docs/assets/block-quick-start.svg +230 -0
- package/docs/assets/bubble-lifecycle.gif +0 -0
- package/docs/assets/bubble-style-gallery.svg +138 -0
- package/docs/assets/placement-guide.svg +292 -0
- package/docs/assets/width-linebreak-guide.svg +99 -0
- package/docs/block-manual.ja.md +292 -0
- package/docs/block-manual.md +292 -0
- package/docs/index.html +486 -0
- package/docs/ja/index.html +486 -0
- package/package.json +104 -0
package/docs/index.html
ADDED
|
@@ -0,0 +1,486 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="utf-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
6
|
+
<meta name="description" content="Block manual for TurboWarp Bubble, including shapes, placement, portraits, blinking, lip-sync, and the animated advance indicator.">
|
|
7
|
+
<title>TurboWarp Bubble Block Manual</title>
|
|
8
|
+
<style>
|
|
9
|
+
:root { color-scheme: light dark; --ink: #25283a; --muted: #667085; --accent: #d94b68; --accent-strong: #b83255; --accent-soft: #fff0f4; --line: #d9deea; --panel: #fff; --page: #f2f4f8; --code: #25283a; }
|
|
10
|
+
@media (prefers-color-scheme: dark) { :root { --ink: #f7edf1; --muted: #c8bcc2; --accent: #ff8ca3; --accent-strong: #ffb2c1; --accent-soft: #48252f; --line: #50434a; --panel: #211c20; --page: #151215; --code: #100d10; } }
|
|
11
|
+
* { box-sizing: border-box; }
|
|
12
|
+
html { scroll-behavior: smooth; scroll-padding-top: 6rem; }
|
|
13
|
+
body { margin: 0; color: var(--ink); background: radial-gradient(circle at 12% 0%, color-mix(in srgb, var(--accent) 12%, transparent), transparent 28rem), var(--page); font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", "Hiragino Sans", "Noto Sans JP", sans-serif; line-height: 1.75; }
|
|
14
|
+
a { color: var(--accent-strong); text-underline-offset: .18em; }
|
|
15
|
+
a:focus-visible { outline: 3px solid var(--accent); outline-offset: 3px; border-radius: .2rem; }
|
|
16
|
+
.skip-link { position: absolute; top: -5rem; left: 1rem; z-index: 20; padding: .65rem .9rem; color: var(--ink); background: var(--panel); border-radius: .5rem; }
|
|
17
|
+
.skip-link:focus { top: 1rem; }
|
|
18
|
+
.site-header { position: sticky; top: 0; z-index: 10; border-bottom: 1px solid color-mix(in srgb, var(--line) 80%, transparent); background: color-mix(in srgb, var(--page) 86%, transparent); backdrop-filter: blur(16px); box-shadow: 0 2px 10px #25283a14; }
|
|
19
|
+
.header-inner { display: flex; width: min(70rem, calc(100% - 2rem)); min-height: 4.25rem; margin-inline: auto; align-items: center; gap: 1rem; }
|
|
20
|
+
.brand { display: inline-flex; align-items: center; gap: .65rem; color: var(--ink); font-weight: 800; text-decoration: none; white-space: nowrap; }
|
|
21
|
+
.brand-mark { display: grid; width: 2rem; height: 2rem; place-items: center; color: #fff; background: linear-gradient(145deg, #ff6680, #b83255); border-radius: .7rem .7rem .7rem .25rem; box-shadow: 0 7px 18px #b8325559; }
|
|
22
|
+
.primary-nav { display: flex; align-items: center; gap: 1rem; margin-left: auto; font-size: .9rem; }
|
|
23
|
+
.primary-nav a, .github-link { color: var(--muted); text-decoration: none; }
|
|
24
|
+
.primary-nav a:hover, .github-link:hover { color: var(--ink); }
|
|
25
|
+
.github-link { padding: .38rem .55rem; border-radius: .6rem; font-size: .84rem; font-weight: 750; }
|
|
26
|
+
.language-switch { display: inline-flex; flex: 0 0 auto; padding: .2rem; border: 1px solid var(--line); border-radius: 99rem; background: var(--panel); white-space: nowrap; }
|
|
27
|
+
.language-switch a { padding: .26rem .58rem; border-radius: 99rem; color: var(--muted); font-size: .82rem; font-weight: 750; text-decoration: none; }
|
|
28
|
+
.language-switch a[aria-current="page"] { color: var(--ink); background: var(--accent-soft); }
|
|
29
|
+
.manual { width: min(1080px, calc(100% - 2rem)); margin: 2rem auto 4rem; padding: clamp(1rem, 4vw, 3.5rem); background: var(--panel); border: 1px solid var(--line); border-radius: 20px; box-shadow: 0 12px 36px #25283a12; }
|
|
30
|
+
h1, h2, h3 { line-height: 1.35; scroll-margin-top: 5rem; }
|
|
31
|
+
h1 { margin-top: 0; font-size: clamp(1.9rem, 4vw, 2.8rem); }
|
|
32
|
+
h2 { margin-top: 2.8rem; padding-bottom: .4rem; border-bottom: 2px solid var(--accent); font-size: clamp(1.45rem, 3vw, 2rem); }
|
|
33
|
+
h3 { margin-top: 2rem; font-size: 1.25rem; }
|
|
34
|
+
img { display: block; max-width: 100%; height: auto; margin: 1.5rem auto; border-radius: 12px; }
|
|
35
|
+
table { display: block; width: 100%; overflow-x: auto; border-collapse: collapse; margin: 1.2rem 0; }
|
|
36
|
+
th, td { padding: .65rem .8rem; border: 1px solid var(--line); text-align: left; vertical-align: top; }
|
|
37
|
+
th { background: var(--accent-soft); }
|
|
38
|
+
pre { overflow-x: auto; padding: 1rem 1.1rem; color: #f8fafc; background: var(--code); border-radius: 12px; line-height: 1.55; }
|
|
39
|
+
code { padding: .12em .35em; background: var(--accent-soft); border-radius: 5px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .92em; }
|
|
40
|
+
pre code { padding: 0; color: inherit; background: transparent; }
|
|
41
|
+
blockquote { margin-left: 0; padding: .25rem 1rem; color: var(--muted); border-left: 4px solid var(--accent); }
|
|
42
|
+
.site-footer { padding: 0 1rem 3rem; color: var(--muted); text-align: center; font-size: .9rem; }
|
|
43
|
+
@media (max-width: 850px) { .primary-nav { display: none; } .github-link { margin-left: auto; } }
|
|
44
|
+
@media (max-width: 620px) { .brand-text { display: none; } .header-inner { gap: .4rem; } .github-link { padding-inline: .3rem; } .language-switch a { padding-inline: .45rem; } .manual { width: 100%; margin-top: 0; border-width: 0; border-radius: 0; box-shadow: none; } }
|
|
45
|
+
@media print { .site-header, .skip-link { display: none; } body { background: #fff; } }
|
|
46
|
+
</style>
|
|
47
|
+
</head>
|
|
48
|
+
<body>
|
|
49
|
+
<a class="skip-link" href="#manual">Skip to the manual</a>
|
|
50
|
+
<header class="site-header">
|
|
51
|
+
<div class="header-inner">
|
|
52
|
+
<a class="brand" href="./" aria-label="Bubble manual home">
|
|
53
|
+
<span class="brand-mark" aria-hidden="true">B</span>
|
|
54
|
+
<span class="brand-text">TurboWarp Bubble</span>
|
|
55
|
+
</a>
|
|
56
|
+
<nav class="primary-nav" aria-label="Manual sections">
|
|
57
|
+
<a href="#requirements">Get started</a>
|
|
58
|
+
<a href="#bubble-style">Styles</a>
|
|
59
|
+
<a href="#lifecycle">Display & wait</a>
|
|
60
|
+
<a href="#reference">Block reference</a>
|
|
61
|
+
</nav>
|
|
62
|
+
<a class="github-link" href="https://github.com/kubohiroya/turbowarp-bubble">GitHub</a>
|
|
63
|
+
<nav class="language-switch" aria-label="Language">
|
|
64
|
+
<a href="./" lang="en" hreflang="en" aria-current="page">English</a>
|
|
65
|
+
<a href="./ja/" lang="ja" hreflang="ja">日本語</a>
|
|
66
|
+
</nav>
|
|
67
|
+
</div>
|
|
68
|
+
</header>
|
|
69
|
+
<main id="manual" class="manual">
|
|
70
|
+
<h1>TurboWarp Bubble Block Manual</h1>
|
|
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 advance indicator.</p>
|
|
72
|
+
<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
|
+
<h2 id="requirements">1. Load the required extensions</h2>
|
|
74
|
+
<p>The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the five custom extensions with <strong>Run without sandbox</strong> enabled. Async Input and Runtime Expression must be available before a Bubble wait; Asset Manager and SVG Text must be available before the first Bubble is shown.</p>
|
|
75
|
+
<table>
|
|
76
|
+
<thead>
|
|
77
|
+
<tr>
|
|
78
|
+
<th align="right">Order</th>
|
|
79
|
+
<th>Extension</th>
|
|
80
|
+
<th>URL</th>
|
|
81
|
+
</tr>
|
|
82
|
+
</thead>
|
|
83
|
+
<tbody><tr>
|
|
84
|
+
<td align="right">1</td>
|
|
85
|
+
<td>Temporary Variables</td>
|
|
86
|
+
<td>Add from the TurboWarp extension library</td>
|
|
87
|
+
</tr>
|
|
88
|
+
<tr>
|
|
89
|
+
<td align="right">2</td>
|
|
90
|
+
<td>Async Input 0.3.0</td>
|
|
91
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js</code></td>
|
|
92
|
+
</tr>
|
|
93
|
+
<tr>
|
|
94
|
+
<td align="right">3</td>
|
|
95
|
+
<td>Runtime Expression 0.3.0</td>
|
|
96
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js</code></td>
|
|
97
|
+
</tr>
|
|
98
|
+
<tr>
|
|
99
|
+
<td align="right">4</td>
|
|
100
|
+
<td>Asset Manager 0.7.0</td>
|
|
101
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js</code></td>
|
|
102
|
+
</tr>
|
|
103
|
+
<tr>
|
|
104
|
+
<td align="right">5</td>
|
|
105
|
+
<td>SVG Text 0.3.0</td>
|
|
106
|
+
<td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.3.0/dist/svg-text.js</code></td>
|
|
107
|
+
</tr>
|
|
108
|
+
<tr>
|
|
109
|
+
<td align="right">6</td>
|
|
110
|
+
<td>Bubble 0.1.0</td>
|
|
111
|
+
<td>After npm publication: <code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.1.0/dist/turbowarp-bubble.js</code></td>
|
|
112
|
+
</tr>
|
|
113
|
+
</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 Asset Manager or SVG Text is missing when it displays a Bubble, or if Async Input or Runtime Expression is missing when it starts a Bubble wait.</p>
|
|
115
|
+
<p>See also:</p>
|
|
116
|
+
<ul>
|
|
117
|
+
<li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/">Asset Manager guide</a></li>
|
|
118
|
+
<li><a href="https://kubohiroya.github.io/turbowarp-async-input/">Async Input guide</a></li>
|
|
119
|
+
<li><a href="https://kubohiroya.github.io/turbowarp-runtime-expression/">Runtime Expression guide</a></li>
|
|
120
|
+
<li><a href="https://kubohiroya.github.io/turbowarp-svg-text/">SVG Text guide</a></li>
|
|
121
|
+
</ul>
|
|
122
|
+
<h2 id="portrait">2. Prepare portrait assets</h2>
|
|
123
|
+
<p>The following example stores costumes in a hidden asset sprite named <code>Assets</code>.</p>
|
|
124
|
+
<table>
|
|
125
|
+
<thead>
|
|
126
|
+
<tr>
|
|
127
|
+
<th>Costume</th>
|
|
128
|
+
<th>Asset Manager name</th>
|
|
129
|
+
<th>Contents</th>
|
|
130
|
+
</tr>
|
|
131
|
+
</thead>
|
|
132
|
+
<tbody><tr>
|
|
133
|
+
<td><code>HeroFace</code></td>
|
|
134
|
+
<td><code>HeroFace</code></td>
|
|
135
|
+
<td>Face, hair, and outline, excluding the animated eyes/mouth</td>
|
|
136
|
+
</tr>
|
|
137
|
+
<tr>
|
|
138
|
+
<td><code>HeroEyesOpen</code></td>
|
|
139
|
+
<td><code>HeroEyesOpen</code></td>
|
|
140
|
+
<td>Transparent overlay containing only the open eyes</td>
|
|
141
|
+
</tr>
|
|
142
|
+
<tr>
|
|
143
|
+
<td><code>HeroEyesClosed</code></td>
|
|
144
|
+
<td><code>HeroEyesClosed</code></td>
|
|
145
|
+
<td>Transparent overlay containing only the closed eyes</td>
|
|
146
|
+
</tr>
|
|
147
|
+
<tr>
|
|
148
|
+
<td><code>HeroMouthClosed</code></td>
|
|
149
|
+
<td><code>HeroMouthClosed</code></td>
|
|
150
|
+
<td>Transparent overlay containing only the closed mouth</td>
|
|
151
|
+
</tr>
|
|
152
|
+
<tr>
|
|
153
|
+
<td><code>HeroMouthOpen</code></td>
|
|
154
|
+
<td><code>HeroMouthOpen</code></td>
|
|
155
|
+
<td>Transparent overlay containing only the open mouth</td>
|
|
156
|
+
</tr>
|
|
157
|
+
<tr>
|
|
158
|
+
<td><code>Next1</code></td>
|
|
159
|
+
<td><code>Next1</code></td>
|
|
160
|
+
<td>First frame of the advance indicator</td>
|
|
161
|
+
</tr>
|
|
162
|
+
<tr>
|
|
163
|
+
<td><code>Next2</code></td>
|
|
164
|
+
<td><code>Next2</code></td>
|
|
165
|
+
<td>Second frame of the advance indicator</td>
|
|
166
|
+
</tr>
|
|
167
|
+
</tbody></table>
|
|
168
|
+
<p>Use the same canvas size and center point for the base, eye, and mouth images. Keep overlay backgrounds transparent; mismatched canvases or centers make the layers drift when composed.</p>
|
|
169
|
+
<p>Register each costume with Asset Manager:</p>
|
|
170
|
+
<pre><code class="language-text">register resource [costume:Assets:HeroFace] as asset [HeroFace]
|
|
171
|
+
register resource [costume:Assets:HeroEyesOpen] as asset [HeroEyesOpen]
|
|
172
|
+
register resource [costume:Assets:HeroEyesClosed] as asset [HeroEyesClosed]
|
|
173
|
+
register resource [costume:Assets:HeroMouthClosed] as asset [HeroMouthClosed]
|
|
174
|
+
register resource [costume:Assets:HeroMouthOpen] as asset [HeroMouthOpen]
|
|
175
|
+
register resource [costume:Assets:Next1] as asset [Next1]
|
|
176
|
+
register resource [costume:Assets:Next2] as asset [Next2]
|
|
177
|
+
</code></pre>
|
|
178
|
+
<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. Define a text style</h2>
|
|
180
|
+
<p>Use SVG Text to define the named style for the Bubble's text layer.</p>
|
|
181
|
+
<pre><code class="language-text">define text style [dialogue-text]
|
|
182
|
+
background [#fff4cc]
|
|
183
|
+
text [#332200]
|
|
184
|
+
font [Noto Sans JP]
|
|
185
|
+
size [100]
|
|
186
|
+
align [left]
|
|
187
|
+
bubble direction [up]
|
|
188
|
+
</code></pre>
|
|
189
|
+
<p>Bubble refers to this style as <code>dialogue-text</code>. Text and Bubble styles are runtime state, so normally define them again whenever the green flag is clicked.</p>
|
|
190
|
+
<p>SVG Text 0.3.x retains a <code>bubble direction</code> input in its block contract, but Bubble does not use it when creating the text drawable through <code>setText</code>. Use <code>set bubble placement</code> in the next section instead. The obsolete SVG Text direction input is intended to be removed in a later breaking release.</p>
|
|
191
|
+
<h2 id="bubble-style">4. Define a Bubble style</h2>
|
|
192
|
+
<p>First associate a Bubble style name with an SVG Text style name.</p>
|
|
193
|
+
<pre><code class="language-text">define bubble style [hero-dialogue] using text style [dialogue-text]
|
|
194
|
+
set bubble placement [up-right] for bubble style [hero-dialogue]
|
|
195
|
+
set bubble distance [12] for bubble style [hero-dialogue]
|
|
196
|
+
set bubble visual style [NORMAL] for bubble style [hero-dialogue]
|
|
197
|
+
set bubble tail length [18] for bubble style [hero-dialogue]
|
|
198
|
+
set bubble offset x [0] y [0] scale [100] % for bubble style [hero-dialogue]
|
|
199
|
+
</code></pre>
|
|
200
|
+
<h3>Actor-relative and stage-relative placement</h3>
|
|
201
|
+
<p><img src="./assets/placement-guide.svg" alt="Actor-relative 16-way and angle placement compared with three stage-relative placements"></p>
|
|
202
|
+
<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
|
+
<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
|
+
<pre><code class="language-text">up / up-up-right / up-right / right-up-right
|
|
206
|
+
right / right-down-right / down-right / down-down-right
|
|
207
|
+
down / down-down-left / down-left / left-down-left
|
|
208
|
+
left / left-up-left / up-left / up-up-left
|
|
209
|
+
</code></pre>
|
|
210
|
+
<p>Compass aliases such as <code>north</code>, <code>north-northeast</code>, and <code>northeast</code> may also be typed directly or supplied by a reporter. A number uses Scratch direction semantics from 0 through 360 degrees: <code>0</code> is up, <code>90</code> right, <code>180</code> down, <code>270</code> left, and <code>360</code> normalizes to <code>0</code>. Arbitrary angles are not rounded to the 16 menu directions. The default is <code>up-right</code>.</p>
|
|
211
|
+
<p>Stage-relative placements do not point at an actor and are positioned within the Stage safe area.</p>
|
|
212
|
+
<table>
|
|
213
|
+
<thead>
|
|
214
|
+
<tr>
|
|
215
|
+
<th>Placement</th>
|
|
216
|
+
<th>Position</th>
|
|
217
|
+
</tr>
|
|
218
|
+
</thead>
|
|
219
|
+
<tbody><tr>
|
|
220
|
+
<td><code>HEADER_LIKE</code></td>
|
|
221
|
+
<td>Top of the Stage safe area, centered</td>
|
|
222
|
+
</tr>
|
|
223
|
+
<tr>
|
|
224
|
+
<td><code>CENTER</code></td>
|
|
225
|
+
<td>Horizontal and vertical center of the Stage</td>
|
|
226
|
+
</tr>
|
|
227
|
+
<tr>
|
|
228
|
+
<td><code>FOOTER_LIKE</code></td>
|
|
229
|
+
<td>Bottom of the Stage safe area, centered</td>
|
|
230
|
+
</tr>
|
|
231
|
+
</tbody></table>
|
|
232
|
+
<p>These placements do not depend on actor coordinates, bounds, or visibility. Use one of them when running <code>say</code> or <code>think</code> from the Stage. A stage-relative Bubble has no actor-pointing tail.</p>
|
|
233
|
+
<h3>Actor distance, tail, body offset, and scale</h3>
|
|
234
|
+
<p><img src="./assets/actor-transform-guide.svg" alt="Real Bubble SVGs comparing distance, tail length, offset, and scale"></p>
|
|
235
|
+
<ul>
|
|
236
|
+
<li><code>distance</code> (default <code>12</code>) is the gap between the actor bounds and the tail tip. Actor bounds means the axis-aligned bounding box (AABB) of the rendered actor in Stage coordinates.</li>
|
|
237
|
+
<li><code>tail length</code> (default <code>18</code>) is the nominal distance from the Bubble border to the tail tip at the normal position.</li>
|
|
238
|
+
<li><code>offset x/y/scale</code> (default <code>[0, 0, 100]</code>) uses positive x to the right, positive y upward, and scale as a percentage. <code>[10, -10, 120]</code> moves the body 10 right and 10 down, then scales it to 120%.</li>
|
|
239
|
+
</ul>
|
|
240
|
+
<p>Scale applies to the body, SVG Text, portrait base, blink/lip-sync layers, advance indicator, and internal padding as one unit, so the displayed font size scales by the same factor. When scale alone changes, the body center moves away from the actor by the increase in radius, preserving the actor-side gap. The x/y offset is added afterward. The tail tip remains fixed and the union with the body border is regenerated, so an offset can change the effective tail length.</p>
|
|
241
|
+
<p>Near a Stage edge, keeping the scaled Bubble on-screen takes priority and can reduce the requested distance. Actor-relative distance, tail, offset, and scale settings do not apply to <code>HEADER_LIKE</code>, <code>CENTER</code>, or <code>FOOTER_LIKE</code>.</p>
|
|
242
|
+
<h3>Width, automatic wrapping, and Japanese line-breaking rules</h3>
|
|
243
|
+
<p><img src="./assets/width-linebreak-guide.svg" alt="Automatic wrapping at different maxWidth values and Japanese line-breaking examples"></p>
|
|
244
|
+
<p>The diagram is generated by running the production <code>wrapText</code> implementation. <code>@cto.af/linebreak</code> supplies Unicode UAX #14 break opportunities, which are filtered against <code>Intl.Segmenter</code> grapheme boundaries. The renderer then chooses the last candidate that fits the measured width. It avoids unnatural breaks before punctuation, closing brackets, small kana and prolonged sound marks, and inside a combined emoji grapheme.</p>
|
|
245
|
+
<h3>Bubble visual styles</h3>
|
|
246
|
+
<p><img src="./assets/bubble-style-gallery.svg" alt="Ten Bubble visual styles rendered by the production SVG renderer"></p>
|
|
247
|
+
<p>Available shapes are <code>NORMAL</code>, <code>THINKING</code>, <code>DREAMING</code>, <code>YELLING</code>, <code>OFF_PANEL</code>, <code>WAVY</code>, <code>WHISPERING</code>, <code>ANNOUNCEMENT</code>, <code>NARRATION</code>, and <code>NO_BUBBLE</code>.</p>
|
|
248
|
+
<pre><code class="language-text">set bubble visual style [YELLING] for bubble style [hero-dialogue]
|
|
249
|
+
</code></pre>
|
|
250
|
+
<p>The diagram and TurboWarp drawable both use Bubble's shared <code>renderBubbleSvg</code> function. Shapes with triangular tails use a <a href="https://github.com/platener/jsclipper">platener/jsclipper</a> union between the body and tail. <code>THINKING</code> and <code>DREAMING</code> use circular trails and are excluded from that union. Actor-relative placement points the tail toward the actor; stage-relative placement has no tail. <code>NO_BUBBLE</code> hides the body drawable and displays only text, portrait, and other layers.</p>
|
|
251
|
+
<p>The default visual style is <code>NORMAL</code>. The body drawable is created before text and portrait drawables so it remains behind them. <code>close this bubble</code>, target/clone disposal, and runtime disposal release the body drawable and its owned SVG skin.</p>
|
|
252
|
+
<p><code>NEGATIVE</code> is not a separate style because it can be expressed with fill and border colors. Orientation and segments are also not public inputs; dimensions are calculated from width, font, character count, and the number of lines after wrapping.</p>
|
|
253
|
+
<p>Now configure the portrait and advance animation layers:</p>
|
|
254
|
+
<pre><code class="language-text">set portrait base [HeroFace] for bubble style [hero-dialogue]
|
|
255
|
+
|
|
256
|
+
set blink frames [HeroEyesOpen,HeroEyesClosed]
|
|
257
|
+
every [0.4] seconds for bubble style [hero-dialogue]
|
|
258
|
+
|
|
259
|
+
set talk frames [HeroMouthClosed,HeroMouthOpen]
|
|
260
|
+
every [0.1] seconds for bubble style [hero-dialogue]
|
|
261
|
+
|
|
262
|
+
set advance frames [Next1,Next2]
|
|
263
|
+
every [0.2] seconds for bubble style [hero-dialogue]
|
|
264
|
+
</code></pre>
|
|
265
|
+
<p><code>ASSETS</code> is a comma-separated list of Asset Manager names. Surrounding whitespace is removed; commas cannot be part of an asset name.</p>
|
|
266
|
+
<ul>
|
|
267
|
+
<li>Blink and talk animations accept one or more frames. A single frame remains static.</li>
|
|
268
|
+
<li>Use two or more advance frames so the loop is visible.</li>
|
|
269
|
+
<li><code>SECONDS</code> must be a finite number greater than zero.</li>
|
|
270
|
+
<li>An empty <code>ASSETS</code> input removes that animation.</li>
|
|
271
|
+
<li>An empty portrait base removes the whole portrait.</li>
|
|
272
|
+
</ul>
|
|
273
|
+
<h2 id="lifecycle">5. Show dialogue and wait for input</h2>
|
|
274
|
+
<p><code>say</code> and <code>think</code> show a Bubble immediately, continue to the next block, and begin in <code>talking</code> animation mode.</p>
|
|
275
|
+
<pre><code class="language-text">set runtime variable [input] to []
|
|
276
|
+
listen for key [Space] set runtime var [input] to [pressed]
|
|
277
|
+
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
278
|
+
say [Let's head for the sea!] with bubble style [hero-dialogue]
|
|
279
|
+
wait with this bubble until condition [input == "pressed"] or timeout after [10] seconds
|
|
280
|
+
close this bubble
|
|
281
|
+
</code></pre>
|
|
282
|
+
<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-advance</code>, stops lip-sync, and loops the images configured by <code>set advance 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>
|
|
283
|
+
<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>
|
|
284
|
+
<p>When combining Bubble with audio or a separate text-reveal system, switch to <code>awaiting-advance</code> when that process completes.</p>
|
|
285
|
+
<p><img src="./assets/bubble-lifecycle.gif" alt="A say Bubble lip-syncs, shows advance frames while awaiting advance, then closes after input"></p>
|
|
286
|
+
<p>If animated GIF playback is unavailable, use this static animation-mode comparison:</p>
|
|
287
|
+
<p><img src="./assets/animation-mode-guide.svg" alt="Blink, lip-sync, and advance-frame states in talking, awaiting-advance, and idle modes"></p>
|
|
288
|
+
<h2 id="animation-modes">6. Bubble animation modes</h2>
|
|
289
|
+
<table>
|
|
290
|
+
<thead>
|
|
291
|
+
<tr>
|
|
292
|
+
<th>Mode</th>
|
|
293
|
+
<th>Blink</th>
|
|
294
|
+
<th>Lip-sync</th>
|
|
295
|
+
<th>Advance frames</th>
|
|
296
|
+
<th>Typical use</th>
|
|
297
|
+
</tr>
|
|
298
|
+
</thead>
|
|
299
|
+
<tbody><tr>
|
|
300
|
+
<td><code>talking</code></td>
|
|
301
|
+
<td>Runs</td>
|
|
302
|
+
<td>Runs</td>
|
|
303
|
+
<td>Hidden</td>
|
|
304
|
+
<td>Dialogue display or audio playback</td>
|
|
305
|
+
</tr>
|
|
306
|
+
<tr>
|
|
307
|
+
<td><code>awaiting-advance</code></td>
|
|
308
|
+
<td>Runs</td>
|
|
309
|
+
<td>Stops/hidden</td>
|
|
310
|
+
<td>Loops</td>
|
|
311
|
+
<td>Await the user's request to advance</td>
|
|
312
|
+
</tr>
|
|
313
|
+
<tr>
|
|
314
|
+
<td><code>idle</code></td>
|
|
315
|
+
<td>Runs</td>
|
|
316
|
+
<td>Stops/hidden</td>
|
|
317
|
+
<td>Stops/hidden</td>
|
|
318
|
+
<td>Keep a Bubble visible and still</td>
|
|
319
|
+
</tr>
|
|
320
|
+
</tbody></table>
|
|
321
|
+
<p><code>set this bubble animation mode [MODE]</code> changes only the Bubble owned by the calling sprite, clone, or Stage. It reports an error if that target has not first run <code>say</code> or <code>think</code>.</p>
|
|
322
|
+
<h2 id="say-think">7. <code>say</code> and <code>think</code></h2>
|
|
323
|
+
<pre><code class="language-text">say [MESSAGE] with bubble style [STYLE]
|
|
324
|
+
think [MESSAGE] with bubble style [STYLE]
|
|
325
|
+
</code></pre>
|
|
326
|
+
<p>Both blocks support the same visual styles, portrait layers, placement, and animation-mode control. The block name does not force a shape; explicitly choose <code>NORMAL</code>, <code>THINKING</code>, or another shape with <code>set bubble visual style</code>. The Composition API surface still receives a <code>say</code>/<code>think</code> kind, so a custom host can add its own kind-dependent behavior.</p>
|
|
327
|
+
<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>
|
|
328
|
+
<h2 id="clones">8. Using Bubble with clones</h2>
|
|
329
|
+
<p>Bubble style definitions are shared within the extension, but each sprite or clone owns its currently displayed Bubble.</p>
|
|
330
|
+
<ol>
|
|
331
|
+
<li>Define assets and styles once from the original sprite when the green flag is clicked.</li>
|
|
332
|
+
<li>Run <code>say</code> or <code>think</code> from each clone itself.</li>
|
|
333
|
+
<li>Change the animation mode and close the Bubble from the same clone that displayed it.</li>
|
|
334
|
+
</ol>
|
|
335
|
+
<p>When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables owned by that target are released automatically.</p>
|
|
336
|
+
<h2 id="reference">9. Block reference</h2>
|
|
337
|
+
<table>
|
|
338
|
+
<thead>
|
|
339
|
+
<tr>
|
|
340
|
+
<th>Block</th>
|
|
341
|
+
<th>Description</th>
|
|
342
|
+
</tr>
|
|
343
|
+
</thead>
|
|
344
|
+
<tbody><tr>
|
|
345
|
+
<td><code>define bubble style [STYLE] using text style [TEXT_STYLE]</code></td>
|
|
346
|
+
<td>Define or redefine a Bubble style</td>
|
|
347
|
+
</tr>
|
|
348
|
+
<tr>
|
|
349
|
+
<td><code>set bubble placement [PLACEMENT] for bubble style [STYLE]</code></td>
|
|
350
|
+
<td>Set an actor direction/angle or a stage-relative region</td>
|
|
351
|
+
</tr>
|
|
352
|
+
<tr>
|
|
353
|
+
<td><code>set bubble distance [DISTANCE] for bubble style [STYLE]</code></td>
|
|
354
|
+
<td>Set the distance from actor bounds to the tail tip</td>
|
|
355
|
+
</tr>
|
|
356
|
+
<tr>
|
|
357
|
+
<td><code>set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]</code></td>
|
|
358
|
+
<td>Select one of ten SVG body shapes</td>
|
|
359
|
+
</tr>
|
|
360
|
+
<tr>
|
|
361
|
+
<td><code>set bubble tail length [LENGTH] for bubble style [STYLE]</code></td>
|
|
362
|
+
<td>Set the nominal border-to-tip tail length</td>
|
|
363
|
+
</tr>
|
|
364
|
+
<tr>
|
|
365
|
+
<td><code>set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]</code></td>
|
|
366
|
+
<td>Set body position and whole-Bubble scale, including text</td>
|
|
367
|
+
</tr>
|
|
368
|
+
<tr>
|
|
369
|
+
<td><code>set portrait base [ASSET] for bubble style [STYLE]</code></td>
|
|
370
|
+
<td>Set the portrait base image</td>
|
|
371
|
+
</tr>
|
|
372
|
+
<tr>
|
|
373
|
+
<td><code>set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]</code></td>
|
|
374
|
+
<td>Set blink overlays and interval</td>
|
|
375
|
+
</tr>
|
|
376
|
+
<tr>
|
|
377
|
+
<td><code>set talk frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]</code></td>
|
|
378
|
+
<td>Set lip-sync overlays and interval</td>
|
|
379
|
+
</tr>
|
|
380
|
+
<tr>
|
|
381
|
+
<td><code>set advance frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]</code></td>
|
|
382
|
+
<td>Set the animation shown during <code>awaiting-advance</code></td>
|
|
383
|
+
</tr>
|
|
384
|
+
<tr>
|
|
385
|
+
<td><code>say [MESSAGE] with bubble style [STYLE]</code></td>
|
|
386
|
+
<td>Start or replace a <code>say</code> Bubble in <code>talking</code> mode</td>
|
|
387
|
+
</tr>
|
|
388
|
+
<tr>
|
|
389
|
+
<td><code>think [MESSAGE] with bubble style [STYLE]</code></td>
|
|
390
|
+
<td>Start or replace a <code>think</code> Bubble in <code>talking</code> mode</td>
|
|
391
|
+
</tr>
|
|
392
|
+
<tr>
|
|
393
|
+
<td><code>set this bubble animation mode [MODE]</code></td>
|
|
394
|
+
<td>Select <code>talking</code>, <code>awaiting-advance</code>, or <code>idle</code> for this Bubble</td>
|
|
395
|
+
</tr>
|
|
396
|
+
<tr>
|
|
397
|
+
<td><code>wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds</code></td>
|
|
398
|
+
<td>Await a Runtime Expression condition or optional timeout</td>
|
|
399
|
+
</tr>
|
|
400
|
+
<tr>
|
|
401
|
+
<td><code>close this bubble</code></td>
|
|
402
|
+
<td>Release this target's Bubble and owned resources</td>
|
|
403
|
+
</tr>
|
|
404
|
+
<tr>
|
|
405
|
+
<td><code>Bubble version</code></td>
|
|
406
|
+
<td>Report the Bubble implementation version</td>
|
|
407
|
+
</tr>
|
|
408
|
+
</tbody></table>
|
|
409
|
+
<h2 id="troubleshooting">10. Troubleshooting</h2>
|
|
410
|
+
<table>
|
|
411
|
+
<thead>
|
|
412
|
+
<tr>
|
|
413
|
+
<th>Symptom</th>
|
|
414
|
+
<th>Cause and solution</th>
|
|
415
|
+
</tr>
|
|
416
|
+
</thead>
|
|
417
|
+
<tbody><tr>
|
|
418
|
+
<td>Asset Manager required error</td>
|
|
419
|
+
<td>Load Asset Manager 0.7.x without sandbox</td>
|
|
420
|
+
</tr>
|
|
421
|
+
<tr>
|
|
422
|
+
<td>SVG Text required error</td>
|
|
423
|
+
<td>Load SVG Text 0.3.x without sandbox</td>
|
|
424
|
+
</tr>
|
|
425
|
+
<tr>
|
|
426
|
+
<td>Async Input required error</td>
|
|
427
|
+
<td>Load Async Input 0.3.x without sandbox before using the Bubble wait</td>
|
|
428
|
+
</tr>
|
|
429
|
+
<tr>
|
|
430
|
+
<td>Runtime Expression required error</td>
|
|
431
|
+
<td>Load Runtime Expression 0.3.x without sandbox before using the Bubble wait</td>
|
|
432
|
+
</tr>
|
|
433
|
+
<tr>
|
|
434
|
+
<td><code>bubble style is not defined</code></td>
|
|
435
|
+
<td>Run <code>define bubble style</code> first, including after restarting with green flag</td>
|
|
436
|
+
</tr>
|
|
437
|
+
<tr>
|
|
438
|
+
<td>Image asset is not registered</td>
|
|
439
|
+
<td>Wait for <code>register resource ... as asset ...</code> before showing the Bubble</td>
|
|
440
|
+
</tr>
|
|
441
|
+
<tr>
|
|
442
|
+
<td>Asset is not an image</td>
|
|
443
|
+
<td>Confirm <code>MIME type of asset [NAME]</code> is <code>image/*</code></td>
|
|
444
|
+
</tr>
|
|
445
|
+
<tr>
|
|
446
|
+
<td>Only one advance frame</td>
|
|
447
|
+
<td>Supply at least two frames, or clear the setting</td>
|
|
448
|
+
</tr>
|
|
449
|
+
<tr>
|
|
450
|
+
<td>Frame interval error</td>
|
|
451
|
+
<td>Use a finite <code>SECONDS</code> value greater than zero</td>
|
|
452
|
+
</tr>
|
|
453
|
+
<tr>
|
|
454
|
+
<td>Actor-relative Bubble from the Stage</td>
|
|
455
|
+
<td>Use <code>HEADER_LIKE</code>, <code>CENTER</code>, or <code>FOOTER_LIKE</code></td>
|
|
456
|
+
</tr>
|
|
457
|
+
<tr>
|
|
458
|
+
<td>Invalid placement</td>
|
|
459
|
+
<td>Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value</td>
|
|
460
|
+
</tr>
|
|
461
|
+
<tr>
|
|
462
|
+
<td>Eyes or mouth are misaligned</td>
|
|
463
|
+
<td>Match canvas size, center, and transparent area across all portrait layers</td>
|
|
464
|
+
</tr>
|
|
465
|
+
</tbody></table>
|
|
466
|
+
<h2 id="cleanup">11. Automatic cleanup</h2>
|
|
467
|
+
<p>Bubble automatically releases its owned timers, SVG Text skins, and renderer drawables when:</p>
|
|
468
|
+
<ul>
|
|
469
|
+
<li><code>close this bubble</code> runs;</li>
|
|
470
|
+
<li>the same sprite or clone runs another <code>say</code> or <code>think</code>;</li>
|
|
471
|
+
<li>the target sprite or clone stops;</li>
|
|
472
|
+
<li>the green flag starts the project;</li>
|
|
473
|
+
<li>the whole project stops; or</li>
|
|
474
|
+
<li>the TurboWarp runtime is disposed.</li>
|
|
475
|
+
</ul>
|
|
476
|
+
<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>
|
|
477
|
+
<h2 id="regeneration">12. Regenerating the manual assets</h2>
|
|
478
|
+
<p>The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick <code>magick</code> command.</p>
|
|
479
|
+
<pre><code class="language-sh">pnpm docs:render
|
|
480
|
+
pnpm docs:check
|
|
481
|
+
</code></pre>
|
|
482
|
+
<p><code>docs:check</code> verifies SVG viewBoxes, production-renderer and <code>wrapText</code> markers, every visual style, the GIF dimensions/frame count/loop setting, references to all images and 16 blocks in both language manuals, and that the generated GitHub Pages HTML is current.</p>
|
|
483
|
+
</main>
|
|
484
|
+
<footer class="site-footer">Source code is available under MPL-2.0.</footer>
|
|
485
|
+
</body>
|
|
486
|
+
</html>
|