@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/README.md
CHANGED
|
@@ -1,61 +1,65 @@
|
|
|
1
1
|
# TurboWarp Bubble
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**English** | [日本語](README_ja.md)
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
`@kubohiroya/turbowarp-bubble` is an unsandboxed extension that manages TurboWarp `say` and `think` displays as separate text, character-expression, and input-waiting indicator layers. It also provides a composition API for using the same features directly from applications.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
The current release is Bubble 0.9.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.8.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. See the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles and TurboWarp-compatible basic bubbles.
|
|
8
8
|
|
|
9
|
-
|
|
10
|
-
2. 独自Webアプリやhostから使う場合は、[Composition API](#composition-api)と[Styleと表示](#styleと表示)を確認します。
|
|
11
|
-
3. 表示単位、改行、外形、portrait、animationの仕様を知りたい場合は、[概念と表示仕様](#概念と表示仕様)を参照します。
|
|
12
|
-
4. Scratch公式エディターでの利用可否は、[Scratchとの互換性](#scratchとの互換性)に記載しています。
|
|
9
|
+
## How to read this README
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
Choose your environment first so that you only need to read the relevant sections.
|
|
15
12
|
|
|
16
|
-
|
|
13
|
+
1. To use blocks in TurboWarp, see [TurboWarp extension](#turbowarp-extension) and [Available blocks](#available-blocks).
|
|
14
|
+
2. To use Bubble from a custom web application or host, see [Composition API](#composition-api) and [Styles and display](#styles-and-display).
|
|
15
|
+
3. For the specifications of reveal units, line wrapping, shapes, portraits, and animations, see [Concepts and display specifications](#concepts-and-display-specifications).
|
|
16
|
+
4. See [Scratch compatibility](#scratch-compatibility) for availability in the official Scratch editor.
|
|
17
|
+
|
|
18
|
+
## Feature overview
|
|
19
|
+
|
|
20
|
+
Bubble combines a Text provider that draws text, a Bubble layer that manages the bubble outline and placement, and optional Asset capabilities that resolve images and audio. This lets the TurboWarp extension and compositions called by application hosts use the same display model.
|
|
17
21
|
|
|
18
22
|
```mermaid
|
|
19
23
|
flowchart LR
|
|
20
|
-
input[
|
|
24
|
+
input[Dialogue input] --> reveal[Select reveal unit]
|
|
21
25
|
reveal --> text[CHARACTER / WORD / LINE / BLOCK]
|
|
22
|
-
text --> layout[
|
|
23
|
-
layout --> body[Bubble
|
|
24
|
-
text --> voice[
|
|
25
|
-
body --> portrait[
|
|
26
|
-
portrait --> blink[
|
|
27
|
-
portrait --> lipsync[
|
|
28
|
-
body --> motion[
|
|
29
|
-
body --> wait[continue
|
|
30
|
-
wait --> close[
|
|
26
|
+
text --> layout[Line wrapping and size calculation]
|
|
27
|
+
layout --> body[Bubble outline, tail, and placement]
|
|
28
|
+
text --> voice[Full voice and per-unit sound effects]
|
|
29
|
+
body --> portrait[Portrait layers]
|
|
30
|
+
portrait --> blink[Blink]
|
|
31
|
+
portrait --> lipsync[Lip-sync]
|
|
32
|
+
body --> motion[Show, active, and hide animations]
|
|
33
|
+
body --> wait[Wait for continue]
|
|
34
|
+
wait --> close[Close and release resources]
|
|
31
35
|
```
|
|
32
36
|
|
|
33
|
-
|
|
37
|
+
The table below maps the 0.9.0 feature set to its public entry points. The standalone extension exposes 29 palette blocks generated from 31 definitions; two hidden legacy definitions keep previously saved styled say/think blocks working. The full visible list appears under [Available blocks](#available-blocks).
|
|
34
38
|
|
|
35
|
-
|
|
|
36
|
-
|
|
|
37
|
-
|
|
|
38
|
-
|
|
|
39
|
-
|
|
|
40
|
-
| Bubble
|
|
41
|
-
|
|
|
42
|
-
|
|
|
39
|
+
| Area | What this README covers | Public entry points |
|
|
40
|
+
| --------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
|
|
41
|
+
| Text rendering and wrapping | `BubbleTextCapability`, named styles, measured width, `maxWidth`, and UAX #14-compliant wrapping | `composition`, `turbowarp-adapter`, and extension blocks |
|
|
42
|
+
| Progressive reveal | `CHARACTER` / `WORD` / `LINE` / `BLOCK`, delimiters, per-unit sound effects, and finish conditions | `composition`, lightweight `reveal` entry, and blocks |
|
|
43
|
+
| Portrait | Independent base-image, `blink`, and `lip-sync` layers | Composition API and blocks through Asset Manager |
|
|
44
|
+
| Bubble outline | Visual styles such as `NORMAL`, placement, tail, offset, and scale | Composition API, TurboWarp adapter, and blocks |
|
|
45
|
+
| Display mode | `talking` / `awaiting-continue` / `idle` | `BubbleHandle.setAnimationMode()` and the matching block |
|
|
46
|
+
| Show, active, and hide animations | `fadeIn`, `floatIn`, `shake`, `animateBubbleShape`, and others | Style settings, `BubbleHandle.animate()`, and blocks |
|
|
43
47
|
|
|
44
|
-
##
|
|
48
|
+
## Concepts and display specifications
|
|
45
49
|
|
|
46
|
-
###
|
|
50
|
+
### Three-layer architecture and responsibilities
|
|
47
51
|
|
|
48
|
-
|
|
52
|
+
The dependency structure places the pure Bubble composition at the center, with the TurboWarp adapter and each provider around it. Arrows point from the consumer to the dependency it uses.
|
|
49
53
|
|
|
50
54
|
```mermaid
|
|
51
55
|
flowchart TB
|
|
52
|
-
core["Bubble core\
|
|
53
|
-
contract["BubbleTextCapability\nhost-neutral
|
|
54
|
-
twAdapter["TurboWarp Bubble adapter\
|
|
55
|
-
svgAdapter["SVG Text adapter\
|
|
56
|
-
assets["
|
|
57
|
-
input["
|
|
58
|
-
host["
|
|
56
|
+
core["Bubble core\noutline, placement, lifecycle, and animation state"]
|
|
57
|
+
contract["BubbleTextCapability\nhost-neutral text contract"]
|
|
58
|
+
twAdapter["TurboWarp Bubble adapter\nconnects to renderer / runtime / target"]
|
|
59
|
+
svgAdapter["SVG Text 0.8 layout adapter\nrenderer-independent line layout and measurement"]
|
|
60
|
+
assets["Optional Image / Audio capabilities\nportrait, lip-sync, and audio"]
|
|
61
|
+
input["Optional Input / Expression capabilities\ninput and wait conditions"]
|
|
62
|
+
host["Custom web application / host"]
|
|
59
63
|
extension["TurboWarp extension\nblocks / Scratch target"]
|
|
60
64
|
core -->|"consumes"| contract
|
|
61
65
|
svgAdapter -->|"implements"| contract
|
|
@@ -67,62 +71,115 @@ flowchart TB
|
|
|
67
71
|
extension -."optional".-> input
|
|
68
72
|
```
|
|
69
73
|
|
|
70
|
-
|
|
74
|
+
In this architecture, Bubble core refers only to the host-neutral `BubbleTextCapability` contract. By default, the TurboWarp adapter calls `createSvgTextLayoutComposition().layoutText()` from its direct dependency, `@kubohiroya/turbowarp-svg-text@0.8.1`, to obtain line layout and text widths without creating SVG skins. When the standalone SVG Text 0.8.1 extension is already loaded, Bubble instead adapts its public `getLayoutCapability()` so styles defined by project blocks retain their font, color, size, and alignment. The bubble outline, tail, portrait placement, and show and hide animations are outside SVG Text's responsibilities. A Composition API host can inject a different implementation as `textCapability`. Image resolution, audio playback, input, and condition evaluation are also separated into capabilities; Asset Manager, Async Input, and Runtime Expression are connected only when their corresponding features are used.
|
|
75
|
+
|
|
76
|
+
### Rendering backend (SVG overlay by default)
|
|
77
|
+
|
|
78
|
+
The default value of `bubbleRenderBackend` is `"svg-overlay"`. Bubble places a shared SVG root over the stage canvas with `renderer.addOverlay(root, "scale")`, then renders the body, tail, text, portrait, corner clip, and continue indicator as DOM elements. Text uses host-neutral SVG Text 0.8.1 layout data, either from the loaded standalone extension's shared named-style registry or from Bubble's bundled fallback composition. On this default path, Bubble does not call `createDrawable()`, `createSVGSkin()`, or `createBitmapSkin()` to show bubbles, update text or styles, or run animations, so Bubble-originated work never enters scratch-render's `SVGSkin` / `Silhouette` path. `"scratch-render"` is used only when explicitly selected for compatibility or rollback.
|
|
79
|
+
|
|
80
|
+
When the stock Asset Manager 0.12.1 extension is loaded before Bubble in TurboWarp, Bubble calls `runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()` the first time a portrait or another image feature is used. It then lazily connects to the same registry populated by Asset Manager blocks. Asset Manager is not loaded when only text is used. A Composition API host can inject capabilities explicitly as follows.
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
|
|
84
|
+
import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
|
|
85
|
+
import {
|
|
86
|
+
createAssetManagerSvgOverlayImageCapability,
|
|
87
|
+
createSvgTextOverlayTextCapability,
|
|
88
|
+
createTurboWarpBubbleComposition,
|
|
89
|
+
} from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
|
|
90
|
+
|
|
91
|
+
const assets = createAssetManagerComposition();
|
|
92
|
+
const textLayouts = createSvgTextLayoutComposition();
|
|
93
|
+
|
|
94
|
+
textLayouts.defineStyle({
|
|
95
|
+
name: "dialogue-text",
|
|
96
|
+
alignment: "left",
|
|
97
|
+
backgroundColor: "transparent",
|
|
98
|
+
font: "Helvetica",
|
|
99
|
+
fontPercent: 100,
|
|
100
|
+
textColor: "#575e75",
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
const bubbles = createTurboWarpBubbleComposition(runtime, {
|
|
104
|
+
svgOverlayTextCapability: createSvgTextOverlayTextCapability(textLayouts),
|
|
105
|
+
svgOverlayImageCapability:
|
|
106
|
+
createAssetManagerSvgOverlayImageCapability(assets),
|
|
107
|
+
});
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
When `svgOverlayTextCapability` is omitted and standalone SVG Text 0.8.1 is loaded, Bubble obtains its frozen `getLayoutCapability()` and resolves the exact named-style registry populated by SVG Text blocks. If standalone SVG Text is absent, Bubble creates its own SVG Text 0.8.1 layout composition and initializes `default` and each first-referenced text-style name with transparent-background defaults. If an older standalone extension is present without the public handoff, Bubble reports `BUBBLE-RUNTIME-004` instead of silently replacing project styles; explicit `svgOverlayUnsupportedBehavior: "fallback"` selects scratch-render. Supplying a capability directly overrides both automatic paths. For portraits and similar features, Bubble's `createAssetManagerSvgOverlayImageCapability()` converts generic Asset Manager DOM resources into Bubble's image contract. The dependency points one way, from Bubble to Asset Manager; Asset Manager does not refer to Bubble types or security markers. The adapter exposes only MIME types allowed by both packages, carries across the validated MIME type, intrinsic size, `blob:` URL, and `release()`, and adds Bubble metadata to sanitized SVG from Asset Manager. Bubble never inserts arbitrary SVG strings. It reconstructs only allowed elements and attributes, such as `path` and `group`, from the canonical body by using `createElementNS()`. It rejects `script`, event handlers, `foreignObject`, and external URLs. The overlay root uses `pointer-events: none` and `aria-hidden="true"`.
|
|
111
|
+
|
|
112
|
+
The default text provider is the directly depended-on SVG Text 0.8.1. Preserving styles from a separately loaded stock SVG Text extension requires its 0.8.1 `getLayoutCapability()`. Automatic image connection between stock extensions requires Asset Manager 0.12.1 or later, which exposes `getDOMImageCapability()`. The lower-level path that explicitly injects `resolveDOMImageResource()` from the Composition API is available with Asset Manager 0.12.0 or later.
|
|
113
|
+
|
|
114
|
+
The skin-independent contracts for SVG Text and Asset Manager are published in [turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26), [turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103), and the stock registry handoff in [turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106). Bubble uses only public upstream APIs and never substitutes private-field access or extraction from skins. Selecting `svg-overlay` on a host without the overlay API returns `BUBBLE-RUNTIME-004`. Using images without either Asset Manager 0.12.1's public capability or an explicitly injected capability returns `BUBBLE-RUNTIME-002`. Bubble falls back to `scratch-render` on a host without the overlay API only when `svgOverlayUnsupportedBehavior: "fallback"` is explicitly specified.
|
|
71
115
|
|
|
72
|
-
|
|
116
|
+
| Host / capture method | `scratch-render` | `svg-overlay` |
|
|
117
|
+
| ------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------- |
|
|
118
|
+
| TurboWarp Web / Desktop | Supported | Supported when the overlay API and the public capabilities described above are available |
|
|
119
|
+
| TurboWarp Packager / player HTML | Supported | Supported under the same conditions when the packaged DOM can retain the overlay root |
|
|
120
|
+
| Host without `renderer.addOverlay` | Supported | Explicit error by default; fallback only when configured |
|
|
121
|
+
| OS screenshot / screen recording | Included | Included in the final browser composite |
|
|
122
|
+
| `renderer.canvas.toDataURL()` / `toBlob()` | Included | Not included in the raw WebGL canvas |
|
|
123
|
+
| `renderer.canvas.captureStream()` | Included | Not included in the raw WebGL stream |
|
|
73
124
|
|
|
74
|
-
|
|
125
|
+
When the stage's native size changes, Bubble updates the root `viewBox` and every surface. Fullscreen and high-DPI CSS scaling are delegated to the renderer's `scale` overlay mode. On stop, project reload, target or clone destruction, or composition disposal, Bubble releases listeners, DOM nodes, and capability-owned resources. It calls `removeOverlay(root)` when the last Bubble is closed.
|
|
75
126
|
|
|
76
|
-
|
|
127
|
+
Automated regression tests verify that showing a Bubble, updating text, shaking it, and animating its shape with the default settings create zero Bubble-originated renderer skins or drawables. They also cover native-size updates, the shared root, upstream SVG Text 0.8.1 named-style coordinates and rounded corners, allowed attributes, and object URL release. The manual gates for visual parity and frame-time / memory behavior in Web, Desktop, and Packager are recorded in the [SVG overlay release notes](docs/release-notes-0.8.0.md).
|
|
128
|
+
|
|
129
|
+
### Progressive reveal units (CHARACTER / WORD / LINE / BLOCK)
|
|
130
|
+
|
|
131
|
+
Instead of only showing the entire line at once, Bubble can progressively add content one selected unit at a time. `CHARACTER` means a displayed grapheme cluster, not a morphological token, so combining characters and emoji are not split in the middle.
|
|
132
|
+
|
|
133
|
+
The spelling in the specification is `CHARACTER`, not `charactor`. `BLOCK` treats multiple lines, including line breaks, as one reveal unit; block here does not mean a Scratch block.
|
|
77
134
|
|
|
78
135
|
```mermaid
|
|
79
136
|
flowchart LR
|
|
80
|
-
source["
|
|
137
|
+
source["Full text: 私の/名前は/中野/です"] --> mode{"Reveal unit"}
|
|
81
138
|
mode -->|CHARACTER| c["私 → 私の → 私の/ → …"]
|
|
82
139
|
mode -->|WORD| w["私の → 私の/名前は → …"]
|
|
83
|
-
mode -->|LINE| l["
|
|
84
|
-
mode -->|BLOCK| b["
|
|
85
|
-
delimiter["
|
|
86
|
-
visibility{"
|
|
87
|
-
visibility -->|invisible| hidden["
|
|
140
|
+
mode -->|LINE| l["Add one line at a time"]
|
|
141
|
+
mode -->|BLOCK| b["Add multiple lines / a paragraph at once"]
|
|
142
|
+
delimiter["Arbitrary delimiter set<br/>for example: slash, space, or vertical bar"] -.-> w
|
|
143
|
+
visibility{"Show delimiters"} -->|visible| shown["Render delimiters"]
|
|
144
|
+
visibility -->|invisible| hidden["Hide delimiters"]
|
|
88
145
|
delimiter --> visibility
|
|
89
146
|
```
|
|
90
147
|
|
|
91
|
-
### WORD
|
|
148
|
+
### WORD delimiters
|
|
92
149
|
|
|
93
|
-
|
|
150
|
+
Bubble does not perform Japanese morphological analysis. `WORD` is intended for languages separated by spaces or languages in which the user can insert delimiters. For example, enter `私の/名前は/中野/です`, set `/` as an invisible WORD delimiter, and the units appear in the order `私の` → `名前は` → `中野` → `です`. Making the delimiter visible preserves the slashes as part of the presentation.
|
|
94
151
|
|
|
95
|
-
|
|
152
|
+
Delimiters are not limited to one character; they can be specified as an arbitrary character set. You can choose whether to include each delimiter in the reveal unit or remove it before passing the text to the Text provider.
|
|
96
153
|
|
|
97
|
-
### DYNAMIC
|
|
154
|
+
### DYNAMIC and RESERVED
|
|
98
155
|
|
|
99
|
-
|
|
156
|
+
Two bubble-sizing strategies are available during progressive reveal.
|
|
100
157
|
|
|
101
158
|
```mermaid
|
|
102
159
|
sequenceDiagram
|
|
103
160
|
participant Host as Host
|
|
104
161
|
participant Bubble as Bubble surface
|
|
105
162
|
participant Text as Text provider
|
|
106
|
-
Host->>Text:
|
|
163
|
+
Host->>Text: Measure the full text
|
|
107
164
|
alt RESERVED
|
|
108
|
-
Text-->>Bubble:
|
|
109
|
-
Bubble->>Bubble:
|
|
110
|
-
loop
|
|
111
|
-
Host->>Text:
|
|
112
|
-
Text-->>Bubble:
|
|
165
|
+
Text-->>Bubble: Final width and line count
|
|
166
|
+
Bubble->>Bubble: Reserve final size in advance
|
|
167
|
+
loop For each reveal unit
|
|
168
|
+
Host->>Text: Update visible range
|
|
169
|
+
Text-->>Bubble: Update text only
|
|
113
170
|
end
|
|
114
171
|
else DYNAMIC
|
|
115
|
-
loop
|
|
116
|
-
Host->>Text:
|
|
117
|
-
Text-->>Bubble:
|
|
118
|
-
Bubble->>Bubble:
|
|
172
|
+
loop For each reveal unit
|
|
173
|
+
Host->>Text: Update visible range
|
|
174
|
+
Text-->>Bubble: Current width and line count
|
|
175
|
+
Bubble->>Bubble: Recalculate outline and placement
|
|
119
176
|
end
|
|
120
177
|
end
|
|
121
178
|
```
|
|
122
179
|
|
|
123
|
-
`RESERVED
|
|
180
|
+
`RESERVED` keeps the outline more stable during reveal, while `DYNAMIC` avoids extra whitespace in short lines. `DYNAMIC` is the default layout. In `normalizeBubbleReveal` and the Composition API, the default `intervalSeconds` is `0`, which disables automatic advance; the extension block starts with `0.05` in its seconds field. Both layouts are independent of bubble-outline animations and portrait layers. The style's `reveal`, `handle.revealNext()`, and `handle.revealAll()` are the integration points for splitting and timing; a positive `intervalSeconds` enables automatic advance.
|
|
124
181
|
|
|
125
|
-
|
|
182
|
+
To reveal all remaining units before entering the waiting state, use a finish operation with an explicit reveal unit.
|
|
126
183
|
|
|
127
184
|
```text
|
|
128
185
|
finish [CHARACTER / WORD / LINE / BLOCK]
|
|
@@ -130,39 +187,39 @@ finish [CHARACTER / WORD / LINE / BLOCK]
|
|
|
130
187
|
or timeout after [TIMEOUT] seconds
|
|
131
188
|
```
|
|
132
189
|
|
|
133
|
-
`CONDITION
|
|
190
|
+
When `CONDITION` becomes true, Bubble reveals every remaining unit. If it does not become true, the same completion process begins after `TIMEOUT` seconds. Set `TIMEOUT` to `0` for no time limit. On completion, Bubble can move to `awaiting-continue`, or the host can start `close` or the hide animation. Use `handle.finish({ unit, condition, timeoutSeconds })` in the Composition API or the `finish [UNIT] ...` block in the procedural extension. The block requires Runtime Expression; Async Input is needed as well only when input events update variables used by the condition.
|
|
134
191
|
|
|
135
|
-
###
|
|
192
|
+
### Audio and reveal units
|
|
136
193
|
|
|
137
|
-
`finish
|
|
194
|
+
`finish` is available as `handle.finish({ unit, condition, timeoutSeconds })` in the public Composition API and as the TurboWarp `finish [UNIT] ...` block. It completes progressive reveal and settles the audio and waiting state when the condition succeeds or the timeout expires.
|
|
138
195
|
|
|
139
|
-
Asset Manager
|
|
196
|
+
When Asset Manager is connected as the audio provider, the following audio can share the same display lifecycle:
|
|
140
197
|
|
|
141
|
-
-
|
|
142
|
-
- `CHARACTER
|
|
143
|
-
-
|
|
198
|
+
- Full voice playback when display starts
|
|
199
|
+
- A sound effect each time one `CHARACTER`, `WORD`, `LINE`, or `BLOCK` unit is revealed
|
|
200
|
+
- A finish cue after the Composition API's `finish` condition succeeds or its timeout expires
|
|
144
201
|
|
|
145
|
-
|
|
202
|
+
Per-unit effects play named audio assets; they do not synthesize the displayed string as speech. TurboWarp blocks expose voice and per-unit reveal sounds; `audio.finish` is currently a Composition API setting. Text, portraits, and the Bubble outline remain independently usable when no audio is provided.
|
|
146
203
|
|
|
147
|
-
###
|
|
204
|
+
### Package boundaries
|
|
148
205
|
|
|
149
|
-
|
|
|
150
|
-
| ------------------------------------------ |
|
|
151
|
-
| `@kubohiroya/turbowarp-asset-manager` |
|
|
152
|
-
| Bubble core
|
|
153
|
-
| `@kubohiroya/turbowarp-svg-text` |
|
|
154
|
-
| `@kubohiroya/turbowarp-async-input` |
|
|
155
|
-
| `@kubohiroya/turbowarp-runtime-expression` | runtime
|
|
156
|
-
| `@kubohiroya/turbowarp-bubble` |
|
|
157
|
-
|
|
|
206
|
+
| Package | Responsibility |
|
|
207
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
|
|
208
|
+
| `@kubohiroya/turbowarp-asset-manager` | Connect optional Image / Audio capabilities to TurboWarp assets (image resolution and audio playback) |
|
|
209
|
+
| Bubble core (`composition`) | `BubbleTextCapability` contract, bubble surfaces, placement, progressive reveal, and animation |
|
|
210
|
+
| `@kubohiroya/turbowarp-svg-text` | Host-neutral plain / ruby layout, stock named-style handoff, and text-width measurement in version 0.8.1 |
|
|
211
|
+
| `@kubohiroya/turbowarp-async-input` | Reflect key and tap input in Temporary Variables runtime variables |
|
|
212
|
+
| `@kubohiroya/turbowarp-runtime-expression` | Safely evaluate wait conditions that refer to runtime variables |
|
|
213
|
+
| `@kubohiroya/turbowarp-bubble` | Bubble surfaces, placement, progressive reveal, say / think, expression layers, animation, and input waiting |
|
|
214
|
+
| Application / host | Convert application-specific input to Composition API calls as needed |
|
|
158
215
|
|
|
159
|
-
Bubble
|
|
216
|
+
Bubble does not re-export its dependencies. The lower-level Composition API requires `textCapability` as a contract and is not limited to SVG Text. The TurboWarp adapter uses the separately loaded SVG Text 0.8.1 named-style handoff when available, otherwise it creates the directly depended-on layout composition as its provider. Image, audio, input, and condition-evaluation capabilities are replaceable; the TurboWarp adapter connects Asset Manager lazily, while Composition API hosts can implement `imageResolver` and `audio` themselves. Features that use Asset Manager cover external media beyond images, including full voice clips, typewriter sounds, and per-line or per-paragraph effects.
|
|
160
217
|
|
|
161
|
-
###
|
|
218
|
+
### Automatic wrapping and line-breaking rules
|
|
162
219
|
|
|
163
|
-
Bubble
|
|
220
|
+
For automatic wrapping with the optional `maxWidth`, Bubble uses `@cto.af/linebreak` to find Unicode UAX #14-compliant line-break opportunities. The dependency is contained behind the `LineBreakProvider` interface. Bubble measures text using the actual font and selects the last candidate that fits within the limit.
|
|
164
221
|
|
|
165
|
-
`UnicodeLineBreakProvider
|
|
222
|
+
`UnicodeLineBreakProvider` restricts UAX #14 candidates to grapheme boundaries reported by `Intl.Segmenter`. In addition to applying line-start and line-end restrictions for punctuation and small kana, this prevents splitting combining characters or emoji. Explicit line breaks are preserved. Only strings with no valid break candidate, such as some URLs, fall back to splitting at grapheme boundaries.
|
|
166
223
|
|
|
167
224
|
```ts
|
|
168
225
|
import { wrapText } from "@kubohiroya/turbowarp-bubble/composition";
|
|
@@ -174,23 +231,23 @@ const layout = wrapText({
|
|
|
174
231
|
});
|
|
175
232
|
```
|
|
176
233
|
|
|
177
|
-
Composition API
|
|
234
|
+
Passing `maxWidth` and an optional `textLocale` in a Composition API Bubble style makes this `wrapText` foundation wrap the actual displayed string using the Text capability's `measureText`. If SVG Text or a host-provided Text capability does not provide `measureText`, displaying content with `maxWidth` produces an explicit capability error.
|
|
178
235
|
|
|
179
|
-

|
|
180
237
|
|
|
181
|
-
|
|
238
|
+
Every line in the figure is produced by calling the production `wrapText` implementation directly; the illustration does not use manually inserted line breaks.
|
|
182
239
|
|
|
183
|
-
### Bubble visual
|
|
240
|
+
### Bubble visual-style shapes
|
|
184
241
|
|
|
185
|
-
|
|
242
|
+
The available shapes are `NORMAL`, `THINKING`, `DREAMING`, `YELLING`, `OFF_PANEL`, `WAVY`, `WHISPERING`, `ANNOUNCEMENT`, `NARRATION`, and `NO_BUBBLE`.
|
|
186
243
|
|
|
187
|
-

|
|
188
245
|
|
|
189
|
-
|
|
246
|
+
This figure is generated with Bubble's shared `renderBubbleSvg`. For shapes with a triangular tail, the renderer finds the two tail-base points on the actual body border, unions the body polygon with the tail triangle using [platener/jsclipper](https://github.com/platener/jsclipper), and draws only the single resulting outline path. The round trails used by `THINKING` and `DREAMING` remain separate shapes.
|
|
190
247
|
|
|
191
|
-
standalone
|
|
248
|
+
In the standalone extension, select a shape with the `set bubble visual style` block. Both rendering backends use the shared `renderBubbleSvg`: the default overlay reconstructs its canonical SVG as allowlisted DOM elements, while explicit `scratch-render` mode applies an SVG skin to a dedicated drawable. In both cases the body stays behind the text and expressions. Actor-relative bubbles generate a tail pointing toward the Actor; background-relative bubbles have no tail. `NO_BUBBLE` hides the body and displays only the text, expressions, and other content. `NEGATIVE` can be represented using the fill and border colors, so it is not a separate style; orientation and segments are not exposed as inputs either.
|
|
192
249
|
|
|
193
|
-
portrait
|
|
250
|
+
A portrait can be placed at `left`, `right`, `top-left`, `top-right`, `bottom-left`, or `bottom-right`, with a portrait-specific `[x, y, zoom]` and corner radius. Placement defaults to `left`, the transform defaults to `[0, 0, 100]`, and corner radius defaults to `0`. Zoom must be greater than zero, and corner radius cannot be negative. In the standalone extension, use `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px ...`; select `none` to remove the entire portrait. In the Composition API, include it in the style as follows.
|
|
194
251
|
|
|
195
252
|
```ts
|
|
196
253
|
portrait: {
|
|
@@ -201,23 +258,23 @@ portrait: {
|
|
|
201
258
|
}
|
|
202
259
|
```
|
|
203
260
|
|
|
204
|
-
|
|
261
|
+
See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) for the licenses of dependencies included in the distributed bundle.
|
|
205
262
|
|
|
206
|
-
##
|
|
263
|
+
## Usage
|
|
207
264
|
|
|
208
|
-
###
|
|
265
|
+
### Installation
|
|
209
266
|
|
|
210
267
|
```sh
|
|
211
268
|
pnpm add @kubohiroya/turbowarp-bubble
|
|
212
269
|
```
|
|
213
270
|
|
|
214
|
-
npm
|
|
271
|
+
With npm, install the same dependency as follows.
|
|
215
272
|
|
|
216
273
|
```sh
|
|
217
274
|
npm install @kubohiroya/turbowarp-bubble
|
|
218
275
|
```
|
|
219
276
|
|
|
220
|
-
|
|
277
|
+
Consumers that need only progressive-reveal normalization and string splitting can import the small `reveal` entry point without including the entire Bubble composition.
|
|
221
278
|
|
|
222
279
|
```ts
|
|
223
280
|
import {
|
|
@@ -229,15 +286,11 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
|
|
|
229
286
|
const chunks = splitBubbleText("A👩🚀B", reveal);
|
|
230
287
|
```
|
|
231
288
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
TurboWarp adapterの既定文字経路を使う場合は、SVG Textを追加します。
|
|
289
|
+
SVG Text 0.8.1 is included as a regular dependency and serves as the default skin-independent text provider. You do not need to install it separately. Loading the standalone SVG Text 0.8.1 extension first is optional, but doing so lets Bubble reuse styles defined by its project blocks through the public handoff. Bubble's declared optional peer ranges remain `>=0.7.0 <1` for Asset Manager and `>=0.3.0 <1` for both Async Input and Runtime Expression; the currently published and recommended extension versions are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. Even when a host injects a custom `svgOverlayTextCapability`, Bubble's own SVG Text dependency remains fixed at version 0.8.1.
|
|
235
290
|
|
|
236
|
-
|
|
237
|
-
pnpm add @kubohiroya/turbowarp-svg-text
|
|
238
|
-
```
|
|
291
|
+
After rolling back to `bubbleRenderBackend: "scratch-render"`, Bubble creates a skin-based provider from the same 0.8.1 dependency if the standalone SVG Text extension is not loaded. On a host where the standalone SVG Text extension is already loaded, Bubble continues using that existing provider for compatibility.
|
|
239
292
|
|
|
240
|
-
|
|
293
|
+
Add Asset Manager to use image portraits, lip-sync, continue indicators, or audio assets. The `finish [UNIT] ...` block requires Runtime Expression. The integrated `wait with this bubble ...` block requires both Async Input and Runtime Expression.
|
|
241
294
|
|
|
242
295
|
```sh
|
|
243
296
|
pnpm add @kubohiroya/turbowarp-asset-manager \
|
|
@@ -251,92 +304,119 @@ npm install @kubohiroya/turbowarp-asset-manager \
|
|
|
251
304
|
@kubohiroya/turbowarp-runtime-expression
|
|
252
305
|
```
|
|
253
306
|
|
|
254
|
-
### TurboWarp
|
|
307
|
+
### TurboWarp extension
|
|
255
308
|
|
|
256
|
-
|
|
309
|
+
For instructions covering block assembly, preparation of expression variants, input waiting, clones, and troubleshooting, see the block manual ([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/)). It also includes an animation example covering `talking`, the transition to `awaiting-continue`, successful input, and `close`.
|
|
257
310
|
|
|
258
|
-
|
|
311
|
+
In the Kamishibai DSL 4.0 combined bundle, open this manual with the documentation button directly below the **Bubble** member heading. The bundled palette keeps the same style, placement, portrait, reveal, audio, wait, animation, clone, and cleanup behavior; its member namespace and Bubble icon identify the originating extension.
|
|
259
312
|
|
|
260
|
-
|
|
313
|
+
#### Loading in TurboWarp
|
|
261
314
|
|
|
262
|
-
|
|
263
|
-
2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
|
|
264
|
-
3. SVG Textを読み込みます。Bubbleの文字style定義と文字幅計測に必要です。
|
|
265
|
-
4. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Managerを読み込みます。
|
|
266
|
-
5. `wait with this bubble until condition ...`を使う場合はAsync InputとRuntime Expressionを読み込みます。
|
|
267
|
-
6. 最後にBubbleを読み込みます。依存拡張を先に読み込むと、対応するブロックとcapabilityが接続されます。
|
|
315
|
+
TurboWarp Bubble's `dist/turbowarp-bubble.js` is an **unsandboxed custom extension** that connects to TurboWarp's renderer and target APIs. Load it in the TurboWarp Editor in this order:
|
|
268
316
|
|
|
269
|
-
|
|
317
|
+
1. For the input-wait example, open your project in the TurboWarp Editor and add Temporary Variables from the extension library.
|
|
318
|
+
2. Select “Custom Extension” and enable Run without sandbox.
|
|
319
|
+
3. Load Asset Manager 0.12.1 if you use portraits, blinking, lip-sync, continue frames, or audio.
|
|
320
|
+
4. Load Runtime Expression 0.4.0 for `finish [UNIT] ...`; load both Async Input 0.4.0 and Runtime Expression 0.4.0 for `wait with this bubble until condition ...`.
|
|
321
|
+
5. Load Bubble 0.9.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
|
|
322
|
+
|
|
323
|
+
Bubble alone is the minimum configuration for text-only use. Temporary Variables, Asset Manager, Async Input, and Runtime Expression can be omitted when you do not use the features they support. After loading Bubble, its basic `say [MESSAGE]` and `think [MESSAGE]` blocks work immediately without a style definition. They select the built-in Bubble styles `say` and `think`, respectively. Each style binds its body shape and tail/trail shape as one visual choice, and both use the reserved text profile `default`. Use `define bubble style` and `show [MESSAGE] with bubble style [STYLE]` only when you need a named custom style. Other named text styles and every explicit body, placement, media, reveal, or motion setting select the custom profile.
|
|
270
324
|
|
|
271
325
|
```text
|
|
272
|
-
#
|
|
273
|
-
https://
|
|
326
|
+
# Add only when using portraits, blink, lip-sync, continue, or audio
|
|
327
|
+
https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
|
|
274
328
|
|
|
275
|
-
#
|
|
276
|
-
https://
|
|
329
|
+
# Add Async Input for the integrated wait block
|
|
330
|
+
https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
|
|
277
331
|
|
|
278
|
-
#
|
|
279
|
-
https://
|
|
280
|
-
https://unpkg.com/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js
|
|
332
|
+
# Add Runtime Expression for finish or the integrated wait block
|
|
333
|
+
https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
|
|
281
334
|
|
|
282
|
-
# Bubble
|
|
283
|
-
https://
|
|
335
|
+
# Bubble (always load last)
|
|
336
|
+
https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js
|
|
284
337
|
```
|
|
285
338
|
|
|
286
|
-
TurboWarp
|
|
339
|
+
TurboWarp custom extensions load JavaScript from URLs, so a network connection is required the first time they are loaded. For an unsandboxed development URL, TurboWarp requires the server origin to be exactly `http://localhost:8000/`; `127.0.0.1`, `0.0.0.0`, and other ports do not receive this exception. From the repository root, run `python3 -m http.server 8000`, then load `http://localhost:8000/dist/turbowarp-bubble.js`. Alternatively, choose the custom-extension file or text input and enable **Run extension without sandbox**. The extension does not work when opened directly with `file://` or when run as a sandboxed extension. See [TurboWarp's unsandboxed extension documentation](https://docs.turbowarp.org/development/extensions/unsandboxed) for the host restrictions.
|
|
340
|
+
|
|
341
|
+
#### Scratch compatibility
|
|
287
342
|
|
|
288
|
-
|
|
343
|
+
TurboWarp Bubble cannot be used directly as a custom extension in the official Scratch editor (Scratch 3.0). The official Scratch editor does not expose TurboWarp's unsandboxed extension, internal renderer, or target drawable APIs. Adding the URL from this README to a Scratch `.sb3` project does not register Bubble's blocks.
|
|
289
344
|
|
|
290
|
-
|
|
345
|
+
Support by environment is summarized below.
|
|
291
346
|
|
|
292
|
-
|
|
347
|
+
| Environment | Usage | Support |
|
|
348
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------- |
|
|
349
|
+
| TurboWarp Editor | Load `dist/turbowarp-bubble.js` as an unsandboxed custom extension | Supported |
|
|
350
|
+
| TurboWarp Packager / compatible runtime | Load it in an environment that provides unsandboxed custom extensions and the renderer API | Supported (verify in each environment) |
|
|
351
|
+
| Official Scratch editor | Load it as an official or sandboxed extension | Not supported |
|
|
352
|
+
| Custom web application / host | Use the npm Composition API or TurboWarp adapter from JavaScript | Supported |
|
|
293
353
|
|
|
294
|
-
|
|
295
|
-
| ------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
|
|
296
|
-
| TurboWarp Editor | `dist/turbowarp-bubble.js`をunsandboxedカスタム拡張機能として読み込む | 対応 |
|
|
297
|
-
| TurboWarp Packager/互換runtime | unsandboxedカスタム拡張機能とrenderer APIが利用できる構成で読み込む | 対応(環境ごとに確認が必要) |
|
|
298
|
-
| Scratch公式エディター | 公式拡張機能またはサンドボックス拡張機能として読み込む | 非対応 |
|
|
299
|
-
| 独自Webアプリ/ホスト | npmのcomposition APIまたはTurboWarp adapterをJavaScriptから利用する | 対応 |
|
|
354
|
+
To use Bubble in another Scratch-compatible runtime, that runtime must implement the same unsandboxed APIs and renderer contract as TurboWarp. In a custom web application, use `@kubohiroya/turbowarp-bubble/composition` or `@kubohiroya/turbowarp-bubble/turbowarp-adapter` instead of the TurboWarp block extension.
|
|
300
355
|
|
|
301
|
-
|
|
356
|
+
Bubble owns a display for each calling sprite, clone, or Stage. With the default backend, the SVG body, text, expression base, blink layer, lip-sync layer, and continue icon are created as layers in the shared overlay DOM, so you do not need to add layer sprites to the project. The Stage can display only styles that use background-relative placement.
|
|
302
357
|
|
|
303
|
-
|
|
358
|
+
#### Available blocks
|
|
304
359
|
|
|
305
|
-
|
|
360
|
+
| Block | Behavior |
|
|
361
|
+
| -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
362
|
+
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Defines or replaces a Bubble style |
|
|
363
|
+
| `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Sets an Actor-relative direction/angle or background-relative region |
|
|
364
|
+
| `set portrait base [ASSET] for bubble style [STYLE]` | Sets the portrait base; an empty value removes the entire portrait |
|
|
365
|
+
| `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | Sets portrait placement, local transform, and rounded corners |
|
|
366
|
+
| `set bubble distance [DISTANCE] for bubble style [STYLE]` | Sets the distance from Actor bounds to the tail tip |
|
|
367
|
+
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Selects one of ten inseparable SVG body + tail/trail pairs |
|
|
368
|
+
| `set bubble tail length [LENGTH] for bubble style [STYLE]` | Sets the nominal length from the body border to the tail tip |
|
|
369
|
+
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Sets the body offset and whole-Bubble scale |
|
|
370
|
+
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets blink frames and interval |
|
|
371
|
+
| `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets lip-sync frames and interval |
|
|
372
|
+
| `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Sets the animation shown in `awaiting-continue` |
|
|
373
|
+
| `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | Configures CHARACTER/WORD/LINE/BLOCK progressive reveal |
|
|
374
|
+
| `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | Configures WORD delimiters and their visibility |
|
|
375
|
+
| `set bubble reveal sound [ASSET] for bubble style [STYLE]` | Sets the per-unit reveal sound |
|
|
376
|
+
| `set bubble voice [ASSET] for bubble style [STYLE]` | Sets full voice played when display starts |
|
|
377
|
+
| `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | Reveals remaining units and waits for a condition or timeout |
|
|
378
|
+
| `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configures the show animation |
|
|
379
|
+
| `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configures the hide animation |
|
|
380
|
+
| `animate this bubble [MOTION]` | Plays a whole-Bubble animation |
|
|
381
|
+
| `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shakes the complete Bubble surface |
|
|
382
|
+
| `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Applies relative-scale cycles to the Bubble |
|
|
383
|
+
| `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transitions the Bubble outline |
|
|
384
|
+
| `say [MESSAGE]` | Uses built-in style `say`: speech body and speech tail |
|
|
385
|
+
| `think [MESSAGE]` | Uses built-in style `think`: thought body and round trail |
|
|
386
|
+
| `show [MESSAGE] with bubble style [STYLE]` | Shows the body and tail/trail pair owned by the selected style |
|
|
387
|
+
| `set this bubble animation mode [MODE]` | Selects `talking`, `awaiting-continue`, or `idle` |
|
|
388
|
+
| `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Waits for a Runtime Expression condition or optional timeout |
|
|
389
|
+
| `close this bubble` | Releases this target's Bubble and owned resources |
|
|
390
|
+
| `Bubble version` | Returns the implementation version |
|
|
306
391
|
|
|
307
|
-
|
|
308
|
-
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
309
|
-
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義し、SVG Textで定義した文字style名を関連付ける |
|
|
310
|
-
| `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
|
|
311
|
-
| `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
|
|
312
|
-
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
|
|
313
|
-
| `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
|
|
314
|
-
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含むBubble全体の拡大率を設定する |
|
|
315
|
-
| `set portrait base [ASSET] for bubble style [STYLE]` | 表情ベース画像を設定する。空文字でportrait全体を解除する |
|
|
316
|
-
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分を設定する。空リストで解除する |
|
|
317
|
-
| `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
|
|
318
|
-
| `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
|
|
319
|
-
| `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始または置換する |
|
|
320
|
-
| `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始または置換する |
|
|
321
|
-
| `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を切り替える |
|
|
322
|
-
| `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | 条件成立またはtimeoutまでBubbleを表示したまま待つ |
|
|
323
|
-
| `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
|
|
324
|
-
| `Bubble version` | 実装versionを返す |
|
|
392
|
+
`ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and timeouts accept zero; a zero reveal interval disables automatic advance, while a zero timeout disables the time limit.
|
|
325
393
|
|
|
326
|
-
`
|
|
394
|
+
Bubble provides two built-in Bubble styles. `say` owns the speech body and speech tail; `think` owns the thought body and round trail. The body and tail/trail are one visual-style choice rather than independently selected properties. The matching short block selects each style automatically, so neither a style-definition block nor a style input is required. Both styles use the reserved text profile `default`: 14px Helvetica, 16px line height, a 170px maximum line width, 50px minimum text width, 10px padding, 16px corners, a white fill, and Scratch text/stroke colors. The 4px SVG stroke is painted before the white fill, which covers its inner half and leaves the same thin visible outline as TurboWarp's standard bubble. The profile starts on the Actor's right, flips to the left only when that side fits, follows Actor bounds, fences the Stage top and sides, formats numeric block inputs like Scratch, limits text to 330 characters, and closes on an empty block input.
|
|
327
395
|
|
|
328
|
-
|
|
396
|
+
##### TurboWarp standard comparison
|
|
397
|
+
|
|
398
|
+
The following screenshots were captured from the same TurboWarp Editor project with the English UI, a `Cat` sprite at `x=-80`, `y=0`, size `80%`, a white Stage, and matching `Hello!` / `Hmm...` inputs. The left column runs TurboWarp's standard Looks blocks. The right column runs Bubble's basic blocks with their matching built-in `say` / `think` styles; no definition or setter block is used.
|
|
399
|
+
|
|
400
|
+

|
|
401
|
+
|
|
402
|
+
The Stage comparison shows the right-side placement, content-sized body, and the speech tail or thought trail pointing back toward the Actor in each implementation. Bubble draws an independent SVG surface, so the screenshot is the visual reference for its renderer output rather than a reused image of TurboWarp's native bubble.
|
|
403
|
+
|
|
404
|
+

|
|
405
|
+
|
|
406
|
+
The block comparison shows the no-setup basic path and the unified custom-style block. Bubble's short `say` and `think` blocks automatically use the matching built-in styles; the callout shows each inseparable body-plus-tail/trail pair, maps both to the reserved text profile `default`, and lists the shared metrics. Named custom styles use `show [MESSAGE] with bubble style [STYLE]`, so the display operation does not select a second, potentially conflicting kind. The former styled say/think opcodes remain hidden compatibility definitions for saved projects.
|
|
407
|
+
|
|
408
|
+
Any explicit style-setting block—or a text style name other than `default`—selects the existing custom profile. Within that profile the omitted visual style is `NORMAL` and the omitted placement is `up-right`; explicit visual styles, placement, distance, tail length, offsets, portrait, continue indicator, reveal, audio, and motion retain their existing behavior. With the default `svg-overlay` backend, the selected body is an SVG DOM layer in the shared overlay root. Explicit `scratch-render` mode instead uses an SVG skin and renderer drawable. Closing or replacing a Bubble, stopping its target, or disposing the runtime releases whichever resources the selected backend owns.
|
|
329
409
|
|
|
330
410
|
#### Placement
|
|
331
411
|
|
|
332
|
-
`PLACEMENT
|
|
412
|
+
`PLACEMENT` configures the custom profile and has two families: Actor-relative and background-relative. Once placement or another style option is explicitly configured, the custom-profile default is `up-right`. The untouched basic profile instead uses Scratch's right-first, fit-dependent left flip.
|
|
333
413
|
|
|
334
|
-
- Actor
|
|
335
|
-
-
|
|
414
|
+
- Actor-relative: one of 16 canonical direction names, a compass alias, or an angle from 0 to 360 degrees following Scratch directions. `0` is up, `90` is right, `180` is down, `270` is left, and `360` is normalized to `0`. Arbitrary angles are not rounded to one of the 16 named directions.
|
|
415
|
+
- Background-relative: `HEADER_LIKE`, `CENTER`, or `FOOTER_LIKE`. These center the Bubble horizontally at the top, center, or bottom of the Stage safe area and do not depend on the Actor's position, bounds, or visibility.
|
|
336
416
|
|
|
337
|
-
Actor
|
|
417
|
+
The 16 canonical Actor-relative direction names are listed below. Aliases are case-insensitive and are converted to their canonical names.
|
|
338
418
|
|
|
339
|
-
|
|
|
419
|
+
| Canonical name | Compass alias | Canonical name | Compass alias |
|
|
340
420
|
| ------------------ | ----------------- | ---------------- | ----------------- |
|
|
341
421
|
| `up` | `north` | `down` | `south` |
|
|
342
422
|
| `up-up-right` | `north-northeast` | `down-down-left` | `south-southwest` |
|
|
@@ -347,28 +427,28 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
|
|
|
347
427
|
| `down-right` | `southeast` | `up-left` | `northwest` |
|
|
348
428
|
| `down-down-right` | `south-southeast` | `up-up-left` | `north-northwest` |
|
|
349
429
|
|
|
350
|
-

|
|
351
431
|
|
|
352
|
-
|
|
432
|
+
Each of the 16 directions in the figure shows an Actor, the actual Bubble outline, its tail, and its text. The body and tail form one path through a JSClipper union, so there is no internal border line at the join. The three background-relative examples show the Stage border, safe area, outline dimensions, horizontal centerline, and reference edge or center. Both the figure and the rendered body in the TurboWarp Editor are generated from the shared `renderBubbleSvg`.
|
|
353
433
|
|
|
354
|
-

|
|
355
435
|
|
|
356
|
-
Actor
|
|
436
|
+
Actor-relative `distance` runs from the Actor's Stage-coordinate AABB (the axis-aligned bounding box represented by the top, bottom, left, and right values returned by the renderer's `getBoundsForBubble()`) to the tail tip. Its default is `12`. `tail length` runs from the body border at the normal position to the tail tip. Its default is `18`.
|
|
357
437
|
|
|
358
|
-
`offset x/y/scale
|
|
438
|
+
The default `offset x/y/scale` is `[0, 0, 100]`. Positive x points right, and positive y points up. Scale applies as one transformation to the Bubble outline, SVG Text content and font size, expression images, continue icon, and inner padding. When only scale changes, Bubble moves the body center away from the Actor by the radius of the size increase, preserving the Actor-side gap. It then applies the x/y offset and regenerates the tail toward its fixed tip, so the resulting length after the offset can differ from `tail length`. At Stage edges, the full Bubble is clamped to remain onscreen. These three settings are ignored for background-relative placement.
|
|
359
439
|
|
|
360
|
-
#### Portrait
|
|
440
|
+
#### Portrait, blink, and lip-sync
|
|
361
441
|
|
|
362
|
-
portrait
|
|
442
|
+
A portrait is a set of layered, pre-aligned transparent images. Prepare the base and variant images with the same canvas size and center point to update only the eyes and mouth without redrawing the face.
|
|
363
443
|
|
|
364
444
|
```mermaid
|
|
365
445
|
flowchart TB
|
|
366
446
|
bubble[Bubble surface]
|
|
367
447
|
body[Bubble body / text]
|
|
368
|
-
base[portraitBase\
|
|
369
|
-
blink[portraitBlink\
|
|
370
|
-
lipsync[portraitLipSync\
|
|
371
|
-
continue[continueIndicator\
|
|
448
|
+
base[portraitBase\nface, hair, and outline]
|
|
449
|
+
blink[portraitBlink\nblink variant]
|
|
450
|
+
lipsync[portraitLipSync\nlip-sync variant]
|
|
451
|
+
continue[continueIndicator\nnext icon]
|
|
372
452
|
bubble --> body
|
|
373
453
|
bubble --> base
|
|
374
454
|
base --> blink
|
|
@@ -376,85 +456,95 @@ flowchart TB
|
|
|
376
456
|
bubble --> continue
|
|
377
457
|
```
|
|
378
458
|
|
|
379
|
-
|
|
|
459
|
+
| Layer | Behavior while displayed | Configuration block / API |
|
|
380
460
|
| ------------------- | ------------------------------------------------------ | ------------------------------------------- |
|
|
381
|
-
| `portraitBase` |
|
|
382
|
-
| `portraitBlink` | `talking
|
|
383
|
-
| `portraitLipSync` | `talking
|
|
384
|
-
| `continueIndicator` | `awaiting-continue
|
|
461
|
+
| `portraitBase` | Base image that remains visible | `set portrait base` / `portrait.base` |
|
|
462
|
+
| `portraitBlink` | Loops in `talking`, `awaiting-continue`, and `idle` | `set blink frames` / `portrait.blink` |
|
|
463
|
+
| `portraitLipSync` | Loops only in `talking`; stops and hides while waiting | `set lip-sync frames` / `portrait.lipSync` |
|
|
464
|
+
| `continueIndicator` | Loops only in `awaiting-continue` | `set continue frames` / `continueIndicator` |
|
|
385
465
|
|
|
386
|
-
|
|
466
|
+
Blink and lip-sync can each use a single still image. The keyword `lip-sync` consistently means a mouth-expression variant, not the entire act of speaking. `continue` is an icon animation that represents waiting for input; it does not execute the JavaScript `continue` statement.
|
|
387
467
|
|
|
388
|
-

|
|
389
469
|
|
|
390
470
|
#### Bubble animation
|
|
391
471
|
|
|
392
|
-
Bubble
|
|
472
|
+
Bubble treats image-frame loops (blink, lip-sync, and continue) separately from transformations of the Bubble surface itself. The currently published `set this bubble animation mode` switches the behavior mode of the frame loops. Surface transformations form a general animation specification applied to the same surface.
|
|
393
473
|
|
|
394
474
|
```mermaid
|
|
395
475
|
flowchart LR
|
|
396
|
-
start[
|
|
397
|
-
in --> visible[
|
|
398
|
-
visible --> shake[shake\
|
|
399
|
-
visible --> explode[explode\
|
|
400
|
-
visible --> shape[animateBubbleShape\
|
|
476
|
+
start[Show] --> in[Show animation\nfadeIn / floatIn / zoomIn / riseUp]
|
|
477
|
+
in --> visible[Visible]
|
|
478
|
+
visible --> shake[shake\ndirection, count, and ease]
|
|
479
|
+
visible --> explode[explode\nrelative size, count, and ease]
|
|
480
|
+
visible --> shape[animateBubbleShape\nspeed and duration]
|
|
401
481
|
visible --> waiting[awaiting-continue]
|
|
402
|
-
waiting --> out[
|
|
403
|
-
out --> released[
|
|
482
|
+
waiting --> out[Hide animation\nfadeOut / floatOut / zoomOut / sink]
|
|
483
|
+
out --> released[Close and release resources]
|
|
404
484
|
```
|
|
405
485
|
|
|
406
|
-
#####
|
|
486
|
+
##### Show and hide
|
|
487
|
+
|
|
488
|
+
Following PowerPoint terminology as a reference, Bubble calls these “show animations” and “hide animations.” Show animations include `fadeIn`, `floatIn`, `zoomIn`, and `riseUp`; hide animations include `fadeOut`, `floatOut`, `zoomOut`, and `sink`. They are not restricted to `RESERVED`. They can also be applied to a Bubble whose displayed size changes under `DYNAMIC`; a hide animation calculates its endpoint from the current outline.
|
|
407
489
|
|
|
408
|
-
|
|
490
|
+
To remove a Bubble, run `close this bubble`. It applies the configured hide animation and then releases the display and its owned resources. The hide-animation setter configures the exit effect but does not hide anything by itself. The built-in `say` and `think` blocks also close on an empty message for TurboWarp compatibility. There is no separate `hide` block because the operation destroys the current display instead of retaining hidden state.
|
|
409
491
|
|
|
410
|
-
#####
|
|
492
|
+
##### Transformations while visible
|
|
411
493
|
|
|
412
|
-
- `shake + direction + count + ease`:
|
|
413
|
-
- `explode + relativeScale + count + ease`:
|
|
414
|
-
- `animateBubbleShape + speed + duration`: `THINKING
|
|
494
|
+
- `shake + direction + count + ease`: Shakes the entire Bubble in the selected direction. `direction` can be horizontal, vertical, or diagonal; `count` is the number of round trips, and `ease` is the timing curve for each round trip.
|
|
495
|
+
- `explode + relativeScale + count + ease`: Repeatedly scales up and back down relative to the current size. The same relative transformation applies to the entire surface, including the portrait and Text.
|
|
496
|
+
- `animateBubbleShape + speed + duration`: Changes among outlines such as `THINKING`, `DREAMING`, `YELLING`, `WAVY`, and `WHISPERING` at the selected speed and for the selected duration. This separates changes to `visualStyle` from active surface animation.
|
|
415
497
|
|
|
416
|
-
TurboWarp adapter
|
|
498
|
+
The TurboWarp adapter advances each animation on scheduler ticks of up to 16 ms and applies `ease` to each frame's progress. The default SVG overlay changes the shared surface group's opacity and transform; explicit `scratch-render` mode maps the same motions to renderer effects, position, and scale. `shake` performs the requested number of round trips, while `explode` repeatedly enlarges and restores the Text, portrait, and body together. A `shake` or `explode` without `durationSeconds` uses a default duration based on its count.
|
|
417
499
|
|
|
418
|
-
`animateBubbleShape
|
|
500
|
+
`animateBubbleShape` cross-fades the current and requested outlines generated by `renderBubbleSvg` on every frame. The overlay backend rebuilds only the allowlisted body elements, while `scratch-render` updates the body skin; neither path regenerates the Text or portrait. `speed` is the shape-transition speed multiplier within the selected duration.
|
|
419
501
|
|
|
420
|
-
|
|
502
|
+
Animations integrate with the lifecycle of `show`, `handle.animate()`, `handle.setAnimationMode()`, `handle.updateStyle()`, and `handle.close()`. When a new Bubble replaces the same `actorKey`, the old animation timers and backend-owned rendering resources are released first. `shake` accepts `ease`; `explode` accepts `relativeScale`, `count`, and `ease`; and `animateBubbleShape` accepts `speed` and `durationSeconds`.
|
|
421
503
|
|
|
422
504
|
#### Animation mode
|
|
423
505
|
|
|
424
|
-
|
|
|
425
|
-
| ------------------- |
|
|
426
|
-
| `talking` |
|
|
427
|
-
| `awaiting-continue` |
|
|
428
|
-
| `idle` |
|
|
506
|
+
| Mode | Blink | Lip-sync | Continue frames |
|
|
507
|
+
| ------------------- | ------- | ------------------ | ------------------ |
|
|
508
|
+
| `talking` | Running | Running | Hidden |
|
|
509
|
+
| `awaiting-continue` | Running | Stopped and hidden | Looping |
|
|
510
|
+
| `idle` | Running | Stopped and hidden | Stopped and hidden |
|
|
429
511
|
|
|
430
|
-
`say
|
|
512
|
+
The `say` and `think` blocks start displaying in `talking` mode and immediately proceed to the next block. `wait with this bubble ...` automatically moves to `awaiting-continue` and evaluates runtime variables updated by Async Input through Runtime Expression. When the condition succeeds or the timeout expires, it moves to `idle` and proceeds to the next block.
|
|
431
513
|
|
|
432
|
-
####
|
|
514
|
+
#### Block example
|
|
433
515
|
|
|
434
516
|
```text
|
|
435
|
-
define bubble style [hero-dialogue] using text style [
|
|
517
|
+
define bubble style [hero-dialogue] using text style [default]
|
|
436
518
|
set bubble placement [up-right] for bubble style [hero-dialogue]
|
|
437
519
|
set bubble distance [12] for bubble style [hero-dialogue]
|
|
438
520
|
set bubble visual style [NORMAL] for bubble style [hero-dialogue]
|
|
439
521
|
set bubble tail length [18] for bubble style [hero-dialogue]
|
|
440
522
|
set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
|
|
441
523
|
set portrait base [HeroFace] for bubble style [hero-dialogue]
|
|
524
|
+
set portrait [top-left] offset x [-4] y [6] zoom [120] % corner radius [12] px for bubble style [hero-dialogue]
|
|
442
525
|
set blink frames [HeroEyesOpen,HeroEyesClosed] every [0.4] seconds for bubble style [hero-dialogue]
|
|
443
526
|
set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
|
|
444
527
|
set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
|
|
528
|
+
set bubble reveal unit [WORD] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
|
|
529
|
+
set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
|
|
530
|
+
set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
|
|
531
|
+
set bubble voice [HeroVoice] for bubble style [hero-dialogue]
|
|
532
|
+
set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
|
|
533
|
+
set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
|
|
445
534
|
set runtime variable [input] to []
|
|
446
535
|
listen for key [Space] set runtime var [input] to [pressed]
|
|
447
536
|
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
448
|
-
|
|
449
|
-
|
|
537
|
+
show [Set/sail!] with bubble style [hero-dialogue]
|
|
538
|
+
finish [WORD] with condition [input == "pressed"] or timeout after [10] seconds
|
|
539
|
+
shake this bubble direction [90] count [2] ease [easeInOut]
|
|
450
540
|
close this bubble
|
|
451
541
|
```
|
|
452
542
|
|
|
453
|
-
|
|
543
|
+
Bubble automatically releases its owned timers, overlay DOM, and image leases when the project starts or stops, a target sprite or clone stops, or the runtime is disposed. When `scratch-render` is explicitly selected, Bubble also releases its owned SVG skins and drawables as before. If a dependency extension has not been loaded, the returned error includes the required npm package name.
|
|
454
544
|
|
|
455
545
|
### Composition API
|
|
456
546
|
|
|
457
|
-
TurboWarp runtime
|
|
547
|
+
Hosts that connect to a TurboWarp runtime renderer can use the public adapter. By default, it uses the SVG Text 0.8.1 named-style handoff when a standalone extension is loaded, otherwise its bundled layout composition, together with an SVG overlay. Load Asset Manager in addition only when using image portraits, lip-sync, continue indicators, or audio assets.
|
|
458
548
|
|
|
459
549
|
```ts
|
|
460
550
|
import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
|
|
@@ -462,7 +552,7 @@ import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/t
|
|
|
462
552
|
const bubbles = createTurboWarpBubbleComposition(runtime);
|
|
463
553
|
```
|
|
464
554
|
|
|
465
|
-
|
|
555
|
+
If the host implements the rendering surface, use the lower-level Composition API below.
|
|
466
556
|
|
|
467
557
|
```ts
|
|
468
558
|
import {
|
|
@@ -485,23 +575,23 @@ const bubbles = createBubbleComposition({
|
|
|
485
575
|
});
|
|
486
576
|
```
|
|
487
577
|
|
|
488
|
-
`declare
|
|
578
|
+
The `declare` lines are type declarations that keep the example short. In a real host, implement and pass `BubbleTextCapability` (text layout, rendering, measurement, and release), `BubbleImageCapability` (image-name resolution), `BubbleAudioCapability` (audio playback), and `BubbleSurfaceFactory` (creation of targets for the outline, text, and portrait). When using `@kubohiroya/turbowarp-svg-text/composition`, adapt it with `createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))` for a skin-based host or `createSvgTextOverlayTextCapability(createSvgTextLayoutComposition())` for an SVG overlay. With a TurboWarp runtime, use `createTurboWarpBubbleComposition(runtime)` instead of implementing these pieces individually.
|
|
489
579
|
|
|
490
|
-
|
|
580
|
+
For text-only display, omit the Asset Manager import, `createAssetManagerComposition()`, and the `imageResolver` property. Asset Manager is a media path not only for images but also for registering and playing full voice clips, per-unit reveal sounds, and finish cues through `audio.voice`, `audio.reveal`, and `audio.finish`. The TurboWarp adapter connects the stock Asset Manager lazily; a lower-level Composition API host can instead inject its own `audio` capability.
|
|
491
581
|
|
|
492
|
-
`createSurface
|
|
582
|
+
The surface returned by `createSurface` has the following targets.
|
|
493
583
|
|
|
494
|
-
surface
|
|
584
|
+
The surface also implements `updateStyle(style)` so it can update the Bubble's position, shape, and size. To change the style of a displayed Bubble, call `updateStyle(style)` on the returned handle. If the updated style uses an image layer, the surface must have returned the corresponding target in advance.
|
|
495
585
|
|
|
496
|
-
- `text`: `textCapability
|
|
497
|
-
- `portraitBase`:
|
|
498
|
-
- `portraitBlink`:
|
|
499
|
-
- `portraitLipSync`:
|
|
500
|
-
- `continueIndicator`:
|
|
586
|
+
- `text`: Target to which `textCapability` applies text layout
|
|
587
|
+
- `portraitBase`: Target for the character-expression base image
|
|
588
|
+
- `portraitBlink`: Target for the blink variant
|
|
589
|
+
- `portraitLipSync`: Target for the lip-sync variant
|
|
590
|
+
- `continueIndicator`: Target for the “next” icon
|
|
501
591
|
|
|
502
|
-
|
|
592
|
+
Image-layer target IDs must be distinct from one another. Targets for layers unused by the style can be omitted.
|
|
503
593
|
|
|
504
|
-
####
|
|
594
|
+
#### Styles and display
|
|
505
595
|
|
|
506
596
|
```ts
|
|
507
597
|
bubbles.defineStyle({
|
|
@@ -536,6 +626,7 @@ bubbles.defineStyle({
|
|
|
536
626
|
audio: {
|
|
537
627
|
voice: "HeroVoice",
|
|
538
628
|
reveal: "Typewriter",
|
|
629
|
+
finish: "Ready",
|
|
539
630
|
},
|
|
540
631
|
showAnimation: { name: "fadeIn", durationSeconds: 0.2 },
|
|
541
632
|
hideAnimation: { name: "fadeOut", durationSeconds: 0.2 },
|
|
@@ -546,26 +637,26 @@ bubbles.defineStyle({
|
|
|
546
637
|
textStyle: "dialogue-text",
|
|
547
638
|
placement: "FOOTER_LIKE",
|
|
548
639
|
maxWidth: 320,
|
|
549
|
-
textLocale: "
|
|
640
|
+
textLocale: "en",
|
|
550
641
|
});
|
|
551
642
|
|
|
552
643
|
const bubble = await bubbles.show({
|
|
553
644
|
actor: heroTarget,
|
|
554
645
|
actorKey: "Hero",
|
|
555
646
|
kind: "say",
|
|
556
|
-
text: "
|
|
647
|
+
text: "Set sail!",
|
|
557
648
|
styleName: "hero-dialogue",
|
|
558
649
|
});
|
|
559
650
|
```
|
|
560
651
|
|
|
561
|
-
`show
|
|
652
|
+
The initial animation mode for `show` is `talking`. Blink continues while the Bubble is displayed, and lip-sync runs. After the full text is visible, change the mode to `awaiting-continue` when the application begins waiting for the user to choose “next.”
|
|
562
653
|
|
|
563
654
|
```ts
|
|
564
655
|
await bubble.setAnimationMode("awaiting-continue");
|
|
565
|
-
//
|
|
656
|
+
// Stop and hide lip-sync, then loop the "next" icon.
|
|
566
657
|
|
|
567
658
|
await bubble.setAnimationMode("idle");
|
|
568
|
-
//
|
|
659
|
+
// Keep the Bubble visible, but stop lip-sync and the "next" icon.
|
|
569
660
|
|
|
570
661
|
await bubble.revealNext();
|
|
571
662
|
await bubble.revealAll();
|
|
@@ -584,19 +675,19 @@ await bubble.finish({
|
|
|
584
675
|
await bubble.close();
|
|
585
676
|
```
|
|
586
677
|
|
|
587
|
-
|
|
678
|
+
The returned handle's `setText(text)` updates the body text on the same surface and can be used for progressive text display. `handle.updateStyle(style)` applies a style change immediately to a displayed Bubble. Showing a new Bubble with the same `actorKey` completely destroys and then replaces the previous Bubble. `releaseTarget`, `releaseAll`, and `dispose` also release owned timers, text-capability targets, and surfaces. State is not shared between compositions.
|
|
588
679
|
|
|
589
|
-
##
|
|
680
|
+
## License and source code
|
|
590
681
|
|
|
591
|
-
|
|
682
|
+
The Source Code Form of this package is provided under the terms of the [MPL-2.0](https://www.mozilla.org/MPL/2.0/). The corresponding source code is available from the [GitHub repository](https://github.com/kubohiroya/turbowarp-bubble). Source code corresponding to JavaScript bundles distributed through npm and CDNs can be found at the same package version in this repository.
|
|
592
683
|
|
|
593
|
-
|
|
684
|
+
Copyright notices and license terms for third-party software incorporated into the distribution are collected in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
|
|
594
685
|
|
|
595
|
-
##
|
|
686
|
+
## Development
|
|
596
687
|
|
|
597
688
|
```sh
|
|
598
689
|
pnpm install
|
|
599
690
|
pnpm check
|
|
600
691
|
```
|
|
601
692
|
|
|
602
|
-
`pnpm check
|
|
693
|
+
`pnpm check` runs type checking, linting, formatting, unit tests, distribution inspection, external-consumer type checking, and an npm pack dry run.
|