@kubohiroya/turbowarp-bubble 0.1.1 → 0.2.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 CHANGED
@@ -2,18 +2,142 @@
2
2
 
3
3
  `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。紙芝居固有のDSLやシーン遷移には依存しません。
4
4
 
5
+ ## 機能の全体像
6
+
7
+ Bubbleは、文字を描くText provider、吹き出しの外形と配置を管理するBubble layer、画像・音声を解決する任意のAsset capabilityを組み合わせます。これにより、TurboWarpの機能拡張としても、アプリのhostから呼び出すcompositionとしても同じ表示モデルを利用できます。
8
+
9
+ ```mermaid
10
+ flowchart LR
11
+ input[セリフ入力] --> reveal[表示単位の選択]
12
+ reveal --> text[CHARACTER / WORD / LINE / BLOCK]
13
+ text --> layout[改行・サイズ計算]
14
+ layout --> body[Bubble外形・tail・placement]
15
+ text --> voice[フルボイス/単位ごとの効果音]
16
+ body --> portrait[portraitレイヤー]
17
+ portrait --> blink[blink]
18
+ portrait --> lipsync[lip-sync]
19
+ body --> motion[入場・中間・退場animation]
20
+ body --> wait[continue待機]
21
+ wait --> close[終了・resource解放]
22
+ ```
23
+
24
+ このREADMEでは、現在公開している機能と、3層構成で接続する表示仕様を同じ用語で説明します。公開APIにまだ現れていない仕様は「実装状況」欄で明示しています。
25
+
26
+ | 領域 | このREADMEで説明する内容 | 現在の公開API |
27
+ | --------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
28
+ | 文字描画・改行 | 名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(SVG Text capability) |
29
+ | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | 仕様を整理中。現行Bubbleは`show`/`setText`で全文を受け取る |
30
+ | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | 実装済み(Asset Manager capability) |
31
+ | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | 実装済み |
32
+ | 表示mode | `talking`/`awaiting-continue`/`idle` | 実装済み |
33
+ | 入退場・中間animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | 仕様を整理中。現行APIは未公開 |
34
+
35
+ ## 3層構成と責務
36
+
37
+ 依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。
38
+
39
+ ```mermaid
40
+ flowchart TB
41
+ core[Bubble composition\n外形・配置・ライフサイクル・animation state]
42
+ adapter[TurboWarp adapter\nrenderer / runtime / targetへの接続]
43
+ text[SVG Text provider\n文字skin・計測・named style]
44
+ image[Image capability\nportrait・blink・lip-sync・continue画像]
45
+ audio[Audio capability\nvoice・表示単位ごとの効果音]
46
+ input[Async Input + Runtime Expression\n入力と待機条件]
47
+ core --> adapter
48
+ adapter --> text
49
+ core -.任意Capability.-> image
50
+ core -.任意Capability.-> audio
51
+ core -.任意Capability.-> input
52
+ ```
53
+
54
+ `@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portraitの配置、入退場animationは担当しません。Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyで、対応する機能を使う場合だけ接続します。
55
+
56
+ ## 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
57
+
58
+ セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
59
+
60
+ 仕様上の綴りは`CHARACTER`です(`charactor`ではありません)。`BLOCK`は、改行を含む複数行を一つの表示単位として扱う名前で、ここでいうblockはScratchのblockではありません。
61
+
62
+ ```mermaid
63
+ flowchart LR
64
+ source[全文: 私の/名前は/中野/です] --> mode{表示単位}
65
+ mode -->|CHARACTER| c[私 → 私の → 私の/ → …]
66
+ mode -->|WORD| w[私の → 私の/名前は → …]
67
+ mode -->|LINE| l[1行ずつ追加]
68
+ mode -->|BLOCK| b[複数行/段落をまとめて追加]
69
+ delimiter[任意の区切り文字集合\n例: /、空白、|] -.-> w
70
+ visibility{区切り文字の表示} -->|visible| shown[区切り文字も描画]
71
+ visibility -->|invisible| hidden[区切り文字を隠して描画]
72
+ delimiter --> visibility
73
+ ```
74
+
75
+ ### WORDの区切り文字
76
+
77
+ 日本語の形態素解析は行いません。`WORD`は空白で区切る言語、または利用者が区切りを埋め込める言語を対象にします。例えば`私の/名前は/中野/です`を入力し、`/`をWORD delimiterにして不可視にすれば、`私の`→`名前は`→`中野`→`です`の順で表示できます。区切り文字を可視にすれば、スラッシュを演出として残せます。
78
+
79
+ 区切り文字は単一文字に限定せず、任意の文字集合として指定します。delimiter自体を表示単位に含めるか、取り除いてからText providerへ渡すかを選べるようにします。
80
+
81
+ ### DYNAMICとRESERVED
82
+
83
+ 逐次表示中の吹き出しサイズは、次の2方式を選べるようにします。
84
+
85
+ ```mermaid
86
+ sequenceDiagram
87
+ participant Host as Host
88
+ participant Bubble as Bubble surface
89
+ participant Text as Text provider
90
+ Host->>Text: 全文をmeasure
91
+ alt RESERVED
92
+ Text-->>Bubble: 最終幅・最終行数
93
+ Bubble->>Bubble: 最終サイズを先に確保
94
+ loop 表示単位ごと
95
+ Host->>Text: 可視範囲を更新
96
+ Text-->>Bubble: 文字だけ更新
97
+ end
98
+ else DYNAMIC
99
+ loop 表示単位ごと
100
+ Host->>Text: 可視範囲を更新
101
+ Text-->>Bubble: 現在の幅・行数
102
+ Bubble->>Bubble: 外形とplacementを再計算
103
+ end
104
+ end
105
+ ```
106
+
107
+ `RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。いずれもBubble外形のanimationやportraitレイヤーとは独立したレイアウト方針です。現行の公開composition APIでは`show`と`handle.setText()`がこの接続点になり、逐次表示の分割・タイミングはhostが制御します。
108
+
109
+ 逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
110
+
111
+ ```text
112
+ finish [CHARACTER / WORD / LINE / BLOCK]
113
+ with condition [CONDITION]
114
+ or timeout after [TIMEOUT] seconds
115
+ ```
116
+
117
+ `CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または退場animationを開始します。`finish`の公開block/APIは現在のBubbleにはまだなく、既存の`wait with this bubble ...`は全文表示後の入力待ちに対応します。
118
+
119
+ ### 音声と表示単位
120
+
121
+ Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
122
+
123
+ - 表示開始時のフルボイス
124
+ - `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
125
+ - 表示終了、continue待機、timeoutの通知音
126
+
127
+ 表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声assetを再生する経路です。音声がない場合でも、文字表示・portrait・Bubble外形は独立して利用できます。
128
+
5
129
  ## パッケージ境界
6
130
 
7
131
  | パッケージ | 責務 |
8
132
  | ------------------------------------------ | ------------------------------------------------------------------------- |
9
- | `@kubohiroya/turbowarp-asset-manager` | アセット名の登録、画像種別の検証、画像targetへの適用 |
133
+ | `@kubohiroya/turbowarp-asset-manager` | アセット名の登録、画像種別の検証、画像targetへの適用、音声再生 |
10
134
  | `@kubohiroya/turbowarp-svg-text` | 名前付き文字styleと、文字列からSVGスキンへの変換 |
11
135
  | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
12
136
  | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
13
137
  | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、say/think、表情レイヤー、animation mode、入力待機 |
14
138
  | アプリ/host | 必要に応じたDSLからcomposition APIへの変換 |
15
139
 
16
- Bubbleは依存パッケージを再exportしません。このため、Asset ManagerとSVG文字ActorはBubbleを使わない画面でも従来どおり単独で利用できます。
140
+ Bubbleは依存パッケージを再exportしません。SVG Textは現在の文字描画に必要ですが、Asset Manager、Async Input、Runtime Expressionは利用する機能がなければインストール不要です。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
17
141
 
18
142
  ## 自動改行と禁則処理の基盤
19
143
 
@@ -31,7 +155,7 @@ const layout = wrapText({
31
155
  });
32
156
  ```
33
157
 
34
- この基盤は改行位置と行幅を返します。Bubble surfaceへ`maxWidth`を渡し、SVG Textの実測値と吹き出し形状へ接続する処理は、後続の表示統合で追加します。
158
+ Composition APIのBubble styleへ`maxWidth`と任意の`textLocale`を渡すと、Text capabilityの`measureText`を使ってこの`wrapText`基盤が実際の表示文字列を自動改行します。SVG Textまたはhost側のText capabilityが`measureText`を提供しない場合、`maxWidth`を使った表示は明示的なcapabilityエラーになります。
35
159
 
36
160
  ![maxWidthの違いによる自動改行と、日本語禁則処理の例](docs/assets/width-linebreak-guide.svg)
37
161
 
@@ -58,20 +182,24 @@ standalone機能拡張では、`set bubble visual style`ブロックで形状を
58
182
  ## インストール
59
183
 
60
184
  ```sh
61
- pnpm add @kubohiroya/turbowarp-bubble \
62
- @kubohiroya/turbowarp-asset-manager \
63
- @kubohiroya/turbowarp-svg-text \
185
+ pnpm add @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
186
+ ```
187
+
188
+ 現在のpeer dependency範囲は、SVG Textが`>=0.4.0 <1`、Asset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`です。Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyです。
189
+
190
+ 画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
191
+
192
+ ```sh
193
+ pnpm add @kubohiroya/turbowarp-asset-manager \
64
194
  @kubohiroya/turbowarp-async-input \
65
195
  @kubohiroya/turbowarp-runtime-expression
66
196
  ```
67
197
 
68
- 現在のpeer dependency範囲は、Asset Manager `>=0.7.0 <1`、SVG Text、Async Input、Runtime Expressionがそれぞれ`>=0.3.0 <1`です。
69
-
70
198
  ## TurboWarp機能拡張
71
199
 
72
- ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-advance`、入力成立、`close`までのアニメーション例も掲載しています。
200
+ ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
73
201
 
74
- TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、「カスタム拡張機能」から次の5本をサンドボックスなしで読み込みます。Async InputとRuntime ExpressionはBubble待機より前に、Asset ManagerとSVG Textは最初のBubble表示より前にロードします。
202
+ TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、「カスタム拡張機能」からSVG TextとBubbleをサンドボックスなしで読み込みます。portrait、lip-sync、continue indicator、または音声アセットを使う場合だけAsset Managerを追加し、待機ブロックを使う場合だけAsync InputとRuntime Expressionを追加します。各依存が必要な機能を実行する前にロードしてください。
75
203
 
76
204
  ```text
77
205
  https://unpkg.com/@kubohiroya/turbowarp-asset-manager/dist/asset-manager.js
@@ -95,11 +223,11 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
95
223
  | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含むBubble全体の拡大率を設定する |
96
224
  | `set portrait base [ASSET] for bubble style [STYLE]` | 表情ベース画像を設定する。空文字でportrait全体を解除する |
97
225
  | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分を設定する。空リストで解除する |
98
- | `set talk frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
99
- | `set advance frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
226
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
227
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
100
228
  | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始または置換する |
101
229
  | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始または置換する |
102
- | `set this bubble animation mode [MODE]` | `talking`/`awaiting-advance`/`idle`を切り替える |
230
+ | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を切り替える |
103
231
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | 条件成立またはtimeoutまでBubbleを表示したまま待つ |
104
232
  | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
105
233
  | `Bubble version` | 実装versionを返す |
@@ -138,15 +266,75 @@ Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box
138
266
 
139
267
  `offset x/y/scale`の既定値は`[0, 0, 100]`です。xは右、yは上が正です。scaleはBubble外形だけでなく、SVG Textの文字(フォントサイズ)、表情画像、次へアイコン、内部余白へ一体で適用します。scaleだけを変えた場合は、拡大量の半径分だけ本体中心をActorから離し、Actor側の間隔を維持します。その後x/y offsetを加え、固定したtail先端へ向けてtailを再生成するため、offset後の実長は`tail length`から変化し得ます。Stage端では全体が画面内に収まるようクランプします。これら3設定は背景相対placementでは無視します。
140
268
 
269
+ ### Portraitとblink / lip-sync
270
+
271
+ portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
272
+
273
+ ```mermaid
274
+ flowchart TB
275
+ bubble[Bubble surface]
276
+ body[Bubble body / text]
277
+ base[portraitBase\n顔・髪・輪郭]
278
+ blink[portraitBlink\n目パチ差分]
279
+ lipsync[portraitLipSync\n口パク差分]
280
+ continue[continueIndicator\n次へアイコン]
281
+ bubble --> body
282
+ bubble --> base
283
+ base --> blink
284
+ base --> lipsync
285
+ bubble --> continue
286
+ ```
287
+
288
+ | レイヤー | 表示中の動作 | 設定ブロック/API |
289
+ | ------------------- | ------------------------------------------------------ | ------------------------------------------- |
290
+ | `portraitBase` | 常時表示するベース画像 | `set portrait base` / `portrait.base` |
291
+ | `portraitBlink` | `talking`、`awaiting-continue`、`idle`のすべてでループ | `set blink frames` / `portrait.blink` |
292
+ | `portraitLipSync` | `talking`中だけループし、待機時は停止・非表示 | `set lip-sync frames` / `portrait.lipSync` |
293
+ | `continueIndicator` | `awaiting-continue`中だけループ | `set continue frames` / `continueIndicator` |
294
+
295
+ 目パチと口パクは1枚の静止画でも利用できます。口パクのキーワードは、話す行為全体ではなく口元の表情差分を指定する意味で`lip-sync`に統一しています。`continue`は、入力待ちを表すアイコンのanimationであり、JavaScriptの`continue`文を実行する機能ではありません。
296
+
297
+ ![portrait base、blink、lip-sync、continue indicatorを別レイヤーとして重ねる概念図](docs/assets/animation-mode-guide.svg)
298
+
299
+ ### Bubble animation
300
+
301
+ Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
302
+
303
+ ```mermaid
304
+ flowchart LR
305
+ start[表示開始] --> in[入場animation\nfadeIn / floatIn / zoomIn / riseUp]
306
+ in --> visible[表示中]
307
+ visible --> shake[shake\n方向・回数・ease]
308
+ visible --> explode[explode\n相対サイズ・回数・ease]
309
+ visible --> shape[animateBubbleShape\n速度・時間]
310
+ visible --> waiting[awaiting-continue]
311
+ waiting --> out[退場animation\nfadeOut / floatOut / zoomOut / sink]
312
+ out --> released[close・resource解放]
313
+ ```
314
+
315
+ #### 入場と退場
316
+
317
+ PowerPointの用語に寄せ、入場には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、退場には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。入場・退場animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、退場時には現在の外形を基準に終点を計算します。
318
+
319
+ #### 表示中の変形
320
+
321
+ - `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
322
+ - `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
323
+ - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を時間経過で補間します。`visualStyle`の切替と、切替中の形状補間を分離できます。
324
+
325
+ animationは`show`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとdrawableを先に解放します。
326
+
327
+ > **実装状況:** 現在の公開composition APIで利用できるBubble motionは、visual styleの設定と`talking`/`awaiting-continue`/`idle`のmode切替です。上記の入場・退場・`shake`・`explode`・`animateBubbleShape`を外部hostから指定する正式なメソッド/ブロックは、後方互換性を壊さない形で追加する予定です。
328
+
141
329
  ### Animation mode
142
330
 
143
- | mode | 目パチ | 口パク | advance frames |
144
- | ------------------ | ------ | ------------ | -------------- |
145
- | `talking` | 実行 | 実行 | 非表示 |
146
- | `awaiting-advance` | 実行 | 停止・非表示 | ループ実行 |
147
- | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
331
+ | mode | 目パチ | 口パク | continue frames |
332
+ | ------------------- | ------ | ------------ | --------------- |
333
+ | `talking` | 実行 | 実行 | 非表示 |
334
+ | `awaiting-continue` | 実行 | 停止・非表示 | ループ実行 |
335
+ | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
148
336
 
149
- `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-advance`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
337
+ `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
150
338
 
151
339
  ### ブロック構成例
152
340
 
@@ -159,8 +347,8 @@ set bubble tail length [18] for bubble style [hero-dialogue]
159
347
  set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
160
348
  set portrait base [HeroFace] for bubble style [hero-dialogue]
161
349
  set blink frames [HeroEyesOpen,HeroEyesClosed] every [0.4] seconds for bubble style [hero-dialogue]
162
- set talk frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
163
- set advance frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
350
+ set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
351
+ set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
164
352
  set runtime variable [input] to []
165
353
  listen for key [Space] set runtime var [input] to [pressed]
166
354
  listen for touch on this sprite set runtime var [input] to [pressed]
@@ -173,7 +361,7 @@ close this bubble
173
361
 
174
362
  ## Composition API
175
363
 
176
- TurboWarp runtimeのrenderer、Asset Manager、SVG Textへ直接接続するhostでは、公開adapterを利用できます。
364
+ TurboWarp runtimeのrenderer、SVG Textへ直接接続するhostでは、公開adapterを利用できます。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
177
365
 
178
366
  ```ts
179
367
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -188,7 +376,7 @@ import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manag
188
376
  import { createSvgTextComposition } from "@kubohiroya/turbowarp-svg-text/composition";
189
377
  import { createBubbleComposition } from "@kubohiroya/turbowarp-bubble/composition";
190
378
 
191
- const assetManager = createAssetManagerComposition();
379
+ const imageResolver = createAssetManagerComposition();
192
380
  const svgText = createSvgTextComposition({ runtime });
193
381
 
194
382
  svgText.defineStyle({
@@ -201,7 +389,7 @@ svgText.defineStyle({
201
389
  });
202
390
 
203
391
  const bubbles = createBubbleComposition({
204
- assetManager,
392
+ imageResolver,
205
393
  svgText,
206
394
  async createSurface({ actor, actorKey, kind, style }) {
207
395
  // hostがActorの近くへsurfaceを配置し、各レイヤー用のtargetを返します。
@@ -210,13 +398,17 @@ const bubbles = createBubbleComposition({
210
398
  });
211
399
  ```
212
400
 
401
+ テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
402
+
213
403
  `createSurface`が返すsurfaceは、次のtargetを持ちます。
214
404
 
405
+ surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
406
+
215
407
  - `text`: SVG Textが文字スキンを適用するtarget
216
408
  - `portraitBase`: キャラクター表情のベース画像target
217
409
  - `portraitBlink`: 目パチ差分target
218
- - `portraitTalk`: 口パク差分target
219
- - `advanceIndicator`: 「次へ」アイコンtarget
410
+ - `portraitLipSync`: 口パク差分target
411
+ - `continueIndicator`: 「次へ」アイコンtarget
220
412
 
221
413
  画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
222
414
 
@@ -237,12 +429,12 @@ bubbles.defineStyle({
237
429
  frames: ["HeroEyesOpen", "HeroEyesClosed"],
238
430
  frameIntervalSeconds: 0.4,
239
431
  },
240
- talk: {
432
+ lipSync: {
241
433
  frames: ["HeroMouthClosed", "HeroMouthOpen"],
242
434
  frameIntervalSeconds: 0.1,
243
435
  },
244
436
  },
245
- advanceIndicator: {
437
+ continueIndicator: {
246
438
  frames: ["Next1", "Next2"],
247
439
  frameIntervalSeconds: 0.2,
248
440
  },
@@ -252,6 +444,8 @@ bubbles.defineStyle({
252
444
  name: "narration",
253
445
  textStyle: "dialogue-text",
254
446
  placement: "FOOTER_LIKE",
447
+ maxWidth: 320,
448
+ textLocale: "ja",
255
449
  });
256
450
 
257
451
  const bubble = await bubbles.show({
@@ -263,10 +457,10 @@ const bubble = await bubbles.show({
263
457
  });
264
458
  ```
265
459
 
266
- `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-advance`へ変更します。
460
+ `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-continue`へ変更します。
267
461
 
268
462
  ```ts
269
- await bubble.setAnimationMode("awaiting-advance");
463
+ await bubble.setAnimationMode("awaiting-continue");
270
464
  // 口パクを停止して非表示にし、「次へ」アイコンをループ表示します。
271
465
 
272
466
  await bubble.setAnimationMode("idle");
@@ -275,7 +469,7 @@ await bubble.setAnimationMode("idle");
275
469
  await bubble.close();
276
470
  ```
277
471
 
278
- 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、SVG Text target、surfaceを解放します。composition間で状態は共有しません。
472
+ 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、SVG Text target、surfaceを解放します。composition間で状態は共有しません。
279
473
 
280
474
  ## DSL 4.0との関係
281
475