@kubohiroya/turbowarp-bubble 0.1.1 → 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.
package/README.md CHANGED
@@ -1,21 +1,160 @@
1
1
  # TurboWarp Bubble
2
2
 
3
- `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。紙芝居固有のDSLやシーン遷移には依存しません。
3
+ `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
4
+
5
+ ## READMEの読み方
6
+
7
+ 利用環境を先に決めると、必要な部分だけを読めます。
8
+
9
+ 1. TurboWarpでブロックを使う場合は、後述の[TurboWarp機能拡張](#turbowarp機能拡張)と[提供ブロック](#提供ブロック)を確認します。
10
+ 2. 独自Webアプリやhostから使う場合は、[Composition API](#composition-api)と[Styleと表示](#styleと表示)を確認します。
11
+ 3. 表示単位、改行、外形、portrait、animationの仕様を知りたい場合は、[概念と表示仕様](#概念と表示仕様)を参照します。
12
+ 4. Scratch公式エディターでの利用可否は、[Scratchとの互換性](#scratchとの互換性)に記載しています。
13
+
14
+ ## 機能の全体像
15
+
16
+ Bubbleは、文字を描くText provider、吹き出しの外形と配置を管理するBubble layer、画像・音声を解決する任意のAsset capabilityを組み合わせます。これにより、TurboWarpの機能拡張としても、アプリのhostから呼び出すcompositionとしても同じ表示モデルを利用できます。
17
+
18
+ ```mermaid
19
+ flowchart LR
20
+ input[セリフ入力] --> reveal[表示単位の選択]
21
+ reveal --> text[CHARACTER / WORD / LINE / BLOCK]
22
+ text --> layout[改行・サイズ計算]
23
+ layout --> body[Bubble外形・tail・placement]
24
+ text --> voice[フルボイス/単位ごとの効果音]
25
+ body --> portrait[portraitレイヤー]
26
+ portrait --> blink[blink]
27
+ portrait --> lipsync[lip-sync]
28
+ body --> motion[表示開始・表示中・表示終了animation]
29
+ body --> wait[continue待機]
30
+ wait --> close[終了・resource解放]
31
+ ```
32
+
33
+ このREADMEでは、現在公開している機能と、3層構成で接続する表示仕様を同じ用語で説明します。公開APIにまだ現れていない仕様は「実装状況」欄で明示しています。
34
+
35
+ | 領域 | このREADMEで説明する内容 | 現在の公開API |
36
+ | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
37
+ | 文字描画・改行 | 名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(SVG Text capability) |
38
+ | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | 実装済み(`revealNext`/`revealAll`/`finish`、対応ブロック) |
39
+ | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | 実装済み(Asset Manager capability) |
40
+ | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | 実装済み |
41
+ | 表示mode | `talking`/`awaiting-continue`/`idle` | 実装済み |
42
+ | 表示開始・表示中・表示終了animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | 実装済み(`handle.animate`、style設定、対応ブロック) |
43
+
44
+ ## 概念と表示仕様
45
+
46
+ ### 3層構成と責務
47
+
48
+ 依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。矢印は「利用する側」から「利用される側」へ向けています。
49
+
50
+ ```mermaid
51
+ flowchart TB
52
+ core[Bubble composition\n外形・配置・ライフサイクル・animation state]
53
+ adapter[TurboWarp adapter\nrenderer / runtime / targetへの接続]
54
+ text[SVG Text provider\n文字skin・計測・named style]
55
+ image[Image capability\nportrait・blink・lip-sync・continue画像]
56
+ audio[Audio capability\nvoice・表示単位ごとの効果音]
57
+ input[Async Input + Runtime Expression\n入力と待機条件]
58
+ extension[TurboWarp extension\nblocks / Scratch target]
59
+ adapter --> core
60
+ adapter --> text
61
+ core -.任意Capability.-> image
62
+ core -.任意Capability.-> audio
63
+ extension --> core
64
+ extension -.optional.-> input
65
+ ```
66
+
67
+ `@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationは担当しません。画像解決、音声再生、入力、条件評価はCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyとして対応機能を使う場合だけ接続します。
68
+
69
+ ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
70
+
71
+ セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
72
+
73
+ 仕様上の綴りは`CHARACTER`です(`charactor`ではありません)。`BLOCK`は、改行を含む複数行を一つの表示単位として扱う名前で、ここでいうblockはScratchのblockではありません。
74
+
75
+ ```mermaid
76
+ flowchart LR
77
+ source["全文: 私の/名前は/中野/です"] --> mode{"表示単位"}
78
+ mode -->|CHARACTER| c["私 → 私の → 私の/ → …"]
79
+ mode -->|WORD| w["私の → 私の/名前は → …"]
80
+ mode -->|LINE| l["1行ずつ追加"]
81
+ mode -->|BLOCK| b["複数行/段落をまとめて追加"]
82
+ delimiter["任意の区切り文字集合<br/>例: スラッシュ、空白、縦線"] -.-> w
83
+ visibility{"区切り文字の表示"} -->|visible| shown["区切り文字も描画"]
84
+ visibility -->|invisible| hidden["区切り文字を隠して描画"]
85
+ delimiter --> visibility
86
+ ```
87
+
88
+ ### WORDの区切り文字
89
+
90
+ 日本語の形態素解析は行いません。`WORD`は空白で区切る言語、または利用者が区切りを埋め込める言語を対象にします。例えば`私の/名前は/中野/です`を入力し、`/`をWORD delimiterにして不可視にすれば、`私の`→`名前は`→`中野`→`です`の順で表示できます。区切り文字を可視にすれば、スラッシュを演出として残せます。
91
+
92
+ 区切り文字は単一文字に限定せず、任意の文字集合として指定します。delimiter自体を表示単位に含めるか、取り除いてからText providerへ渡すかを選べるようにします。
93
+
94
+ ### DYNAMICとRESERVED
95
+
96
+ 逐次表示中の吹き出しサイズは、次の2方式を選べるようにします。
97
+
98
+ ```mermaid
99
+ sequenceDiagram
100
+ participant Host as Host
101
+ participant Bubble as Bubble surface
102
+ participant Text as Text provider
103
+ Host->>Text: 全文をmeasure
104
+ alt RESERVED
105
+ Text-->>Bubble: 最終幅・最終行数
106
+ Bubble->>Bubble: 最終サイズを先に確保
107
+ loop 表示単位ごと
108
+ Host->>Text: 可視範囲を更新
109
+ Text-->>Bubble: 文字だけ更新
110
+ end
111
+ else DYNAMIC
112
+ loop 表示単位ごと
113
+ Host->>Text: 可視範囲を更新
114
+ Text-->>Bubble: 現在の幅・行数
115
+ Bubble->>Bubble: 外形とplacementを再計算
116
+ end
117
+ end
118
+ ```
119
+
120
+ `RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。いずれもBubble外形のanimationやportraitレイヤーとは独立したレイアウト方針です。Composition APIではstyleの`reveal`、`handle.revealNext()`、`handle.revealAll()`が分割・タイミングの接続点になり、`intervalSeconds`を指定した自動送りにも対応します。
121
+
122
+ 逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
123
+
124
+ ```text
125
+ finish [CHARACTER / WORD / LINE / BLOCK]
126
+ with condition [CONDITION]
127
+ or timeout after [TIMEOUT] seconds
128
+ ```
129
+
130
+ `CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または表示終了animationを開始します。Composition APIでは`handle.finish({ unit, condition, timeoutSeconds })`、手続き型拡張では`finish [UNIT] ...`ブロックを使います。
131
+
132
+ ### 音声と表示単位
133
+
134
+ `finish`は公開Composition APIの`handle.finish({ unit, condition, timeoutSeconds })`と、TurboWarpの`finish [UNIT] ...`ブロックで利用できます。これは逐次表示を最後まで進め、条件成立またはtimeoutで音声と待機状態を確定します。
135
+
136
+ Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
4
137
 
5
- ## パッケージ境界
138
+ - 表示開始時のフルボイス
139
+ - `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
140
+ - 表示終了、continue待機、timeoutの通知音
6
141
 
7
- | パッケージ | 責務 |
8
- | ------------------------------------------ | ------------------------------------------------------------------------- |
9
- | `@kubohiroya/turbowarp-asset-manager` | アセット名の登録、画像種別の検証、画像targetへの適用 |
10
- | `@kubohiroya/turbowarp-svg-text` | 名前付き文字styleと、文字列からSVGスキンへの変換 |
11
- | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
12
- | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
13
- | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、say/think、表情レイヤー、animation mode、入力待機 |
14
- | アプリ/host | 必要に応じたDSLからcomposition APIへの変換 |
142
+ 表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声assetを再生する経路です。音声がない場合でも、文字表示・portrait・Bubble外形は独立して利用できます。
15
143
 
16
- Bubbleは依存パッケージを再exportしません。このため、Asset ManagerとSVG文字ActorはBubbleを使わない画面でも従来どおり単独で利用できます。
144
+ ### パッケージ境界
17
145
 
18
- ## 自動改行と禁則処理の基盤
146
+ | パッケージ | 責務 |
147
+ | ------------------------------------------ | ------------------------------------------------------------------------------ |
148
+ | `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
149
+ | `@kubohiroya/turbowarp-svg-text` | 名前付き文字styleと、文字列からSVGスキンへの変換 |
150
+ | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
151
+ | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
152
+ | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
153
+ | アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
154
+
155
+ Bubbleは依存パッケージを再exportしません。SVG Textは現在の文字描画に必要ですが、画像・音声・入力・条件評価はCapabilityとして差し替えられます。TurboWarp adapterではAsset Managerを自動接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
156
+
157
+ ### 自動改行と禁則処理の基盤
19
158
 
20
159
  Bubbleの任意`maxWidth`による自動改行では、`@cto.af/linebreak`を利用してUnicode UAX #14準拠の改行可能位置を求めます。依存は`LineBreakProvider` interfaceの内側へ閉じ込め、実際のフォントで測った幅から、上限内に収まる最も後ろの候補をBubble側で選びます。
21
160
 
@@ -31,13 +170,13 @@ const layout = wrapText({
31
170
  });
32
171
  ```
33
172
 
34
- この基盤は改行位置と行幅を返します。Bubble surfaceへ`maxWidth`を渡し、SVG Textの実測値と吹き出し形状へ接続する処理は、後続の表示統合で追加します。
173
+ Composition APIのBubble styleへ`maxWidth`と任意の`textLocale`を渡すと、Text capabilityの`measureText`を使ってこの`wrapText`基盤が実際の表示文字列を自動改行します。SVG Textまたはhost側のText capabilityが`measureText`を提供しない場合、`maxWidth`を使った表示は明示的なcapabilityエラーになります。
35
174
 
36
175
  ![maxWidthの違いによる自動改行と、日本語禁則処理の例](docs/assets/width-linebreak-guide.svg)
37
176
 
38
177
  図の各行はproductionの`wrapText`を直接呼んだ結果です。図版専用の手作業改行は使っていません。
39
178
 
40
- ## Bubble visual styleの形状
179
+ ### Bubble visual styleの形状
41
180
 
42
181
  形状候補は`NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`です。
43
182
 
@@ -49,41 +188,88 @@ standalone機能拡張では、`set bubble visual style`ブロックで形状を
49
188
 
50
189
  配布bundleに含まれる依存ライブラリのライセンスは、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)を参照してください。
51
190
 
52
- ## ライセンスとソースコード
191
+ ## 利用方法
53
192
 
54
- このパッケージのSource Code Formは[MPL-2.0](https://www.mozilla.org/MPL/2.0/)の条件で提供します。対応するソースコードは[GitHubリポジトリ](https://github.com/kubohiroya/turbowarp-bubble)から取得できます。npmおよびCDNで配布するJavaScript bundleに対応するソースコードも、このリポジトリの同じpackage versionから参照できます。
193
+ ### インストール
55
194
 
56
- 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
195
+ ```sh
196
+ pnpm add @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
197
+ ```
57
198
 
58
- ## インストール
199
+ npmを使う場合は同じ依存を次のように追加します。
59
200
 
60
201
  ```sh
61
- pnpm add @kubohiroya/turbowarp-bubble \
62
- @kubohiroya/turbowarp-asset-manager \
63
- @kubohiroya/turbowarp-svg-text \
202
+ npm install @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
203
+ ```
204
+
205
+ 現在の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です。
206
+
207
+ 画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
208
+
209
+ ```sh
210
+ pnpm add @kubohiroya/turbowarp-asset-manager \
64
211
  @kubohiroya/turbowarp-async-input \
65
212
  @kubohiroya/turbowarp-runtime-expression
66
213
  ```
67
214
 
68
- 現在のpeer dependency範囲は、Asset Manager `>=0.7.0 <1`、SVG Text、Async Input、Runtime Expressionがそれぞれ`>=0.3.0 <1`です。
215
+ ```sh
216
+ npm install @kubohiroya/turbowarp-asset-manager \
217
+ @kubohiroya/turbowarp-async-input \
218
+ @kubohiroya/turbowarp-runtime-expression
219
+ ```
220
+
221
+ ### TurboWarp機能拡張
222
+
223
+ ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
224
+
225
+ #### TurboWarpでの導入
69
226
 
70
- ## TurboWarp機能拡張
227
+ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget APIへ接続する**unsandboxedカスタム拡張機能**です。TurboWarp Editorでは、次の順で読み込みます。
71
228
 
72
- ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-advance`、入力成立、`close`までのアニメーション例も掲載しています。
229
+ 1. TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
230
+ 2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
231
+ 3. SVG Textを読み込みます。Bubbleの文字style定義と文字幅計測に必要です。
232
+ 4. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Managerを読み込みます。
233
+ 5. `wait with this bubble until condition ...`を使う場合はAsync InputとRuntime Expressionを読み込みます。
234
+ 6. 最後にBubbleを読み込みます。依存拡張を先に読み込むと、対応するブロックとcapabilityが接続されます。
73
235
 
74
- TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、「カスタム拡張機能」から次の5本をサンドボックスなしで読み込みます。Async InputとRuntime ExpressionはBubble待機より前に、Asset ManagerとSVG Textは最初のBubble表示より前にロードします。
236
+ 最小構成はTemporary Variables、SVG Text、Bubbleです。Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define text style`、`define bubble style`、`say`または`think`の順でブロックを配置します。
75
237
 
76
238
  ```text
77
- https://unpkg.com/@kubohiroya/turbowarp-asset-manager/dist/asset-manager.js
78
- https://unpkg.com/@kubohiroya/turbowarp-svg-text/dist/svg-text.js
79
- https://unpkg.com/@kubohiroya/turbowarp-async-input/dist/async-input.js
80
- https://unpkg.com/@kubohiroya/turbowarp-runtime-expression/dist/runtime-expression.js
81
- https://unpkg.com/@kubohiroya/turbowarp-bubble/dist/turbowarp-bubble.js
239
+ # SVG Text(必須)
240
+ https://unpkg.com/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js
241
+
242
+ # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
243
+ https://unpkg.com/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js
244
+
245
+ # 条件待ちを使う場合だけ追加
246
+ https://unpkg.com/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js
247
+ https://unpkg.com/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js
248
+
249
+ # Bubble(必ず最後)
250
+ https://unpkg.com/@kubohiroya/turbowarp-bubble@0.3.0/dist/turbowarp-bubble.js
82
251
  ```
83
252
 
253
+ TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発中は、リポジトリをローカルHTTPサーバーで配信して`dist/turbowarp-bubble.js`を指定できます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。
254
+
255
+ #### Scratchとの互換性
256
+
257
+ Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカスタム拡張機能として直接利用することはできません。Scratch公式にはTurboWarpのunsandboxed拡張機能、renderer内部API、target drawable APIがないためです。Scratch向けの.sb3プロジェクトへこのREADMEのURLを追加しても、Bubbleのブロックは登録されません。
258
+
259
+ 利用環境ごとの位置付けは次のとおりです。
260
+
261
+ | 環境 | 利用方法 | 対応 |
262
+ | ------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
263
+ | TurboWarp Editor | `dist/turbowarp-bubble.js`をunsandboxedカスタム拡張機能として読み込む | 対応 |
264
+ | TurboWarp Packager/互換runtime | unsandboxedカスタム拡張機能とrenderer APIが利用できる構成で読み込む | 対応(環境ごとに確認が必要) |
265
+ | Scratch公式エディター | 公式拡張機能またはサンドボックス拡張機能として読み込む | 非対応 |
266
+ | 独自Webアプリ/ホスト | npmのcomposition APIまたはTurboWarp adapterをJavaScriptから利用する | 対応 |
267
+
268
+ Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
269
+
84
270
  Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。SVG本体、文字、表情ベース、目パチ、口パク、次へアイコンのrenderer drawableは自動生成されるため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
85
271
 
86
- ### 提供ブロック
272
+ #### 提供ブロック
87
273
 
88
274
  | ブロック | 動作 |
89
275
  | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
@@ -95,11 +281,11 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
95
281
  | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含むBubble全体の拡大率を設定する |
96
282
  | `set portrait base [ASSET] for bubble style [STYLE]` | 表情ベース画像を設定する。空文字でportrait全体を解除する |
97
283
  | `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フレーム以上必要。空リストで解除する |
284
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
285
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
100
286
  | `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始または置換する |
101
287
  | `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始または置換する |
102
- | `set this bubble animation mode [MODE]` | `talking`/`awaiting-advance`/`idle`を切り替える |
288
+ | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を切り替える |
103
289
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | 条件成立またはtimeoutまでBubbleを表示したまま待つ |
104
290
  | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
105
291
  | `Bubble version` | 実装versionを返す |
@@ -108,7 +294,7 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
108
294
 
109
295
  visual styleを設定しない場合は`NORMAL`です。本体drawableは文字・表情より背面に生成され、close、対象停止、runtime破棄時にSVG skinとともに解放されます。
110
296
 
111
- ### Placement
297
+ #### Placement
112
298
 
113
299
  `PLACEMENT`はActor相対と背景相対の二系統です。省略時は`up-right`です。
114
300
 
@@ -130,7 +316,7 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
130
316
 
131
317
  ![Actor相対の16方向・角度指定と、背景相対の3配置を比較する図](docs/assets/placement-guide.svg)
132
318
 
133
- 図中の16方向は、それぞれActor、実際のBubble外形、tail、文字を含むミニシーンです。本体とtailはJSClipperのunionによる単一pathなので、接合部に内部border線はありません。背景相対3図はStage外枠、安全領域、外形寸法、水平中央線、基準辺/中心を示します。図とTurboWarp Editorの本体drawableは、どちらも共有`renderBubbleSvg`から生成します。
319
+ 図中の16方向は、それぞれActor、実際のBubble外形、tail、文字を含む表示例です。本体とtailはJSClipperのunionによる単一pathなので、接合部に内部border線はありません。背景相対3図はStage外枠、安全領域、外形寸法、水平中央線、基準辺/中心を示します。図とTurboWarp Editorの本体drawableは、どちらも共有`renderBubbleSvg`から生成します。
134
320
 
135
321
  ![Actor相対のdistance、tail length、offset、scaleを比較する図](docs/assets/actor-transform-guide.svg)
136
322
 
@@ -138,17 +324,79 @@ Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box
138
324
 
139
325
  `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
326
 
141
- ### Animation mode
327
+ #### Portraitとblink / lip-sync
328
+
329
+ portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
330
+
331
+ ```mermaid
332
+ flowchart TB
333
+ bubble[Bubble surface]
334
+ body[Bubble body / text]
335
+ base[portraitBase\n顔・髪・輪郭]
336
+ blink[portraitBlink\n目パチ差分]
337
+ lipsync[portraitLipSync\n口パク差分]
338
+ continue[continueIndicator\n次へアイコン]
339
+ bubble --> body
340
+ bubble --> base
341
+ base --> blink
342
+ base --> lipsync
343
+ bubble --> continue
344
+ ```
345
+
346
+ | レイヤー | 表示中の動作 | 設定ブロック/API |
347
+ | ------------------- | ------------------------------------------------------ | ------------------------------------------- |
348
+ | `portraitBase` | 常時表示するベース画像 | `set portrait base` / `portrait.base` |
349
+ | `portraitBlink` | `talking`、`awaiting-continue`、`idle`のすべてでループ | `set blink frames` / `portrait.blink` |
350
+ | `portraitLipSync` | `talking`中だけループし、待機時は停止・非表示 | `set lip-sync frames` / `portrait.lipSync` |
351
+ | `continueIndicator` | `awaiting-continue`中だけループ | `set continue frames` / `continueIndicator` |
352
+
353
+ 目パチと口パクは1枚の静止画でも利用できます。口パクのキーワードは、話す行為全体ではなく口元の表情差分を指定する意味で`lip-sync`に統一しています。`continue`は、入力待ちを表すアイコンのanimationであり、JavaScriptの`continue`文を実行する機能ではありません。
354
+
355
+ ![portrait base、blink、lip-sync、continue indicatorを別レイヤーとして重ねる概念図](docs/assets/animation-mode-guide.svg)
356
+
357
+ #### Bubble animation
358
+
359
+ Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
360
+
361
+ ```mermaid
362
+ flowchart LR
363
+ start[表示開始] --> in[表示開始animation\nfadeIn / floatIn / zoomIn / riseUp]
364
+ in --> visible[表示中]
365
+ visible --> shake[shake\n方向・回数・ease]
366
+ visible --> explode[explode\n相対サイズ・回数・ease]
367
+ visible --> shape[animateBubbleShape\n速度・時間]
368
+ visible --> waiting[awaiting-continue]
369
+ waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
370
+ out --> released[close・resource解放]
371
+ ```
372
+
373
+ ##### 表示開始と表示終了
374
+
375
+ PowerPointの用語を参考にしつつ、Bubbleの仕様名は「表示開始animation」「表示終了animation」とします。表示開始には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。表示開始・表示終了animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、表示終了時には現在の外形を基準に終点を計算します。
376
+
377
+ ##### 表示中の変形
142
378
 
143
- | mode | 目パチ | 口パク | advance frames |
144
- | ------------------ | ------ | ------------ | -------------- |
145
- | `talking` | 実行 | 実行 | 非表示 |
146
- | `awaiting-advance` | 実行 | 停止・非表示 | ループ実行 |
147
- | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
379
+ - `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
380
+ - `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
381
+ - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
148
382
 
149
- `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-advance`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
383
+ TurboWarp adapterは16ms単位のscheduler tickで各animationを進め、`ease`を各フレームの進行率へ適用します。`fadeIn`/`fadeOut`はrendererの`ghost`効果、`float`/`rise`/`sink`は位置、`zoom`/`explode`は倍率をText・portrait・Bubble本体へ同じように適用します。`shake`は指定回数の往復を行い、`explode`は拡大と復帰を繰り返します。`durationSeconds`を省略した`shake`/`explode`には、回数に応じた既定時間を使います。
150
384
 
151
- ### ブロック構成例
385
+ `animateBubbleShape`は、現在形状と指定形状を各フレームでcross-fadeするSVG body skinへ更新します。Textとportraitは再生成せず、外形だけを連続的に切り替えます。`speed`は指定時間内の形状遷移速度倍率です。
386
+
387
+ animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとdrawableを先に解放します。`shake`には`ease`を指定でき、`explode`には`relativeScale`、`count`、`ease`、`animateBubbleShape`には`speed`と`durationSeconds`を指定できます。
388
+
389
+ #### Animation mode
390
+
391
+ | mode | 目パチ | 口パク | continue frames |
392
+ | ------------------- | ------ | ------------ | --------------- |
393
+ | `talking` | 実行 | 実行 | 非表示 |
394
+ | `awaiting-continue` | 実行 | 停止・非表示 | ループ実行 |
395
+ | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
396
+
397
+ `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
398
+
399
+ #### ブロック構成例
152
400
 
153
401
  ```text
154
402
  define bubble style [hero-dialogue] using text style [dialogue-text]
@@ -159,8 +407,8 @@ set bubble tail length [18] for bubble style [hero-dialogue]
159
407
  set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
160
408
  set portrait base [HeroFace] for bubble style [hero-dialogue]
161
409
  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]
410
+ set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
411
+ set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
164
412
  set runtime variable [input] to []
165
413
  listen for key [Space] set runtime var [input] to [pressed]
166
414
  listen for touch on this sprite set runtime var [input] to [pressed]
@@ -171,9 +419,9 @@ close this bubble
171
419
 
172
420
  プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、SVG text skin、drawableを自動解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
173
421
 
174
- ## Composition API
422
+ ### Composition API
175
423
 
176
- TurboWarp runtimeのrenderer、Asset Manager、SVG Textへ直接接続するhostでは、公開adapterを利用できます。
424
+ TurboWarp runtimeのrenderer、SVG Textへ直接接続するhostでは、公開adapterを利用できます。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
177
425
 
178
426
  ```ts
179
427
  import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
@@ -184,43 +432,43 @@ const bubbles = createTurboWarpBubbleComposition(runtime);
184
432
  描画surfaceをhost側で実装する場合は、以下の低レベルComposition APIを利用します。
185
433
 
186
434
  ```ts
187
- import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
188
- import { createSvgTextComposition } from "@kubohiroya/turbowarp-svg-text/composition";
189
- import { createBubbleComposition } from "@kubohiroya/turbowarp-bubble/composition";
190
-
191
- const assetManager = createAssetManagerComposition();
192
- const svgText = createSvgTextComposition({ runtime });
193
-
194
- svgText.defineStyle({
195
- name: "dialogue-text",
196
- backgroundColor: "#ffffff",
197
- textColor: "#332200",
198
- font: "Noto Sans JP",
199
- fontPercent: 100,
200
- alignment: "left",
201
- });
435
+ import {
436
+ createBubbleComposition,
437
+ type BubbleImageCapability,
438
+ type BubbleSurfaceFactory,
439
+ type BubbleSvgText,
440
+ } from "@kubohiroya/turbowarp-bubble/composition";
441
+
442
+ // These are host-owned capabilities. They may be backed by Asset Manager,
443
+ // another asset service, or local application code.
444
+ declare const imageResolver: BubbleImageCapability;
445
+ declare const svgText: BubbleSvgText;
446
+ declare const bubbleSurfaceHost: BubbleSurfaceFactory;
202
447
 
203
448
  const bubbles = createBubbleComposition({
204
- assetManager,
449
+ imageResolver,
205
450
  svgText,
206
- async createSurface({ actor, actorKey, kind, style }) {
207
- // hostがActorの近くへsurfaceを配置し、各レイヤー用のtargetを返します。
208
- return bubbleSurfaceHost.create({ actor, actorKey, kind, style });
209
- },
451
+ createSurface: bubbleSurfaceHost,
210
452
  });
211
453
  ```
212
454
 
455
+ `declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleSvgText`(文字skinの適用・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
456
+
457
+ テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
458
+
213
459
  `createSurface`が返すsurfaceは、次のtargetを持ちます。
214
460
 
461
+ surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
462
+
215
463
  - `text`: SVG Textが文字スキンを適用するtarget
216
464
  - `portraitBase`: キャラクター表情のベース画像target
217
465
  - `portraitBlink`: 目パチ差分target
218
- - `portraitTalk`: 口パク差分target
219
- - `advanceIndicator`: 「次へ」アイコンtarget
466
+ - `portraitLipSync`: 口パク差分target
467
+ - `continueIndicator`: 「次へ」アイコンtarget
220
468
 
221
469
  画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
222
470
 
223
- ## Styleと表示
471
+ #### Styleと表示
224
472
 
225
473
  ```ts
226
474
  bubbles.defineStyle({
@@ -237,21 +485,35 @@ bubbles.defineStyle({
237
485
  frames: ["HeroEyesOpen", "HeroEyesClosed"],
238
486
  frameIntervalSeconds: 0.4,
239
487
  },
240
- talk: {
488
+ lipSync: {
241
489
  frames: ["HeroMouthClosed", "HeroMouthOpen"],
242
490
  frameIntervalSeconds: 0.1,
243
491
  },
244
492
  },
245
- advanceIndicator: {
493
+ continueIndicator: {
246
494
  frames: ["Next1", "Next2"],
247
495
  frameIntervalSeconds: 0.2,
248
496
  },
497
+ reveal: {
498
+ unit: "CHARACTER",
499
+ layout: "RESERVED",
500
+ intervalSeconds: 0.05,
501
+ sound: "Typewriter",
502
+ },
503
+ audio: {
504
+ voice: "HeroVoice",
505
+ reveal: "Typewriter",
506
+ },
507
+ showAnimation: { name: "fadeIn", durationSeconds: 0.2 },
508
+ hideAnimation: { name: "fadeOut", durationSeconds: 0.2 },
249
509
  });
250
510
 
251
511
  bubbles.defineStyle({
252
512
  name: "narration",
253
513
  textStyle: "dialogue-text",
254
514
  placement: "FOOTER_LIKE",
515
+ maxWidth: 320,
516
+ textLocale: "ja",
255
517
  });
256
518
 
257
519
  const bubble = await bubbles.show({
@@ -263,25 +525,39 @@ const bubble = await bubbles.show({
263
525
  });
264
526
  ```
265
527
 
266
- `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-advance`へ変更します。
528
+ `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-continue`へ変更します。
267
529
 
268
530
  ```ts
269
- await bubble.setAnimationMode("awaiting-advance");
531
+ await bubble.setAnimationMode("awaiting-continue");
270
532
  // 口パクを停止して非表示にし、「次へ」アイコンをループ表示します。
271
533
 
272
534
  await bubble.setAnimationMode("idle");
273
535
  // 吹き出しを残したまま、口パクと「次へ」アイコンを停止します。
274
536
 
537
+ await bubble.revealNext();
538
+ await bubble.revealAll();
539
+ await bubble.animate({
540
+ name: "shake",
541
+ direction: 90,
542
+ count: 2,
543
+ ease: "easeInOut",
544
+ });
545
+ await bubble.finish({
546
+ unit: "CHARACTER",
547
+ condition: () => inputState === "pressed",
548
+ timeoutSeconds: 10,
549
+ });
550
+
275
551
  await bubble.close();
276
552
  ```
277
553
 
278
- 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、SVG Text target、surfaceを解放します。composition間で状態は共有しません。
554
+ 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、SVG Text target、surfaceを解放します。composition間で状態は共有しません。
279
555
 
280
- ## DSL 4.0との関係
556
+ ## ライセンスとソースコード
281
557
 
282
- このパッケージは`bubbleStyles`を含むDSLを解析しません。紙芝居アプリ側のadapterが、例えば`placement: north-northeast`、`placement: 33.75`、`placement: FOOTER_LIKE`を`defineStyle`へ渡し、表示ライフサイクルに合わせて`show`、`setAnimationMode`、`close`を呼び出します。
558
+ このパッケージのSource Code Formは[MPL-2.0](https://www.mozilla.org/MPL/2.0/)の条件で提供します。対応するソースコードは[GitHubリポジトリ](https://github.com/kubohiroya/turbowarp-bubble)から取得できます。npmおよびCDNで配布するJavaScript bundleに対応するソースコードも、このリポジトリの同じpackage versionから参照できます。
283
559
 
284
- アプリ統合は起動時固定・既定OFFのfeature flagで段階導入します。ロールバック時はflagをOFFにし、既存のTurboWarp say/think経路へ戻します。
560
+ 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
285
561
 
286
562
  ## 開発
287
563