@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.
package/README.md CHANGED
@@ -1,6 +1,15 @@
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との互換性)に記載しています。
4
13
 
5
14
  ## 機能の全体像
6
15
 
@@ -16,25 +25,27 @@ flowchart LR
16
25
  body --> portrait[portraitレイヤー]
17
26
  portrait --> blink[blink]
18
27
  portrait --> lipsync[lip-sync]
19
- body --> motion[入場・中間・退場animation]
28
+ body --> motion[表示開始・表示中・表示終了animation]
20
29
  body --> wait[continue待機]
21
30
  wait --> close[終了・resource解放]
22
31
  ```
23
32
 
24
33
  このREADMEでは、現在公開している機能と、3層構成で接続する表示仕様を同じ用語で説明します。公開APIにまだ現れていない仕様は「実装状況」欄で明示しています。
25
34
 
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は未公開 |
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設定、対応ブロック) |
34
43
 
35
- ## 3層構成と責務
44
+ ## 概念と表示仕様
36
45
 
37
- 依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。
46
+ ### 3層構成と責務
47
+
48
+ 依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。矢印は「利用する側」から「利用される側」へ向けています。
38
49
 
39
50
  ```mermaid
40
51
  flowchart TB
@@ -44,16 +55,18 @@ flowchart TB
44
55
  image[Image capability\nportrait・blink・lip-sync・continue画像]
45
56
  audio[Audio capability\nvoice・表示単位ごとの効果音]
46
57
  input[Async Input + Runtime Expression\n入力と待機条件]
47
- core --> adapter
58
+ extension[TurboWarp extension\nblocks / Scratch target]
59
+ adapter --> core
48
60
  adapter --> text
49
61
  core -.任意Capability.-> image
50
62
  core -.任意Capability.-> audio
51
- core -.任意Capability.-> input
63
+ extension --> core
64
+ extension -.optional.-> input
52
65
  ```
53
66
 
54
- `@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portraitの配置、入退場animationは担当しません。Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyで、対応する機能を使う場合だけ接続します。
67
+ `@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationは担当しません。画像解決、音声再生、入力、条件評価はCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyとして対応機能を使う場合だけ接続します。
55
68
 
56
- ## 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
69
+ ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
57
70
 
58
71
  セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
59
72
 
@@ -61,14 +74,14 @@ flowchart TB
61
74
 
62
75
  ```mermaid
63
76
  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[区切り文字を隠して描画]
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["区切り文字を隠して描画"]
72
85
  delimiter --> visibility
73
86
  ```
74
87
 
@@ -104,7 +117,7 @@ sequenceDiagram
104
117
  end
105
118
  ```
106
119
 
107
- `RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。いずれもBubble外形のanimationやportraitレイヤーとは独立したレイアウト方針です。現行の公開composition APIでは`show`と`handle.setText()`がこの接続点になり、逐次表示の分割・タイミングはhostが制御します。
120
+ `RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。いずれもBubble外形のanimationやportraitレイヤーとは独立したレイアウト方針です。Composition APIではstyleの`reveal`、`handle.revealNext()`、`handle.revealAll()`が分割・タイミングの接続点になり、`intervalSeconds`を指定した自動送りにも対応します。
108
121
 
109
122
  逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
110
123
 
@@ -114,10 +127,12 @@ finish [CHARACTER / WORD / LINE / BLOCK]
114
127
  or timeout after [TIMEOUT] seconds
115
128
  ```
116
129
 
117
- `CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または退場animationを開始します。`finish`の公開block/APIは現在のBubbleにはまだなく、既存の`wait with this bubble ...`は全文表示後の入力待ちに対応します。
130
+ `CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または表示終了animationを開始します。Composition APIでは`handle.finish({ unit, condition, timeoutSeconds })`、手続き型拡張では`finish [UNIT] ...`ブロックを使います。
118
131
 
119
132
  ### 音声と表示単位
120
133
 
134
+ `finish`は公開Composition APIの`handle.finish({ unit, condition, timeoutSeconds })`と、TurboWarpの`finish [UNIT] ...`ブロックで利用できます。これは逐次表示を最後まで進め、条件成立またはtimeoutで音声と待機状態を確定します。
135
+
121
136
  Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
122
137
 
123
138
  - 表示開始時のフルボイス
@@ -126,20 +141,20 @@ Asset Managerを音声providerとして接続すると、次の音声を同じ
126
141
 
127
142
  表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声assetを再生する経路です。音声がない場合でも、文字表示・portrait・Bubble外形は独立して利用できます。
128
143
 
129
- ## パッケージ境界
144
+ ### パッケージ境界
130
145
 
131
- | パッケージ | 責務 |
132
- | ------------------------------------------ | ------------------------------------------------------------------------- |
133
- | `@kubohiroya/turbowarp-asset-manager` | アセット名の登録、画像種別の検証、画像targetへの適用、音声再生 |
134
- | `@kubohiroya/turbowarp-svg-text` | 名前付き文字styleと、文字列からSVGスキンへの変換 |
135
- | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
136
- | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
137
- | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、say/think、表情レイヤー、animation mode、入力待機 |
138
- | アプリ/host | 必要に応じたDSLからcomposition APIへの変換 |
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への変換 |
139
154
 
140
- Bubbleは依存パッケージを再exportしません。SVG Textは現在の文字描画に必要ですが、Asset Manager、Async Input、Runtime Expressionは利用する機能がなければインストール不要です。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
155
+ Bubbleは依存パッケージを再exportしません。SVG Textは現在の文字描画に必要ですが、画像・音声・入力・条件評価はCapabilityとして差し替えられます。TurboWarp adapterではAsset Managerを自動接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
141
156
 
142
- ## 自動改行と禁則処理の基盤
157
+ ### 自動改行と禁則処理の基盤
143
158
 
144
159
  Bubbleの任意`maxWidth`による自動改行では、`@cto.af/linebreak`を利用してUnicode UAX #14準拠の改行可能位置を求めます。依存は`LineBreakProvider` interfaceの内側へ閉じ込め、実際のフォントで測った幅から、上限内に収まる最も後ろの候補をBubble側で選びます。
145
160
 
@@ -161,7 +176,7 @@ Composition APIのBubble styleへ`maxWidth`と任意の`textLocale`を渡すと
161
176
 
162
177
  図の各行はproductionの`wrapText`を直接呼んだ結果です。図版専用の手作業改行は使っていません。
163
178
 
164
- ## Bubble visual styleの形状
179
+ ### Bubble visual styleの形状
165
180
 
166
181
  形状候補は`NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`です。
167
182
 
@@ -173,16 +188,18 @@ standalone機能拡張では、`set bubble visual style`ブロックで形状を
173
188
 
174
189
  配布bundleに含まれる依存ライブラリのライセンスは、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)を参照してください。
175
190
 
176
- ## ライセンスとソースコード
191
+ ## 利用方法
177
192
 
178
- このパッケージの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
+ ### インストール
179
194
 
180
- 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
195
+ ```sh
196
+ pnpm add @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
197
+ ```
181
198
 
182
- ## インストール
199
+ npmを使う場合は同じ依存を次のように追加します。
183
200
 
184
201
  ```sh
185
- pnpm add @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
202
+ npm install @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
186
203
  ```
187
204
 
188
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です。
@@ -195,23 +212,64 @@ pnpm add @kubohiroya/turbowarp-asset-manager \
195
212
  @kubohiroya/turbowarp-runtime-expression
196
213
  ```
197
214
 
198
- ## TurboWarp機能拡張
215
+ ```sh
216
+ npm install @kubohiroya/turbowarp-asset-manager \
217
+ @kubohiroya/turbowarp-async-input \
218
+ @kubohiroya/turbowarp-runtime-expression
219
+ ```
220
+
221
+ ### TurboWarp機能拡張
199
222
 
200
223
  ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
201
224
 
202
- TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、「カスタム拡張機能」からSVG TextとBubbleをサンドボックスなしで読み込みます。portrait、lip-sync、continue indicator、または音声アセットを使う場合だけAsset Managerを追加し、待機ブロックを使う場合だけAsync InputとRuntime Expressionを追加します。各依存が必要な機能を実行する前にロードしてください。
225
+ #### TurboWarpでの導入
226
+
227
+ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget APIへ接続する**unsandboxedカスタム拡張機能**です。TurboWarp Editorでは、次の順で読み込みます。
228
+
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が接続されます。
235
+
236
+ 最小構成はTemporary Variables、SVG Text、Bubbleです。Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define text style`、`define bubble style`、`say`または`think`の順でブロックを配置します。
203
237
 
204
238
  ```text
205
- https://unpkg.com/@kubohiroya/turbowarp-asset-manager/dist/asset-manager.js
206
- https://unpkg.com/@kubohiroya/turbowarp-svg-text/dist/svg-text.js
207
- https://unpkg.com/@kubohiroya/turbowarp-async-input/dist/async-input.js
208
- https://unpkg.com/@kubohiroya/turbowarp-runtime-expression/dist/runtime-expression.js
209
- 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
210
251
  ```
211
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
+
212
270
  Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。SVG本体、文字、表情ベース、目パチ、口パク、次へアイコンのrenderer drawableは自動生成されるため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
213
271
 
214
- ### 提供ブロック
272
+ #### 提供ブロック
215
273
 
216
274
  | ブロック | 動作 |
217
275
  | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
@@ -236,7 +294,7 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
236
294
 
237
295
  visual styleを設定しない場合は`NORMAL`です。本体drawableは文字・表情より背面に生成され、close、対象停止、runtime破棄時にSVG skinとともに解放されます。
238
296
 
239
- ### Placement
297
+ #### Placement
240
298
 
241
299
  `PLACEMENT`はActor相対と背景相対の二系統です。省略時は`up-right`です。
242
300
 
@@ -258,7 +316,7 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
258
316
 
259
317
  ![Actor相対の16方向・角度指定と、背景相対の3配置を比較する図](docs/assets/placement-guide.svg)
260
318
 
261
- 図中の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`から生成します。
262
320
 
263
321
  ![Actor相対のdistance、tail length、offset、scaleを比較する図](docs/assets/actor-transform-guide.svg)
264
322
 
@@ -266,7 +324,7 @@ Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box
266
324
 
267
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では無視します。
268
326
 
269
- ### Portraitとblink / lip-sync
327
+ #### Portraitとblink / lip-sync
270
328
 
271
329
  portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
272
330
 
@@ -296,37 +354,39 @@ flowchart TB
296
354
 
297
355
  ![portrait base、blink、lip-sync、continue indicatorを別レイヤーとして重ねる概念図](docs/assets/animation-mode-guide.svg)
298
356
 
299
- ### Bubble animation
357
+ #### Bubble animation
300
358
 
301
359
  Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
302
360
 
303
361
  ```mermaid
304
362
  flowchart LR
305
- start[表示開始] --> in[入場animation\nfadeIn / floatIn / zoomIn / riseUp]
363
+ start[表示開始] --> in[表示開始animation\nfadeIn / floatIn / zoomIn / riseUp]
306
364
  in --> visible[表示中]
307
365
  visible --> shake[shake\n方向・回数・ease]
308
366
  visible --> explode[explode\n相対サイズ・回数・ease]
309
367
  visible --> shape[animateBubbleShape\n速度・時間]
310
368
  visible --> waiting[awaiting-continue]
311
- waiting --> out[退場animation\nfadeOut / floatOut / zoomOut / sink]
369
+ waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
312
370
  out --> released[close・resource解放]
313
371
  ```
314
372
 
315
- #### 入場と退場
373
+ ##### 表示開始と表示終了
316
374
 
317
- PowerPointの用語に寄せ、入場には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、退場には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。入場・退場animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、退場時には現在の外形を基準に終点を計算します。
375
+ PowerPointの用語を参考にしつつ、Bubbleの仕様名は「表示開始animation」「表示終了animation」とします。表示開始には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。表示開始・表示終了animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、表示終了時には現在の外形を基準に終点を計算します。
318
376
 
319
- #### 表示中の変形
377
+ ##### 表示中の変形
320
378
 
321
379
  - `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
322
380
  - `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
323
- - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を時間経過で補間します。`visualStyle`の切替と、切替中の形状補間を分離できます。
381
+ - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
324
382
 
325
- animationは`show`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとdrawableを先に解放します。
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`には、回数に応じた既定時間を使います。
326
384
 
327
- > **実装状況:** 現在の公開composition APIで利用できるBubble motionは、visual styleの設定と`talking`/`awaiting-continue`/`idle`のmode切替です。上記の入場・退場・`shake`・`explode`・`animateBubbleShape`を外部hostから指定する正式なメソッド/ブロックは、後方互換性を壊さない形で追加する予定です。
385
+ `animateBubbleShape`は、現在形状と指定形状を各フレームでcross-fadeするSVG body skinへ更新します。Textとportraitは再生成せず、外形だけを連続的に切り替えます。`speed`は指定時間内の形状遷移速度倍率です。
328
386
 
329
- ### Animation mode
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
330
390
 
331
391
  | mode | 目パチ | 口パク | continue frames |
332
392
  | ------------------- | ------ | ------------ | --------------- |
@@ -336,7 +396,7 @@ animationは`show`、`handle.setAnimationMode()`、`handle.updateStyle()`、`han
336
396
 
337
397
  `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
338
398
 
339
- ### ブロック構成例
399
+ #### ブロック構成例
340
400
 
341
401
  ```text
342
402
  define bubble style [hero-dialogue] using text style [dialogue-text]
@@ -359,7 +419,7 @@ close this bubble
359
419
 
360
420
  プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、SVG text skin、drawableを自動解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
361
421
 
362
- ## Composition API
422
+ ### Composition API
363
423
 
364
424
  TurboWarp runtimeのrenderer、SVG Textへ直接接続するhostでは、公開adapterを利用できます。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
365
425
 
@@ -372,32 +432,28 @@ const bubbles = createTurboWarpBubbleComposition(runtime);
372
432
  描画surfaceをhost側で実装する場合は、以下の低レベルComposition APIを利用します。
373
433
 
374
434
  ```ts
375
- import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
376
- import { createSvgTextComposition } from "@kubohiroya/turbowarp-svg-text/composition";
377
- import { createBubbleComposition } from "@kubohiroya/turbowarp-bubble/composition";
378
-
379
- const imageResolver = createAssetManagerComposition();
380
- const svgText = createSvgTextComposition({ runtime });
381
-
382
- svgText.defineStyle({
383
- name: "dialogue-text",
384
- backgroundColor: "#ffffff",
385
- textColor: "#332200",
386
- font: "Noto Sans JP",
387
- fontPercent: 100,
388
- alignment: "left",
389
- });
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;
390
447
 
391
448
  const bubbles = createBubbleComposition({
392
449
  imageResolver,
393
450
  svgText,
394
- async createSurface({ actor, actorKey, kind, style }) {
395
- // hostがActorの近くへsurfaceを配置し、各レイヤー用のtargetを返します。
396
- return bubbleSurfaceHost.create({ actor, actorKey, kind, style });
397
- },
451
+ createSurface: bubbleSurfaceHost,
398
452
  });
399
453
  ```
400
454
 
455
+ `declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleSvgText`(文字skinの適用・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
456
+
401
457
  テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
402
458
 
403
459
  `createSurface`が返すsurfaceは、次のtargetを持ちます。
@@ -412,7 +468,7 @@ surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・
412
468
 
413
469
  画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
414
470
 
415
- ## Styleと表示
471
+ #### Styleと表示
416
472
 
417
473
  ```ts
418
474
  bubbles.defineStyle({
@@ -438,6 +494,18 @@ bubbles.defineStyle({
438
494
  frames: ["Next1", "Next2"],
439
495
  frameIntervalSeconds: 0.2,
440
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 },
441
509
  });
442
510
 
443
511
  bubbles.defineStyle({
@@ -466,16 +534,30 @@ await bubble.setAnimationMode("awaiting-continue");
466
534
  await bubble.setAnimationMode("idle");
467
535
  // 吹き出しを残したまま、口パクと「次へ」アイコンを停止します。
468
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
+
469
551
  await bubble.close();
470
552
  ```
471
553
 
472
554
  返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、SVG Text target、surfaceを解放します。composition間で状態は共有しません。
473
555
 
474
- ## DSL 4.0との関係
556
+ ## ライセンスとソースコード
475
557
 
476
- このパッケージは`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から参照できます。
477
559
 
478
- アプリ統合は起動時固定・既定OFFのfeature flagで段階導入します。ロールバック時はflagをOFFにし、既存のTurboWarp say/think経路へ戻します。
560
+ 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
479
561
 
480
562
  ## 開発
481
563