@kubohiroya/turbowarp-bubble 0.2.0 → 0.3.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.
@@ -16,6 +16,16 @@ export interface RenderBubbleSvgInput {
16
16
  readonly fontFamily?: string;
17
17
  readonly fontSize?: number;
18
18
  readonly title?: string;
19
+ /**
20
+ * Cross-fades two Bubble body geometries while keeping the text layer
21
+ * stable. This is used by the runtime adapter for animateBubbleShape.
22
+ */
23
+ readonly shapeTransition?: BubbleShapeTransition;
24
+ }
25
+ export interface BubbleShapeTransition {
26
+ readonly from: BubbleVisualStyle;
27
+ readonly to: BubbleVisualStyle;
28
+ readonly progress: number;
19
29
  }
20
30
  export interface BubbleBodyCenterOffsetInput {
21
31
  readonly style: BubbleVisualStyle;
@@ -1,12 +1,36 @@
1
1
  import { type BubblePlacement, type BubblePlacementInput } from "./placement.js";
2
2
  import { type BubbleOffset, type BubbleOffsetInput } from "./actor-transform.js";
3
3
  import { type BubbleVisualStyle } from "./bubble-svg.js";
4
+ import { type BubbleRevealInput, type BubbleRevealUnit, type NormalizedBubbleReveal } from "./reveal.js";
4
5
  export { UnicodeLineBreakProvider, wrapText, type LineBreakOpportunity, type LineBreakProvider, type TextWidthMeasurer, type WrappedTextLayout, type WrappedTextLine, type WrapTextInput, } from "./text-layout.js";
5
6
  export { bubbleBackgroundRegions, bubbleDirectionAliases, bubbleDirectionNames, defaultBubblePlacementInput, normalizeBubblePlacement, type BubbleActorPlacement, type BubbleBackgroundPlacement, type BubbleBackgroundRegion, type BubbleDirectionAlias, type BubbleDirectionName, type BubblePlacement, type BubblePlacementInput, } from "./placement.js";
6
7
  export { actorRelativeBubbleCenter, defaultBubbleDistance, defaultBubbleOffset, defaultBubbleTailLength, normalizeBubbleDistance, normalizeBubbleOffset, normalizeBubbleTailLength, type ActorBounds, type ActorRelativeCenterInput, type BubbleOffset, type BubbleOffsetInput, } from "./actor-transform.js";
7
- export { bubbleBodyCenterOffset, bubbleVisualStyles, renderBubbleSvg, type BubbleBodyCenterOffsetInput, type BubbleVisualStyle, type RenderBubbleSvgInput, } from "./bubble-svg.js";
8
+ export { bubbleBodyCenterOffset, bubbleVisualStyles, renderBubbleSvg, type BubbleBodyCenterOffsetInput, type BubbleShapeTransition, type BubbleVisualStyle, type RenderBubbleSvgInput, } from "./bubble-svg.js";
9
+ export { bubbleRevealUnits, normalizeBubbleReveal, revealedBubbleText, splitBubbleText, type BubbleRevealInput, type BubbleRevealLayout, type BubbleRevealUnit, type NormalizedBubbleReveal, } from "./reveal.js";
8
10
  export type BubbleKind = "say" | "think";
9
11
  export type BubbleAnimationMode = "idle" | "talking" | "awaiting-continue";
12
+ export type BubbleEase = "linear" | "easeIn" | "easeOut" | "easeInOut";
13
+ export type BubbleMotionName = "fadeIn" | "fadeOut" | "floatIn" | "floatOut" | "zoomIn" | "zoomOut" | "riseUp" | "sink" | "shake" | "explode" | "animateBubbleShape";
14
+ export interface BubbleMotionInput {
15
+ readonly name: BubbleMotionName;
16
+ readonly durationSeconds?: number;
17
+ readonly ease?: BubbleEase;
18
+ readonly direction?: number | string;
19
+ readonly count?: number;
20
+ readonly relativeScale?: number;
21
+ readonly speed?: number;
22
+ readonly visualStyle?: BubbleVisualStyle;
23
+ }
24
+ export interface BubbleAudioInput {
25
+ readonly voice?: string;
26
+ readonly reveal?: string;
27
+ readonly finish?: string;
28
+ }
29
+ export interface BubbleFinishInput {
30
+ readonly unit?: BubbleRevealUnit;
31
+ readonly condition?: () => boolean | Promise<boolean>;
32
+ readonly timeoutSeconds?: number;
33
+ }
10
34
  export type BubbleLayer = "portraitBase" | "portraitBlink" | "portraitLipSync" | "continueIndicator";
11
35
  export interface BubbleFrameAnimationInput {
12
36
  readonly frames: ReadonlyArray<string>;
@@ -29,6 +53,12 @@ export interface BubbleStyleInput {
29
53
  readonly visualStyle?: BubbleVisualStyle;
30
54
  readonly portrait?: BubblePortraitInput;
31
55
  readonly continueIndicator?: BubbleFrameAnimationInput;
56
+ readonly reveal?: BubbleRevealInput;
57
+ readonly audio?: BubbleAudioInput;
58
+ /** Animation played when the Bubble drawable first becomes visible. */
59
+ readonly showAnimation?: BubbleMotionInput;
60
+ /** Animation played before the Bubble drawable is hidden. */
61
+ readonly hideAnimation?: BubbleMotionInput;
32
62
  }
33
63
  export interface BubbleFrameAnimation {
34
64
  readonly frames: ReadonlyArray<string>;
@@ -51,6 +81,10 @@ export interface BubbleStyle {
51
81
  readonly visualStyle: BubbleVisualStyle;
52
82
  readonly portrait?: BubblePortrait;
53
83
  readonly continueIndicator?: BubbleFrameAnimation;
84
+ readonly reveal?: NormalizedBubbleReveal;
85
+ readonly audio?: BubbleAudioInput;
86
+ readonly showAnimation?: BubbleMotionInput;
87
+ readonly hideAnimation?: BubbleMotionInput;
54
88
  }
55
89
  export interface BubbleAssetTarget {
56
90
  readonly id: string;
@@ -65,6 +99,8 @@ export interface BubbleAudioCapability {
65
99
  readonly playSound: (name: unknown, options?: Readonly<{
66
100
  untilDone?: boolean;
67
101
  }>) => Promise<void>;
102
+ readonly isRegistered?: (name: unknown) => boolean;
103
+ readonly getMimeType?: (name: unknown) => string;
68
104
  }
69
105
  export interface BubbleTextTarget {
70
106
  readonly drawableID: number;
@@ -95,6 +131,11 @@ export interface BubbleSurface {
95
131
  show(): void | Promise<void>;
96
132
  hide(): void | Promise<void>;
97
133
  dispose(): void | Promise<void>;
134
+ /** Optional host-native motion implementation. */
135
+ animate?(motion: BubbleMotionInput): void | Promise<void>;
136
+ /** Captures the currently rendered text size for RESERVED reveal layout. */
137
+ captureTextLayout?(): void;
138
+ clearTextLayout?(): void;
98
139
  }
99
140
  export interface BubbleSurfaceFactoryInput {
100
141
  readonly actor: unknown;
@@ -127,6 +168,7 @@ export interface ShowBubbleInput {
127
168
  readonly text: string;
128
169
  readonly styleName: string;
129
170
  readonly animationMode?: BubbleAnimationMode;
171
+ readonly reveal?: BubbleRevealInput;
130
172
  }
131
173
  export interface BubbleHandle {
132
174
  readonly actorKey: string;
@@ -135,6 +177,10 @@ export interface BubbleHandle {
135
177
  setText(text: string): Promise<void>;
136
178
  updateStyle(style: BubbleStyleInput): Promise<void>;
137
179
  setAnimationMode(mode: BubbleAnimationMode): Promise<void>;
180
+ revealNext(): Promise<boolean>;
181
+ revealAll(): Promise<void>;
182
+ finish(input?: BubbleFinishInput): Promise<void>;
183
+ animate(motion: BubbleMotionInput): Promise<void>;
138
184
  close(): Promise<void>;
139
185
  }
140
186
  export interface BubbleComposition {
@@ -0,0 +1,26 @@
1
+ export declare const bubbleRevealUnits: readonly ["CHARACTER", "WORD", "LINE", "BLOCK"];
2
+ export type BubbleRevealUnit = (typeof bubbleRevealUnits)[number];
3
+ export type BubbleRevealLayout = "DYNAMIC" | "RESERVED";
4
+ export interface BubbleRevealInput {
5
+ readonly unit: BubbleRevealUnit;
6
+ /** Characters used to separate WORD units. Whitespace is used by default. */
7
+ readonly delimiters?: string;
8
+ /** Keep WORD delimiters in the rendered text when true. */
9
+ readonly showDelimiters?: boolean;
10
+ readonly layout?: BubbleRevealLayout;
11
+ /** Automatically advance after this many seconds. Zero disables auto advance. */
12
+ readonly intervalSeconds?: number;
13
+ /** Optional named audio asset played once per revealed unit. */
14
+ readonly sound?: string;
15
+ }
16
+ export interface NormalizedBubbleReveal extends BubbleRevealInput {
17
+ readonly delimiters: string;
18
+ readonly showDelimiters: boolean;
19
+ readonly layout: BubbleRevealLayout;
20
+ readonly intervalSeconds: number;
21
+ readonly sound?: string;
22
+ }
23
+ export declare function normalizeBubbleReveal(value: unknown): NormalizedBubbleReveal;
24
+ /** Returns append-only chunks; joining the first n chunks gives the visible text. */
25
+ export declare function splitBubbleText(text: string, reveal: NormalizedBubbleReveal): readonly string[];
26
+ export declare function revealedBubbleText(chunks: readonly string[], count: number): string;
@@ -25,6 +25,8 @@ export interface TurboWarpBubbleRenderer {
25
25
  updateDrawableScale(drawableId: number, scale: [number, number]): void;
26
26
  updateDrawableSkinId(drawableId: number, skinId: number): void;
27
27
  updateDrawableVisible(drawableId: number, visible: boolean): void;
28
+ /** Scratch/TurboWarp's ghost effect is used to implement fade motions. */
29
+ updateDrawableEffect?(drawableId: number, effectName: string, value: number): void;
28
30
  setDrawableOrder?(drawableId: number, order: number, layerGroup: string, relative?: boolean): void;
29
31
  }
30
32
  export interface TurboWarpAssetManagerExtension {
@@ -28,10 +28,7 @@
28
28
  <ellipse cx="100" cy="267.4" rx="6.4799999999999995" ry="8.64" fill="#7c2945"/>
29
29
  </g>
30
30
  <g>
31
- <rect x="163" y="196" width="190" height="112" rx="28" fill="#fff4cc" stroke="#725a42" stroke-width="3"/>
32
- <path d="M 193 302 L 167 338 L 241 305 Z" fill="#fff4cc" stroke="#725a42" stroke-width="3" stroke-linejoin="round"/>
33
- <path d="M 189 308 H 245" stroke="#fff4cc" stroke-width="8"/>
34
- <text x="199" y="266" style="fill:#25283a;font-size:17px;font-weight:700">海へ出発!</text>
31
+ <g transform="translate(139 172)" data-bubble-renderer="canonical" data-bubble-style="NORMAL" data-bubble-tail-direction="270"><title>Animation mode Bubble preview</title><path data-animation-mode-bubble-path="union" d="M 24.0000 71.0000 L 24.0000 42.0000 L 24.2216 39.1842 L 24.8810 36.4377 L 25.9619 33.8282 L 27.4377 31.4199 L 29.2721 29.2721 L 31.4199 27.4377 L 33.8282 25.9619 L 36.4377 24.8810 L 39.1842 24.2216 L 42.0000 24.0000 L 196.0000 24.0000 L 198.8158 24.2216 L 201.5623 24.8810 L 204.1718 25.9619 L 206.5801 27.4377 L 208.7279 29.2721 L 210.5623 31.4199 L 212.0381 33.8282 L 213.1190 36.4377 L 213.7784 39.1842 L 214.0000 42.0000 L 214.0000 118.0000 L 213.7784 120.8158 L 213.1190 123.5623 L 212.0381 126.1718 L 210.5623 128.5801 L 208.7279 130.7279 L 206.5801 132.5623 L 204.1718 134.0381 L 201.5623 135.1190 L 198.8158 135.7784 L 196.0000 136.0000 L 42.0000 136.0000 L 39.1842 135.7784 L 36.4377 135.1190 L 33.8282 134.0381 L 31.4199 132.5623 L 29.2721 130.7279 L 27.4377 128.5801 L 25.9619 126.1718 L 24.8810 123.5623 L 24.2216 120.8158 L 24.0000 118.0000 L 24.0000 89.0000 L 6.0000 80.0000 Z" fill="#fff4cc" stroke="#6f5b45" stroke-width="3" stroke-linejoin="round" data-boolean-operation="union" data-tail-base-on-border="true" /><text x="119" y="85.95" text-anchor="middle" fill="#25283a" font-family="Noto Sans JP, sans-serif" font-size="17">海へ出発!</text></g>
35
32
 
36
33
  </g>
37
34
  <g transform="translate(0 0)">
@@ -63,10 +60,7 @@
63
60
  <path d="M 488.8 268.12 Q 496 271.72 503.2 268.12" fill="none" stroke="#7c2945" stroke-width="2.16" stroke-linecap="round"/>
64
61
  </g>
65
62
  <g>
66
- <rect x="559" y="196" width="190" height="112" rx="28" fill="#fff4cc" stroke="#725a42" stroke-width="3"/>
67
- <path d="M 589 302 L 563 338 L 637 305 Z" fill="#fff4cc" stroke="#725a42" stroke-width="3" stroke-linejoin="round"/>
68
- <path d="M 585 308 H 641" stroke="#fff4cc" stroke-width="8"/>
69
- <text x="595" y="266" style="fill:#25283a;font-size:17px;font-weight:700">海へ出発!</text>
63
+ <g transform="translate(535 172)" data-bubble-renderer="canonical" data-bubble-style="NORMAL" data-bubble-tail-direction="270"><title>Animation mode Bubble preview</title><path data-animation-mode-bubble-path="union" d="M 24.0000 71.0000 L 24.0000 42.0000 L 24.2216 39.1842 L 24.8810 36.4377 L 25.9619 33.8282 L 27.4377 31.4199 L 29.2721 29.2721 L 31.4199 27.4377 L 33.8282 25.9619 L 36.4377 24.8810 L 39.1842 24.2216 L 42.0000 24.0000 L 196.0000 24.0000 L 198.8158 24.2216 L 201.5623 24.8810 L 204.1718 25.9619 L 206.5801 27.4377 L 208.7279 29.2721 L 210.5623 31.4199 L 212.0381 33.8282 L 213.1190 36.4377 L 213.7784 39.1842 L 214.0000 42.0000 L 214.0000 118.0000 L 213.7784 120.8158 L 213.1190 123.5623 L 212.0381 126.1718 L 210.5623 128.5801 L 208.7279 130.7279 L 206.5801 132.5623 L 204.1718 134.0381 L 201.5623 135.1190 L 198.8158 135.7784 L 196.0000 136.0000 L 42.0000 136.0000 L 39.1842 135.7784 L 36.4377 135.1190 L 33.8282 134.0381 L 31.4199 132.5623 L 29.2721 130.7279 L 27.4377 128.5801 L 25.9619 126.1718 L 24.8810 123.5623 L 24.2216 120.8158 L 24.0000 118.0000 L 24.0000 89.0000 L 6.0000 80.0000 Z" fill="#fff4cc" stroke="#6f5b45" stroke-width="3" stroke-linejoin="round" data-boolean-operation="union" data-tail-base-on-border="true" /><text x="119" y="85.95" text-anchor="middle" fill="#25283a" font-family="Noto Sans JP, sans-serif" font-size="17">海へ出発!</text></g>
70
64
  <g transform="translate(0 0)">
71
65
  <path d="M 691 254 l 18 0 l -9 12 z" fill="#ff6680"/>
72
66
  <path d="M 691 273 l 18 0 l -9 12 z" fill="#d94b68"/>
@@ -101,10 +95,7 @@
101
95
  <path d="M 884.8 268.12 Q 892 271.72 899.2 268.12" fill="none" stroke="#7c2945" stroke-width="2.16" stroke-linecap="round"/>
102
96
  </g>
103
97
  <g>
104
- <rect x="955" y="196" width="190" height="112" rx="28" fill="#fff4cc" stroke="#725a42" stroke-width="3"/>
105
- <path d="M 985 302 L 959 338 L 1033 305 Z" fill="#fff4cc" stroke="#725a42" stroke-width="3" stroke-linejoin="round"/>
106
- <path d="M 981 308 H 1037" stroke="#fff4cc" stroke-width="8"/>
107
- <text x="991" y="266" style="fill:#25283a;font-size:17px;font-weight:700">海へ出発!</text>
98
+ <g transform="translate(931 172)" data-bubble-renderer="canonical" data-bubble-style="NORMAL" data-bubble-tail-direction="270"><title>Animation mode Bubble preview</title><path data-animation-mode-bubble-path="union" d="M 24.0000 71.0000 L 24.0000 42.0000 L 24.2216 39.1842 L 24.8810 36.4377 L 25.9619 33.8282 L 27.4377 31.4199 L 29.2721 29.2721 L 31.4199 27.4377 L 33.8282 25.9619 L 36.4377 24.8810 L 39.1842 24.2216 L 42.0000 24.0000 L 196.0000 24.0000 L 198.8158 24.2216 L 201.5623 24.8810 L 204.1718 25.9619 L 206.5801 27.4377 L 208.7279 29.2721 L 210.5623 31.4199 L 212.0381 33.8282 L 213.1190 36.4377 L 213.7784 39.1842 L 214.0000 42.0000 L 214.0000 118.0000 L 213.7784 120.8158 L 213.1190 123.5623 L 212.0381 126.1718 L 210.5623 128.5801 L 208.7279 130.7279 L 206.5801 132.5623 L 204.1718 134.0381 L 201.5623 135.1190 L 198.8158 135.7784 L 196.0000 136.0000 L 42.0000 136.0000 L 39.1842 135.7784 L 36.4377 135.1190 L 33.8282 134.0381 L 31.4199 132.5623 L 29.2721 130.7279 L 27.4377 128.5801 L 25.9619 126.1718 L 24.8810 123.5623 L 24.2216 120.8158 L 24.0000 118.0000 L 24.0000 89.0000 L 6.0000 80.0000 Z" fill="#fff4cc" stroke="#6f5b45" stroke-width="3" stroke-linejoin="round" data-boolean-operation="union" data-tail-base-on-border="true" /><text x="119" y="85.95" text-anchor="middle" fill="#25283a" font-family="Noto Sans JP, sans-serif" font-size="17">海へ出発!</text></g>
108
99
 
109
100
  </g>
110
101
  <g transform="translate(0 0)">
Binary file
@@ -6,7 +6,7 @@
6
6
 
7
7
  ## 1. 必要な拡張機能
8
8
 
9
- 入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。文字BubbleにはSVG TextとBubbleが必要です。portrait、lip-sync、continue indicator、将来のフルボイスや表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
9
+ 入力待ちを含む完全な例では6つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。文字BubbleにはSVG TextとBubbleが必要です。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
10
10
 
11
11
  | 順番 | 拡張機能 | 読み込み先 |
12
12
  | ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
@@ -15,7 +15,7 @@
15
15
  | 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
16
16
  | 4 | Asset Manager 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js` |
17
17
  | 5 | SVG Text 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js` |
18
- | 6 | Bubble 0.2.0 | npm公開後は`https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.2.0/dist/turbowarp-bubble.js` |
18
+ | 6 | Bubble 0.3.0 | npm公開後は`https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.3.0/dist/turbowarp-bubble.js` |
19
19
 
20
20
  開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。表示時にSVG Textが、画像・メディア機能の使用時にAsset Managerが、待機開始時にAsync InputかRuntime Expressionが見つからなければ、Bubbleは明示的なエラーを返します。
21
21
 
@@ -173,7 +173,22 @@ set continue frames [Next1,Next2]
173
173
  - `ASSETS`を空にすると、そのアニメーション設定を解除します。
174
174
  - 表情ベースを空にするとportrait全体を解除します。
175
175
 
176
- ## 5. セリフを表示して入力を待つ
176
+ ## 5. 逐次表示、音声、表示サイズ
177
+
178
+ Bubbleはセリフ全体を一度に描画するだけでなく、`CHARACTER`、`WORD`、`LINE`、`BLOCK`の単位で順次表示できます。`WORD`は形態素解析を行わず、空白または指定した区切り文字集合で分割します。区切り文字を表示するかどうかも選べます。
179
+
180
+ ```text
181
+ set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
182
+ set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
183
+ set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
184
+ set bubble voice [HeroVoice] for bubble style [hero-dialogue]
185
+ say [海へ出発!] with bubble style [hero-dialogue]
186
+ finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
187
+ ```
188
+
189
+ `DYNAMIC`は表示単位ごとに吹き出しの大きさと配置を再計算し、`RESERVED`は最終的な文字量を先に計測して表示中の外形を予約します。`set bubble reveal sound`は単位ごと、`set bubble voice`は表示開始時にAsset Managerの名前付き音声を再生します。音声がなくても文字表示は利用できます。
190
+
191
+ ## 6. セリフを表示して入力を待つ
177
192
 
178
193
  `say`または`think`はBubbleを表示するとすぐ次のブロックへ進み、初期animation modeは`talking`になります。
179
194
 
@@ -198,7 +213,7 @@ close this bubble
198
213
 
199
214
  ![talking、awaiting-continue、idleの目パチ、口パク、continue framesの状態比較](./assets/animation-mode-guide.svg)
200
215
 
201
- ## 6. Animation modeの使い分け
216
+ ## 7. Animation modeの使い分け
202
217
 
203
218
  | mode | 目パチ | 口パク | continue frames | 主な用途 |
204
219
  | ------------------- | ------ | ------------ | --------------- | ---------------------------- |
@@ -208,7 +223,22 @@ close this bubble
208
223
 
209
224
  `set this bubble animation mode [MODE]`は、呼び出したsprite、clone、またはStageが所有するBubbleだけを変更します。先に`say`または`think`を実行していない場合はエラーになります。
210
225
 
211
- ## 7. sayとthink
226
+ ## 8. 表示開始・表示中・表示終了animation
227
+
228
+ 表示開始は`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了は`fadeOut`、`floatOut`、`zoomOut`、`sink`から選べます。これらは`DYNAMIC`と`RESERVED`のどちらにも適用できます。
229
+
230
+ ```text
231
+ set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
232
+ set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
233
+ animate this bubble [shake]
234
+ shake this bubble direction [90] count [2] ease [easeInOut]
235
+ explode this bubble relative scale [1.15] count [2] ease [easeOut]
236
+ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
237
+ ```
238
+
239
+ TurboWarp adapterはこれらをschedulerのフレームごとに進め、各フレームの進行率へ`ease`を適用します。`shake`は吹き出し全体を方向・回数付きで揺らし、`explode`はportraitと文字を含むsurface全体を拡大して元へ戻し、`animate bubble shape`は指定時間中に現在の外形から`THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などへcross-fadeします。仕様では、吹き出しが表示される時点を「表示開始」、隠れる時点を「表示終了」と呼びます。
240
+
241
+ ## 9. sayとthink
212
242
 
213
243
  ```text
214
244
  say [MESSAGE] with bubble style [STYLE]
@@ -219,7 +249,7 @@ think [MESSAGE] with bubble style [STYLE]
219
249
 
220
250
  同じsprite、clone、またはStageで新しい`say`/`think`を実行すると、以前のBubbleをtimerやdrawableごと破棄してから置き換えます。Stageでは背景相対placementだけを使用できます。
221
251
 
222
- ## 8. cloneで使う
252
+ ## 10. cloneで使う
223
253
 
224
254
  Bubble styleの定義は拡張機能内で共有されますが、表示中のBubbleはsprite/cloneごとに所有されます。
225
255
 
@@ -229,28 +259,39 @@ Bubble styleの定義は拡張機能内で共有されますが、表示中のBu
229
259
 
230
260
  cloneが停止・削除された場合は、そのtargetに属するtimer、SVG Text skin、drawableが自動解放されます。
231
261
 
232
- ## 9. ブロック一覧
233
-
234
- | ブロック | 説明 |
235
- | -------------------------------------------------------------------------------------- | ------------------------------------------------------- |
236
- | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
237
- | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
238
- | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
239
- | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
240
- | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
241
- | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含む全体のscaleを設定する |
242
- | `set portrait base [ASSET] for bubble style [STYLE]` | portraitのベース画像を設定する |
243
- | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分と間隔を設定する |
244
- | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分と間隔を設定する |
245
- | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-continue`中の「次へ」アニメーションを設定する |
246
- | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始・置換する |
247
- | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始・置換する |
248
- | `set this bubble animation mode [MODE]` | `talking`、`awaiting-continue`、`idle`からmodeを選ぶ |
249
- | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
250
- | `close this bubble` | 自分のBubbleと所有resourceを解放する |
251
- | `Bubble version` | Bubble実装versionを返す |
252
-
253
- ## 10. よくあるエラー
262
+ ## 11. ブロック一覧
263
+
264
+ | ブロック | 説明 |
265
+ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------- |
266
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
267
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
268
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
269
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
270
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Bubble borderからtail先端までの基準長を設定する |
271
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含む全体のscaleを設定する |
272
+ | `set portrait base [ASSET] for bubble style [STYLE]` | portraitのベース画像を設定する |
273
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分と間隔を設定する |
274
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分と間隔を設定する |
275
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-continue`中の「次へ」アニメーションを設定する |
276
+ | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | CHARACTER/WORD/LINE/BLOCKの逐次表示を設定する |
277
+ | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | WORDの区切り文字集合と表示可否を設定する |
278
+ | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | 表示単位ごとの効果音を設定する |
279
+ | `set bubble voice [ASSET] for bubble style [STYLE]` | 表示開始時のフルボイスを設定する |
280
+ | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | 未表示単位を最後まで進め、条件またはtimeoutを待つ |
281
+ | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示開始animationを設定する |
282
+ | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示終了animationを設定する |
283
+ | `animate this bubble [MOTION]` | Bubble全体のanimationを再生する |
284
+ | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | 吹き出し全体を指定方向へ揺らす |
285
+ | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | 吹き出し全体を相対倍率で変化させる |
286
+ | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Bubble外形を時間経過で切り替える |
287
+ | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始・置換する |
288
+ | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始・置換する |
289
+ | `set this bubble animation mode [MODE]` | `talking`、`awaiting-continue`、`idle`からmodeを選ぶ |
290
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
291
+ | `close this bubble` | 自分のBubbleと所有resourceを解放する |
292
+ | `Bubble version` | Bubble実装versionを返す |
293
+
294
+ ## 12. よくあるエラー
254
295
 
255
296
  | 状況 | 原因と対処 |
256
297
  | ---------------------------------- | ------------------------------------------------------------------------ |
@@ -267,7 +308,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG
267
308
  | placementが不正 | 16方向、alias、0〜360度、背景相対3値のいずれかを指定する |
268
309
  | 目や口がずれる | ベースと全差分のcanvasサイズ、中心、透明領域を揃える |
269
310
 
270
- ## 11. 自動解放されるタイミング
311
+ ## 13. 自動解放されるタイミング
271
312
 
272
313
  次の場合、Bubbleが所有するtimer、SVG Text skin、renderer drawableは自動的に解放されます。
273
314
 
@@ -280,7 +321,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、SVG
280
321
 
281
322
  Asset Managerへ登録したアセット自体はBubbleの所有物ではありません。不要になった登録画像をメモリから削除する場合は、Bubbleを閉じた後にAsset Managerの`delete asset [NAME] from memory`を使います。
282
323
 
283
- ## 12. マニュアル画像の再生成
324
+ ## 14. マニュアル画像の再生成
284
325
 
285
326
  図とGIFはリポジトリ内のスクリプトから再生成できます。GIF生成にはImageMagickの`magick`コマンドが必要です。
286
327
 
@@ -6,7 +6,7 @@ This manual explains how to use `turbowarp-bubble` as an unsandboxed TurboWarp c
6
6
 
7
7
  ## 1. Load the required extensions
8
8
 
9
- The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. SVG Text and Bubble are required for text bubbles. Asset Manager is required for portrait, lip-sync, continue indicator, and future voice or display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
9
+ The complete input-wait example uses six extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. SVG Text and Bubble are required for text bubbles. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
10
10
 
11
11
  | Order | Extension | URL |
12
12
  | ----: | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
@@ -15,7 +15,7 @@ The complete input-wait example uses six extensions. Add Temporary Variables fro
15
15
  | 3 | Runtime Expression 0.3.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js` |
16
16
  | 4 | Asset Manager 0.7.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js` |
17
17
  | 5 | SVG Text 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js` |
18
- | 6 | Bubble 0.2.0 | After npm publication: `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.2.0/dist/turbowarp-bubble.js` |
18
+ | 6 | Bubble 0.3.0 | After npm publication: `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.3.0/dist/turbowarp-bubble.js` |
19
19
 
20
20
  To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if SVG Text is missing when it displays a Bubble, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait.
21
21
 
@@ -173,7 +173,22 @@ set continue frames [Next1,Next2]
173
173
  - An empty `ASSETS` input removes that animation.
174
174
  - An empty portrait base removes the whole portrait.
175
175
 
176
- ## 5. Show dialogue and wait for input
176
+ ## 5. Sequential reveal, audio, and layout
177
+
178
+ Bubble can reveal a message as `CHARACTER`, `WORD`, `LINE`, or `BLOCK` units. `WORD` does not perform morphological analysis; it uses whitespace or the configured delimiter character set. Delimiters can remain visible or be hidden.
179
+
180
+ ```text
181
+ set bubble reveal unit [CHARACTER] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
182
+ set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
183
+ set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
184
+ set bubble voice [HeroVoice] for bubble style [hero-dialogue]
185
+ say [Let's head for the sea!] with bubble style [hero-dialogue]
186
+ finish [CHARACTER] with condition [input == "pressed"] or timeout after [10] seconds
187
+ ```
188
+
189
+ `DYNAMIC` recalculates the Bubble size and placement after each unit. `RESERVED` measures the final text first and reserves that layout while units appear. `set bubble reveal sound` plays a named Asset Manager audio asset per unit, while `set bubble voice` plays full voice audio when the Bubble starts. Text display remains available without audio.
190
+
191
+ ## 6. Show dialogue and wait for input
177
192
 
178
193
  `say` and `think` show a Bubble immediately, continue to the next block, and begin in `talking` animation mode.
179
194
 
@@ -198,7 +213,7 @@ If animated GIF playback is unavailable, use this static animation-mode comparis
198
213
 
199
214
  ![Blink, lip-sync, and continue-frame states in talking, awaiting-continue, and idle modes](./assets/animation-mode-guide.svg)
200
215
 
201
- ## 6. Bubble animation modes
216
+ ## 7. Bubble animation modes
202
217
 
203
218
  | Mode | Blink | Lip-sync | Continue frames | Typical use |
204
219
  | ------------------- | ----- | ------------ | --------------- | ------------------------------------ |
@@ -208,7 +223,22 @@ If animated GIF playback is unavailable, use this static animation-mode comparis
208
223
 
209
224
  `set this bubble animation mode [MODE]` changes only the Bubble owned by the calling sprite, clone, or Stage. It reports an error if that target has not first run `say` or `think`.
210
225
 
211
- ## 7. `say` and `think`
226
+ ## 8. Show, in-display, and hide animations
227
+
228
+ Use `fadeIn`, `floatIn`, `zoomIn`, or `riseUp` when a Bubble starts displaying, and `fadeOut`, `floatOut`, `zoomOut`, or `sink` when it finishes displaying. These animations work with both `DYNAMIC` and `RESERVED` layout.
229
+
230
+ ```text
231
+ set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
232
+ set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
233
+ animate this bubble [shake]
234
+ shake this bubble direction [90] count [2] ease [easeInOut]
235
+ explode this bubble relative scale [1.15] count [2] ease [easeOut]
236
+ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
237
+ ```
238
+
239
+ The TurboWarp adapter advances these motions on scheduler frames and applies `ease` to each frame. `shake` applies direction and count to the complete Bubble surface, `explode` expands and returns the relative scale of text and portrait together, and `animate bubble shape` cross-fades the current outline into styles such as `THINKING`, `DREAMING`, `YELLING`, `WAVY`, or `WHISPERING` during the requested speed and duration.
240
+
241
+ ## 9. `say` and `think`
212
242
 
213
243
  ```text
214
244
  say [MESSAGE] with bubble style [STYLE]
@@ -219,7 +249,7 @@ Both blocks support the same visual styles, portrait layers, placement, and anim
219
249
 
220
250
  Running a new `say` or `think` on the same sprite, clone, or Stage disposes the previous Bubble and its timers/drawables before replacing it. The Stage supports stage-relative placement only.
221
251
 
222
- ## 8. Using Bubble with clones
252
+ ## 10. Using Bubble with clones
223
253
 
224
254
  Bubble style definitions are shared within the extension, but each sprite or clone owns its currently displayed Bubble.
225
255
 
@@ -229,28 +259,39 @@ Bubble style definitions are shared within the extension, but each sprite or clo
229
259
 
230
260
  When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables owned by that target are released automatically.
231
261
 
232
- ## 9. Block reference
233
-
234
- | Block | Description |
235
- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
236
- | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
237
- | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
238
- | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
239
- | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten SVG body shapes |
240
- | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Set the nominal border-to-tip tail length |
241
- | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Set body position and whole-Bubble scale, including text |
242
- | `set portrait base [ASSET] for bubble style [STYLE]` | Set the portrait base image |
243
- | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set blink overlays and interval |
244
- | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set lip-sync overlays and interval |
245
- | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set the animation shown during `awaiting-continue` |
246
- | `say [MESSAGE] with bubble style [STYLE]` | Start or replace a `say` Bubble in `talking` mode |
247
- | `think [MESSAGE] with bubble style [STYLE]` | Start or replace a `think` Bubble in `talking` mode |
248
- | `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-continue`, or `idle` for this Bubble |
249
- | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
250
- | `close this bubble` | Release this target's Bubble and owned resources |
251
- | `Bubble version` | Report the Bubble implementation version |
252
-
253
- ## 10. Troubleshooting
262
+ ## 11. Block reference
263
+
264
+ | Block | Description |
265
+ | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
266
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
267
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
268
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
269
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten SVG body shapes |
270
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | Set the nominal border-to-tip tail length |
271
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | Set body position and whole-Bubble scale, including text |
272
+ | `set portrait base [ASSET] for bubble style [STYLE]` | Set the portrait base image |
273
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set blink overlays and interval |
274
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set lip-sync overlays and interval |
275
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | Set the animation shown during `awaiting-continue` |
276
+ | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | Configure CHARACTER/WORD/LINE/BLOCK sequential reveal |
277
+ | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | Configure WORD delimiters and visibility |
278
+ | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | Set the per-unit reveal sound |
279
+ | `set bubble voice [ASSET] for bubble style [STYLE]` | Set full voice played when display starts |
280
+ | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | Reveal remaining units and wait for condition or timeout |
281
+ | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configure show animation |
282
+ | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | Configure hide animation |
283
+ | `animate this bubble [MOTION]` | Play a whole-Bubble animation |
284
+ | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Shake the complete Bubble surface |
285
+ | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Apply relative scale cycles to the Bubble |
286
+ | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Transition the Bubble outline |
287
+ | `say [MESSAGE] with bubble style [STYLE]` | Start or replace a `say` Bubble in `talking` mode |
288
+ | `think [MESSAGE] with bubble style [STYLE]` | Start or replace a `think` Bubble in `talking` mode |
289
+ | `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-continue`, or `idle` for this Bubble |
290
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
291
+ | `close this bubble` | Release this target's Bubble and owned resources |
292
+ | `Bubble version` | Report the Bubble implementation version |
293
+
294
+ ## 12. Troubleshooting
254
295
 
255
296
  | Symptom | Cause and solution |
256
297
  | ------------------------------------ | --------------------------------------------------------------------------- |
@@ -267,7 +308,7 @@ When a clone stops or is deleted, timers, SVG Text skins, and renderer drawables
267
308
  | Invalid placement | Use a 16-way direction, alias, 0–360 degree angle, or stage-relative value |
268
309
  | Eyes or mouth are misaligned | Match canvas size, center, and transparent area across all portrait layers |
269
310
 
270
- ## 11. Automatic cleanup
311
+ ## 13. Automatic cleanup
271
312
 
272
313
  Bubble automatically releases its owned timers, SVG Text skins, and renderer drawables when:
273
314
 
@@ -280,7 +321,7 @@ Bubble automatically releases its owned timers, SVG Text skins, and renderer dra
280
321
 
281
322
  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 `delete asset [NAME] from memory` block.
282
323
 
283
- ## 12. Regenerating the manual assets
324
+ ## 14. Regenerating the manual assets
284
325
 
285
326
  The diagrams and GIF are generated from scripts in this repository. GIF generation requires the ImageMagick `magick` command.
286
327