@kubohiroya/turbowarp-bubble 0.8.0 → 0.10.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_ja.md ADDED
@@ -0,0 +1,709 @@
1
+ # TurboWarp Bubble
2
+
3
+ [English](README.md) | **日本語**
4
+
5
+ `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
6
+
7
+ 現在のリリースはBubble 0.10.0です。既定の描画経路はSVG Text 0.8.1を使うskin非依存のSVG overlayです。TurboWarpですべての機能を使う場合、現在の推奨組み合わせはAsset Manager 0.12.1、Async Input 0.4.0、Runtime Expression 0.4.0です。再利用可能な名前付きclose policyについては[0.10.0 release notes](docs/release-notes-0.10.0.md)、組み込み`say`/`think` styleについては[0.9.0 release notes](docs/release-notes-0.9.0.md)を参照してください。
8
+
9
+ ## READMEの読み方
10
+
11
+ 利用環境を先に決めると、必要な部分だけを読めます。
12
+
13
+ 1. TurboWarpでブロックを使う場合は、後述の[TurboWarp機能拡張](#turbowarp機能拡張)と[提供ブロック](#提供ブロック)を確認します。
14
+ 2. 独自Webアプリやhostから使う場合は、[Composition API](#composition-api)と[Styleと表示](#styleと表示)を確認します。
15
+ 3. 表示単位、改行、外形、portrait、animationの仕様を知りたい場合は、[概念と表示仕様](#概念と表示仕様)を参照します。
16
+ 4. Scratch公式エディターでの利用可否は、[Scratchとの互換性](#scratchとの互換性)に記載しています。
17
+
18
+ ## 機能の全体像
19
+
20
+ Bubbleは、文字を描くText provider、吹き出しの外形と配置を管理するBubble layer、画像・音声を解決する任意のAsset capabilityを組み合わせます。これにより、TurboWarpの機能拡張としても、アプリのhostから呼び出すcompositionとしても同じ表示モデルを利用できます。
21
+
22
+ ```mermaid
23
+ flowchart LR
24
+ input[セリフ入力] --> reveal[表示単位の選択]
25
+ reveal --> text[CHARACTER / WORD / LINE / BLOCK]
26
+ text --> layout[改行・サイズ計算]
27
+ layout --> body[Bubble外形・tail・placement]
28
+ text --> voice[フルボイス/単位ごとの効果音]
29
+ body --> portrait[portraitレイヤー]
30
+ portrait --> blink[blink]
31
+ portrait --> lipsync[lip-sync]
32
+ body --> motion[表示開始・表示中・表示終了animation]
33
+ body --> wait[continue待機]
34
+ wait --> close[終了・resource解放]
35
+ ```
36
+
37
+ 次の表は0.10.0の機能と公開entry pointの対応です。standalone機能拡張は33定義から31個のpaletteブロックを公開し、保存済みprojectの互換性のため旧styled say/think 2定義を非表示で維持します。表示される全ブロックは[提供ブロック](#提供ブロック)に掲載しています。
38
+
39
+ | 領域 | このREADMEで説明する内容 | 公開entry point |
40
+ | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
41
+ | 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | `composition`、`turbowarp-adapter`、機能拡張ブロック |
42
+ | 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | `composition`、軽量な`reveal` entry、機能拡張ブロック |
43
+ | portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | Asset Managerを介したComposition APIと機能拡張ブロック |
44
+ | Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | Composition API、TurboWarp adapter、機能拡張ブロック |
45
+ | 表示mode | `talking`/`awaiting-continue`/`idle` | `BubbleHandle.setAnimationMode()`と対応ブロック |
46
+ | 表示開始・表示中・表示終了animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | style設定、`BubbleHandle.animate()`、機能拡張ブロック |
47
+
48
+ ## 概念と表示仕様
49
+
50
+ ### 3層構成と責務
51
+
52
+ 依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。矢印は「利用する側」から「利用される側」へ向けています。
53
+
54
+ ```mermaid
55
+ flowchart TB
56
+ core["Bubble core\n外形・配置・ライフサイクル・animation state"]
57
+ contract["BubbleTextCapability\nhost-neutralな文字契約"]
58
+ twAdapter["TurboWarp Bubble adapter\nrenderer / runtime / targetへの接続"]
59
+ svgAdapter["SVG Text 0.8 layout adapter\nrenderer非依存の行layout・計測"]
60
+ assets["任意のImage / Audio capability\nportrait・lip-sync・音声"]
61
+ input["任意のInput / Expression capability\n入力・待機条件"]
62
+ host["独自Webアプリ / host"]
63
+ extension["TurboWarp extension\nblocks / Scratch target"]
64
+ core -->|"consumes"| contract
65
+ svgAdapter -->|"implements"| contract
66
+ twAdapter -->|"injects"| core
67
+ twAdapter -->|"uses by default"| svgAdapter
68
+ host -->|"injects"| core
69
+ core -."optional".-> assets
70
+ extension --> twAdapter
71
+ extension -."optional".-> input
72
+ ```
73
+
74
+ この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.8.1`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。standalone SVG Text 0.8.1が既にロードされている場合は、その公開`getLayoutCapability()`を利用し、project blockで定義済みのfont、色、size、alignmentを維持します。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
75
+
76
+ ### 描画backend(SVG overlayが既定)
77
+
78
+ `bubbleRenderBackend`を省略した場合の既定値は`"svg-overlay"`です。`renderer.addOverlay(root, "scale")`でstage canvas上に共有SVG rootを置き、body、tail、text、portrait、corner clip、continue indicatorをDOM要素として描画します。文字にはstandalone拡張の共有named-style registry、またはBubble内包compositionから得るSVG Text 0.8.1のhost-neutral layoutを使います。この既定経路ではBubbleの表示、text更新、style更新、animationのために`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばず、Bubble由来の処理はscratch-renderの`SVGSkin`/`Silhouette`経路へ入りません。`"scratch-render"`は互換性とロールバックのため明示指定時だけ使用します。
79
+
80
+ TurboWarpでstock Asset Manager 0.12.1をBubbleより先に読み込むと、Bubbleはportrait等を初めて使う時に`runtime.ext_kubohiroyaassetmanager.getDOMImageCapability()`を呼び、Asset Managerブロックで登録された同じregistryへ遅延接続します。文字だけを使う場合はAsset Managerを読み込みません。Composition APIのhostは、次のようにcapabilityを明示注入できます。
81
+
82
+ ```ts
83
+ import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
84
+ import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
85
+ import {
86
+ createAssetManagerSvgOverlayImageCapability,
87
+ createSvgTextOverlayTextCapability,
88
+ createTurboWarpBubbleComposition,
89
+ } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
90
+
91
+ const assets = createAssetManagerComposition();
92
+ const textLayouts = createSvgTextLayoutComposition();
93
+
94
+ textLayouts.defineStyle({
95
+ name: "dialogue-text",
96
+ alignment: "left",
97
+ backgroundColor: "transparent",
98
+ font: "Helvetica",
99
+ fontPercent: 100,
100
+ textColor: "#575e75",
101
+ });
102
+
103
+ const bubbles = createTurboWarpBubbleComposition(runtime, {
104
+ svgOverlayTextCapability: createSvgTextOverlayTextCapability(textLayouts),
105
+ svgOverlayImageCapability:
106
+ createAssetManagerSvgOverlayImageCapability(assets),
107
+ });
108
+ ```
109
+
110
+ `svgOverlayTextCapability`を省略し、standalone SVG Text 0.8.1がロード済みの場合、Bubbleはfrozenな`getLayoutCapability()`を取得し、SVG Text blockが更新する同じnamed-style registryを解決します。standaloneがない場合だけ、BubbleはSVG Text 0.8.1のlayout compositionを生成し、`default`および初めて参照されたtext-style名を背景透明の既定styleで初期化します。公開handoffがない古いstandaloneが存在する場合はproject styleを黙って置換せず`BUBBLE-RUNTIME-004`を返し、`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけscratch-renderへ戻ります。capabilityを明示注入すると両方の自動経路を置換できます。portrait等を使う場合、Bubble所有の`createAssetManagerSvgOverlayImageCapability()`がAsset Managerの汎用DOM resourceをBubbleの画像契約へ変換します。依存方向はBubbleからAsset Managerへの一方向であり、Asset ManagerはBubbleの型やsecurity markerを参照しません。adapterは両者が許可するMIME typeだけを公開し、検証済みMIME type、intrinsic size、`blob:` URL、`release()`を引き継ぎ、Asset ManagerがsanitizeしたSVGへBubble側のmetadataを付与します。Bubbleは任意SVG文字列を挿入せず、canonical bodyから`path`、`group`等の許可要素・属性だけを`createElementNS()`で再構築します。`script`、event handler、`foreignObject`、外部URLは受け付けません。overlay rootは`pointer-events: none`、`aria-hidden="true"`です。
111
+
112
+ 既定文字providerは直接依存するSVG Text 0.8.1です。別にロードしたstock SVG Textのstyleを維持するには0.8.1の`getLayoutCapability()`が必要です。stock画像拡張同士の自動接続には`getDOMImageCapability()`を公開するAsset Manager 0.12.1以降が必要です。Composition APIから`resolveDOMImageResource()`を明示注入する低レベル経路はAsset Manager 0.12.0以降で利用できます。
113
+
114
+ SVG Text/Asset Managerのskin非依存契約は[turbowarp-svg-text#26](https://github.com/kubohiroya/turbowarp-svg-text/issues/26)、[turbowarp-asset-manager#103](https://github.com/kubohiroya/turbowarp-asset-manager/issues/103)、stock registry handoffの[turbowarp-asset-manager#106](https://github.com/kubohiroya/turbowarp-asset-manager/issues/106)で公開済みです。Bubbleは上流の公開APIだけを利用し、private field参照やskinからの抽出では代替しません。overlay APIがないhostで`svg-overlay`を選ぶと`BUBBLE-RUNTIME-004`を返します。画像使用時にAsset Manager 0.12.1の公開capabilityも明示注入もない場合は`BUBBLE-RUNTIME-002`を返します。`svgOverlayUnsupportedBehavior: "fallback"`を明示した場合だけ、overlay API非対応hostで`scratch-render`へ戻ります。
115
+
116
+ | host/取得方法 | `scratch-render` | `svg-overlay` |
117
+ | ----------------------------------------- | ---------------- | ------------------------------------------------------ |
118
+ | TurboWarp Web/Desktop | 対応 | overlay APIと上記公開capabilityがある構成で対応 |
119
+ | TurboWarp Packager/player HTML | 対応 | 同上。packaged DOMにoverlay rootを保持できる場合に対応 |
120
+ | `renderer.addOverlay`非対応host | 対応 | 既定は明示error。設定時だけfallback |
121
+ | OS screenshot/画面収録 | 表示される | 最終browser compositeに表示される |
122
+ | `renderer.canvas.toDataURL()`/`toBlob()` | 表示される | raw WebGL canvasには含まれない |
123
+ | `renderer.canvas.captureStream()` | 表示される | raw WebGL streamには含まれない |
124
+
125
+ stage native size変更ではrootの`viewBox`と全surfaceを更新し、fullscreenとhigh-DPIのCSS scalingはrendererの`scale` overlay modeへ委譲します。stop、project reload、target/clone破棄、composition disposeではlistener、DOM、capability所有resourceを解放し、最後のBubbleが閉じた時点で`removeOverlay(root)`を呼びます。
126
+
127
+ 自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.8.1 named styleの行座標・角丸、許可属性、object URL解放を検証します。Web/Desktop/Packagerでのvisual parityとframe time/memoryのmanual gateは[SVG overlay release note](docs/release-notes-0.8.0.md)に記録します。
128
+
129
+ ### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
130
+
131
+ セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
132
+
133
+ 仕様上の綴りは`CHARACTER`です(`charactor`ではありません)。`BLOCK`は、改行を含む複数行を一つの表示単位として扱う名前で、ここでいうblockはScratchのblockではありません。
134
+
135
+ ```mermaid
136
+ flowchart LR
137
+ source["全文: 私の/名前は/中野/です"] --> mode{"表示単位"}
138
+ mode -->|CHARACTER| c["私 → 私の → 私の/ → …"]
139
+ mode -->|WORD| w["私の → 私の/名前は → …"]
140
+ mode -->|LINE| l["1行ずつ追加"]
141
+ mode -->|BLOCK| b["複数行/段落をまとめて追加"]
142
+ delimiter["任意の区切り文字集合<br/>例: スラッシュ、空白、縦線"] -.-> w
143
+ visibility{"区切り文字の表示"} -->|visible| shown["区切り文字も描画"]
144
+ visibility -->|invisible| hidden["区切り文字を隠して描画"]
145
+ delimiter --> visibility
146
+ ```
147
+
148
+ ### WORDの区切り文字
149
+
150
+ 日本語の形態素解析は行いません。`WORD`は空白で区切る言語、または利用者が区切りを埋め込める言語を対象にします。例えば`私の/名前は/中野/です`を入力し、`/`をWORD delimiterにして不可視にすれば、`私の`→`名前は`→`中野`→`です`の順で表示できます。区切り文字を可視にすれば、スラッシュを演出として残せます。
151
+
152
+ 区切り文字は単一文字に限定せず、任意の文字集合として指定します。delimiter自体を表示単位に含めるか、取り除いてからText providerへ渡すかを選べるようにします。
153
+
154
+ ### DYNAMICとRESERVED
155
+
156
+ 逐次表示中の吹き出しサイズは、次の2方式を選べるようにします。
157
+
158
+ ```mermaid
159
+ sequenceDiagram
160
+ participant Host as Host
161
+ participant Bubble as Bubble surface
162
+ participant Text as Text provider
163
+ Host->>Text: 全文をmeasure
164
+ alt RESERVED
165
+ Text-->>Bubble: 最終幅・最終行数
166
+ Bubble->>Bubble: 最終サイズを先に確保
167
+ loop 表示単位ごと
168
+ Host->>Text: 可視範囲を更新
169
+ Text-->>Bubble: 文字だけ更新
170
+ end
171
+ else DYNAMIC
172
+ loop 表示単位ごと
173
+ Host->>Text: 可視範囲を更新
174
+ Text-->>Bubble: 現在の幅・行数
175
+ Bubble->>Bubble: 外形とplacementを再計算
176
+ end
177
+ end
178
+ ```
179
+
180
+ `RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。既定layoutは`DYNAMIC`です。`normalizeBubbleReveal`とComposition APIでは`intervalSeconds`の既定値は自動送りを無効にする`0`で、機能拡張ブロックのseconds欄は`0.05`から始まります。どちらのlayoutもBubble外形のanimationやportraitレイヤーとは独立しています。styleの`reveal`、`handle.revealNext()`、`handle.revealAll()`が分割・タイミングの接続点になり、正の`intervalSeconds`を指定すると自動送りを有効にできます。
181
+
182
+ 逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
183
+
184
+ ```text
185
+ finish [CHARACTER / WORD / LINE / BLOCK]
186
+ with condition [CONDITION]
187
+ or timeout after [TIMEOUT] seconds
188
+ ```
189
+
190
+ `CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または表示終了animationを開始します。Composition APIでは`handle.finish({ unit, condition, timeoutSeconds })`、手続き型拡張では`finish [UNIT] ...`ブロックを使います。このブロックにはRuntime Expressionが必要で、条件で使う変数を入力eventから更新する場合だけAsync Inputも必要です。
191
+
192
+ ### 音声と表示単位
193
+
194
+ `finish`は公開Composition APIの`handle.finish({ unit, condition, timeoutSeconds })`と、TurboWarpの`finish [UNIT] ...`ブロックで利用できます。これは逐次表示を最後まで進め、条件成立またはtimeoutで音声と待機状態を確定します。
195
+
196
+ Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
197
+
198
+ - 表示開始時のフルボイス
199
+ - `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
200
+ - Composition APIの`finish`条件成立時またはtimeout時の完了音
201
+
202
+ 表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声assetを再生する経路です。TurboWarpブロックはvoiceと表示単位ごとの効果音を公開し、`audio.finish`は現在Composition APIから設定します。音声がない場合でも、文字表示・portrait・Bubble外形は独立して利用できます。
203
+
204
+ ### パッケージ境界
205
+
206
+ | パッケージ | 責務 |
207
+ | ------------------------------------------ | ------------------------------------------------------------------------------ |
208
+ | `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
209
+ | Bubble core(`composition`) | `BubbleTextCapability`契約、吹き出しsurface、配置、逐次表示、animation |
210
+ | `@kubohiroya/turbowarp-svg-text` | 0.8.1のhost-neutralなplain/ruby layout、stock named-style handoff、文字幅計測 |
211
+ | `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
212
+ | `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
213
+ | `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
214
+ | アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
215
+
216
+ Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterはstandalone SVG Text 0.8.1があればnamed-style handoffを使い、なければ直接依存するlayout compositionをproviderとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Managerを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
217
+
218
+ ### 自動改行と禁則処理の基盤
219
+
220
+ Bubbleの任意`maxWidth`による自動改行では、`@cto.af/linebreak`を利用してUnicode UAX #14準拠の改行可能位置を求めます。依存は`LineBreakProvider` interfaceの内側へ閉じ込め、実際のフォントで測った幅から、上限内に収まる最も後ろの候補をBubble側で選びます。
221
+
222
+ `UnicodeLineBreakProvider`はUAX #14の候補を`Intl.Segmenter`の書記素境界で絞るため、句読点や小書き仮名の禁則に加え、結合文字や絵文字の途中分割も避けます。明示改行は維持し、URLなど分割可能な候補がない文字列だけを書記素境界でfallback分割します。
223
+
224
+ ```ts
225
+ import { wrapText } from "@kubohiroya/turbowarp-bubble/composition";
226
+
227
+ const layout = wrapText({
228
+ text: "これは長いセリフです。",
229
+ maxWidth: 320,
230
+ measureText: (text) => textRenderer.measure(text),
231
+ });
232
+ ```
233
+
234
+ Composition APIのBubble styleへ`maxWidth`と任意の`textLocale`を渡すと、Text capabilityの`measureText`を使ってこの`wrapText`基盤が実際の表示文字列を自動改行します。SVG Textまたはhost側のText capabilityが`measureText`を提供しない場合、`maxWidth`を使った表示は明示的なcapabilityエラーになります。
235
+
236
+ ![maxWidthの違いによる自動改行と、日本語禁則処理の例](docs/assets/width-linebreak-guide.svg)
237
+
238
+ 図の各行はproductionの`wrapText`を直接呼んだ結果です。図版専用の手作業改行は使っていません。
239
+
240
+ ### Bubble visual styleの形状
241
+
242
+ 形状候補は`NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`です。
243
+
244
+ ![10種類のBubble visual styleを同じSVG rendererで比較する図](docs/assets/bubble-style-gallery.svg)
245
+
246
+ この図はBubble側の共有`renderBubbleSvg`から生成しています。三角形tailを持つ形状は、tail基部の2点を実際の本体border上から求め、[platener/jsclipper](https://github.com/platener/jsclipper)で本体polygonとtail三角形の和集合を作り、単一の外周pathだけを描画します。`THINKING`/`DREAMING`の丸trailは独立形状のままです。
247
+
248
+ standalone機能拡張では、`set bubble visual style`ブロックで形状を選択できます。どちらの描画backendも共有`renderBubbleSvg`を使い、既定overlayはcanonical SVGを許可済みDOM要素として再構築し、明示的な`scratch-render`はSVG skinを専用drawableへ適用します。いずれも本体を文字・表情より背面に置きます。Actor相対ではActorを向くtailを生成し、背景相対ではtailを付けません。`NO_BUBBLE`では本体を非表示にして文字・表情などだけを表示します。`NEGATIVE`はfill colorとborder colorで表現できるため独立styleにせず、orientationとsegmentsも公開入力にしません。
249
+
250
+ portraitは`left`/`right`/`top-left`/`top-right`/`bottom-left`/`bottom-right`へ配置し、portrait固有の`[x, y, zoom]`と角丸半径を指定できます。placementの既定値は`left`、変形は`[0, 0, 100]`、角丸半径は`0`です。zoomは0より大きく、角丸半径は0以上である必要があります。standalone機能拡張では`set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px ...`を使い、`none`でportrait全体を解除します。Composition APIでは次のようにstyleへ含めます。
251
+
252
+ ```ts
253
+ portrait: {
254
+ base: "HeroFace",
255
+ placement: "top-left",
256
+ offset: [-4, 6, 120],
257
+ cornerRadius: 12,
258
+ }
259
+ ```
260
+
261
+ 配布bundleに含まれる依存ライブラリのライセンスは、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)を参照してください。
262
+
263
+ ## 利用方法
264
+
265
+ ### インストール
266
+
267
+ ```sh
268
+ pnpm add @kubohiroya/turbowarp-bubble
269
+ ```
270
+
271
+ npmを使う場合は同じ依存を次のように追加します。
272
+
273
+ ```sh
274
+ npm install @kubohiroya/turbowarp-bubble
275
+ ```
276
+
277
+ 逐次表示の正規化と文字列分割だけが必要な利用側は、Bubble composition全体を含めずに小さな`reveal` entryをimportできます。
278
+
279
+ ```ts
280
+ import {
281
+ normalizeBubbleReveal,
282
+ splitBubbleText,
283
+ } from "@kubohiroya/turbowarp-bubble/reveal";
284
+
285
+ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
286
+ const chunks = splitBubbleText("A👩‍🚀B", reveal);
287
+ ```
288
+
289
+ SVG Text 0.8.1は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールは不要です。standalone SVG Text 0.8.1を先に読み込むことは任意ですが、読み込むとproject blockで定義したstyleを公開handoff経由で再利用します。Bubbleが宣言するoptional peer dependencyの範囲はAsset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`のままです。現在公開中の推奨版はAsset Manager 0.12.1、Async Input 0.4.0、Runtime Expression 0.4.0です。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身が利用するSVG Text dependencyは0.8.1に固定されます。
290
+
291
+ `bubbleRenderBackend: "scratch-render"`へrollbackした場合も、standalone SVG Text拡張が未ロードなら同じ0.8.1 dependencyからskin版providerを生成します。standalone SVG Text拡張が既にロードされているhostでは、互換性のためその既存providerを引き続き使用します。
292
+
293
+ 画像portrait、lip-sync、continue indicator、または音声アセットを使う場合はAsset Managerを追加します。`finish [UNIT] ...`ブロックにはRuntime Expressionが必要です。統合待機ブロック`wait with this bubble ...`にはAsync InputとRuntime Expressionの両方が必要です。
294
+
295
+ ```sh
296
+ pnpm add @kubohiroya/turbowarp-asset-manager \
297
+ @kubohiroya/turbowarp-async-input \
298
+ @kubohiroya/turbowarp-runtime-expression
299
+ ```
300
+
301
+ ```sh
302
+ npm install @kubohiroya/turbowarp-asset-manager \
303
+ @kubohiroya/turbowarp-async-input \
304
+ @kubohiroya/turbowarp-runtime-expression
305
+ ```
306
+
307
+ ### TurboWarp機能拡張
308
+
309
+ ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
310
+
311
+ Kamishibai DSL 4.0の統合bundleでは、**Bubble** member見出し直下のドキュメントボタンからこのマニュアルを開けます。統合paletteでもstyle、placement、portrait、reveal、audio、wait、animation、clone、cleanupの動作は同じで、member namespaceとBubble iconが由来の機能拡張を示します。
312
+
313
+ #### TurboWarpでの導入
314
+
315
+ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget APIへ接続する**unsandboxedカスタム拡張機能**です。TurboWarp Editorでは、次の順で読み込みます。
316
+
317
+ 1. 入力待ちの例を使う場合は、TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
318
+ 2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
319
+ 3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Manager 0.12.1を読み込みます。
320
+ 4. `finish [UNIT] ...`にはRuntime Expression 0.4.0、conditionを使う待機またはclose policyにはAsync Input 0.4.0とRuntime Expression 0.4.0を読み込みます。timeoutだけのclose policyにはどちらも不要です。
321
+ 5. 最後にBubble 0.10.0を読み込みます。SVG Text 0.8.1のlayout providerはBubble bundleに含まれます。
322
+
323
+ 文字だけの最小構成はBubbleです。Temporary Variables、Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。Bubbleを読み込むと、基本の`say [MESSAGE]`/`think [MESSAGE]`ブロックはstyle定義なしですぐ使えます。それぞれ組み込みBubble style `say`/`think`を選び、各styleが本体形状とtail/trail形状を不可分な1つの外観として持ちます。どちらも予約text profile `default`を使います。named custom styleが必要な場合だけ`define bubble style`と`show [MESSAGE] with bubble style [STYLE]`を使います。それ以外のnamed text styleや、外形・配置・media・reveal・motionの明示設定はcustom profileになります。
324
+
325
+ ```text
326
+ # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
327
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
328
+
329
+ # conditionを使う統合待機またはclose policyでAsync Inputを追加
330
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
331
+
332
+ # finishまたはconditionを使う待機/close policyでRuntime Expressionを追加
333
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
334
+
335
+ # Bubble(必ず最後)
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js
337
+ ```
338
+
339
+ TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発用URLをunsandboxedとして読み込むには、server originを正確に`http://localhost:8000/`とする必要があります。`127.0.0.1`、`0.0.0.0`、ほかのportにはこの例外が適用されません。リポジトリrootで`python3 -m http.server 8000`を実行し、`http://localhost:8000/dist/turbowarp-bubble.js`を読み込んでください。別の方法として、カスタム拡張機能のfileまたはtext入力を選び、**サンドボックスなしで実行する**を有効にできます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。host制約の詳細は[TurboWarpのunsandboxed拡張機能ドキュメント](https://docs.turbowarp.org/development/extensions/unsandboxed)を参照してください。
340
+
341
+ #### Scratchとの互換性
342
+
343
+ Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカスタム拡張機能として直接利用することはできません。Scratch公式にはTurboWarpのunsandboxed拡張機能、renderer内部API、target drawable APIがないためです。Scratch向けの.sb3プロジェクトへこのREADMEのURLを追加しても、Bubbleのブロックは登録されません。
344
+
345
+ 利用環境ごとの位置付けは次のとおりです。
346
+
347
+ | 環境 | 利用方法 | 対応 |
348
+ | ------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
349
+ | TurboWarp Editor | `dist/turbowarp-bubble.js`をunsandboxedカスタム拡張機能として読み込む | 対応 |
350
+ | TurboWarp Packager/互換runtime | unsandboxedカスタム拡張機能とrenderer APIが利用できる構成で読み込む | 対応(環境ごとに確認が必要) |
351
+ | Scratch公式エディター | 公式拡張機能またはサンドボックス拡張機能として読み込む | 非対応 |
352
+ | 独自Webアプリ/ホスト | npmのcomposition APIまたはTurboWarp adapterをJavaScriptから利用する | 対応 |
353
+
354
+ Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
355
+
356
+ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。既定backendではSVG本体、文字、表情ベース、目パチ、口パク、次へアイコンを共有overlay DOM内のレイヤーとして生成するため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
357
+
358
+ #### 提供ブロック
359
+
360
+ | ブロック | 動作 |
361
+ | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
362
+ | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または置換する |
363
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | 名前付きの終了条件を定義または置換する |
364
+ | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
365
+ | `set portrait base [ASSET] for bubble style [STYLE]` | portraitベースを設定する。空値でportrait全体を解除する |
366
+ | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | portraitの配置、局所変形、角丸を設定する |
367
+ | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
368
+ | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | 不可分なSVG本体+tail/trailの組を10種類から設定する |
369
+ | `set bubble tail length [LENGTH] for bubble style [STYLE]` | 本体borderからtail先端までの基準長を設定する |
370
+ | `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体offsetとBubble全体のscaleを設定する |
371
+ | `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチframeと間隔を設定する |
372
+ | `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パクframeと間隔を設定する |
373
+ | `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | `awaiting-continue`中のanimationを設定する |
374
+ | `set bubble reveal unit [UNIT] every [SECONDS] seconds layout [LAYOUT] for bubble style [STYLE]` | CHARACTER/WORD/LINE/BLOCKの逐次表示を設定する |
375
+ | `set bubble word delimiters [DELIMITERS] show [SHOW] for bubble style [STYLE]` | WORDの区切り文字集合と表示可否を設定する |
376
+ | `set bubble reveal sound [ASSET] for bubble style [STYLE]` | 表示単位ごとの効果音を設定する |
377
+ | `set bubble voice [ASSET] for bubble style [STYLE]` | 表示開始時のフルボイスを設定する |
378
+ | `finish [UNIT] with condition [CONDITION] or timeout after [TIMEOUT] seconds` | 未表示単位を進めて条件成立またはtimeoutを待つ |
379
+ | `set bubble show animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示開始animationを設定する |
380
+ | `set bubble hide animation [MOTION] for [SECONDS] seconds for bubble style [STYLE]` | 表示終了animationを設定する |
381
+ | `animate this bubble [MOTION]` | Bubble全体のanimationを再生する |
382
+ | `shake this bubble direction [DIRECTION] count [COUNT] ease [EASE]` | Bubble surface全体を揺らす |
383
+ | `explode this bubble relative scale [SCALE] count [COUNT] ease [EASE]` | Bubble全体へ相対scaleのcycleを適用する |
384
+ | `animate bubble shape to [VISUAL_STYLE] speed [SPEED] for [SECONDS] seconds` | Bubble外形を遷移させる |
385
+ | `say [MESSAGE]` | 組み込み`say` styleのspeech本体+tailを表示する |
386
+ | `think [MESSAGE]` | 組み込み`think` styleのthought本体+round trailを表示する |
387
+ | `show [MESSAGE] with bubble style [STYLE]` | 選択styleが持つ本体+tail/trailの組を表示する |
388
+ | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を選択する |
389
+ | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立または任意timeoutまで待つ |
390
+ | `wait and close this bubble using close policy [POLICY]` | policyをsnapshotし、成立を待ってBubbleを閉じる |
391
+ | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
392
+ | `Bubble version` | 実装versionを返す |
393
+
394
+ Bubble close policyは制御フローの設定であり、見た目を表すBubble styleではありません。`condition`は時間制限なしで条件を待ち、`timeout`は正の秒数後に閉じ、`condition-or-timeout`は先に成立した方で閉じます。conditionは空にできず、有効なtimeoutは0より大きい値にします。
395
+
396
+ ```text
397
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
398
+ say [3秒後に閉じます。]
399
+ wait and close this bubble using close policy [three-seconds]
400
+
401
+ define bubble close policy [advance] trigger [condition] condition [input == "pressed"] timeout [0] seconds
402
+ say [キーを押すかspriteをタッチしてください。]
403
+ wait and close this bubble using close policy [advance]
404
+ ```
405
+
406
+ 適用ブロックは開始時に名前付き定義をsnapshotします。待機中に同名policyを置換しても、その変更は次回の適用から有効です。timeoutだけのpolicyは現在のanimation modeを維持し、入力用拡張を必要としません。conditionを含むpolicyは`awaiting-continue`へ移り、既存の内蔵待機と同じくAsync InputとRuntime Expressionを使います。成立後は設定済みhide animationを実行してBubbleを解放します。Bubbleの置換、targetやprojectの停止、runtime破棄では待機中policyをcancelし、置換後のBubbleを閉じません。
407
+
408
+ `ASSETS`はAsset Managerへ登録済みの名前をカンマ区切りで指定します。前後の空白は除去され、名前自体にカンマは使用できません。目パチと口パクは1フレーム以上、continue indicatorは2フレーム以上が必要で、空リストにすると設定を解除します。frame間隔は0より大きい有限値です。逐次表示間隔、animation時間、従来のwait timeoutには0も指定でき、逐次表示間隔の0は自動送りを、従来のtimeoutの0は時間制限を無効にします。close policyで明示的に選ぶtimeoutは0より大きい値にします。
409
+
410
+ Bubbleには2つの組み込みBubble styleがあります。`say`はspeech本体とspeech tail、`think`はthought本体とround trailを持ち、本体とtail/trailは個別指定ではなく1つのvisual styleとして選びます。対応する短いブロックが各styleを自動選択するため、style定義ブロックもstyle入力も不要です。どちらも予約text profile `default`を使い、14px Helvetica、line height 16px、最大行幅170px、最小文字領域幅50px、padding 10px、corner radius 16px、白い本体、Scratch標準の文字色・border色で描画します。SVGの4px strokeを先に描き、その内側半分を白いfillで覆うことで、TurboWarp標準と同じ細い見かけの輪郭にします。Actor右側を優先し、右に収まらず左に収まる場合だけ反転します。Actor boundsへの追従、Stage上端・左右端のfence、数値block入力の整形、330文字上限、空文字でのcloseも標準`say`/`think`に揃えます。
411
+
412
+ ##### TurboWarp標準との比較
413
+
414
+ 次の画像は、同じTurboWarp Editor projectで英語UIを使い、`Cat` spriteを`x=-80`、`y=0`、サイズ`80%`、Stageを白背景、入力を`Hello!`/`Hmm...`に揃えて撮影した実画面です。左列はTurboWarp標準の見た目ブロック、右列は対応する組み込み`say`/`think` styleを使うBubbleの基本ブロックです。定義ブロックもsetterも使っていません。
415
+
416
+ ![TurboWarp標準のsay・think吹き出しとBubble基本profileを同じStageで比較した実画面](docs/assets/turbowarp-say-think-stage-comparison.png)
417
+
418
+ Stage比較では、右側配置、内容に追従する本体、Actor側へ向くspeech tail/thought trailを同じ条件で確認できます。Bubbleは独立したSVG surfaceを描画するため、この画像はTurboWarp標準吹き出しの画像を転用したものではなく、Bubble rendererの実際の出力です。
419
+
420
+ ![TurboWarp標準のsay・thinkブロックと、設定不要のBubble基本say・thinkブロックおよび組み込みdefault profile値を比較したスクリーンショット](docs/assets/turbowarp-say-think-block-comparison.png)
421
+
422
+ ブロック比較は設定不要の基本経路と、custom style用の統合表示ブロックを示します。短い`say`/`think`は対応する組み込みstyleを自動選択し、図中のcalloutで不可分な本体+tail/trailの組、両styleが使う予約text profile `default`、共通metricを示します。named custom styleには`show [MESSAGE] with bubble style [STYLE]`を使うため、表示時に競合し得る別のkindを指定しません。旧styled say/think opcodeは保存済みproject互換用の非表示定義として残します。
423
+
424
+ style設定ブロックを1つでも実行するか、`default`以外のtext style名を指定すると、従来のcustom profileになります。custom profileでvisual styleを省略した場合は`NORMAL`、placementを省略した場合は`up-right`です。visual style、placement、distance、tail length、offset、portrait、continue indicator、reveal、audio、motionの明示設定は従来どおり動作します。既定の`svg-overlay` backendでは、選択した本体を共有overlay root内のSVG DOM layerとして描画します。明示的な`scratch-render`ではSVG skinとrenderer drawableを使います。Bubbleのclose/置換、対象停止、runtime破棄では、選択したbackendが所有するresourceを解放します。
425
+
426
+ #### Placement
427
+
428
+ `PLACEMENT`はcustom profileの配置を設定し、Actor相対と背景相対の二系統があります。placementなどのstyle optionを明示したcustom profileでは、省略時は`up-right`です。未変更の基本profileは、Scratch標準と同じ右側優先・収まりに応じた左反転を使います。
429
+
430
+ - Actor相対:16の正規方向名、そのcompass alias、またはScratch方向と同じ0〜360度。`0`は上、`90`は右、`180`は下、`270`は左で、`360`は`0`へ正規化します。任意角度は16方向へ丸めません。
431
+ - 背景相対:`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`。Stage安全領域の上部、中央、下部へ水平中央揃えで置き、Actor位置・bounds・可視性には依存しません。
432
+
433
+ Actor相対の正規方向名は次の16個です。別名は大文字小文字を区別せず、正規名へ変換されます。
434
+
435
+ | 正規名 | compass alias | 正規名 | compass alias |
436
+ | ------------------ | ----------------- | ---------------- | ----------------- |
437
+ | `up` | `north` | `down` | `south` |
438
+ | `up-up-right` | `north-northeast` | `down-down-left` | `south-southwest` |
439
+ | `up-right` | `northeast` | `down-left` | `southwest` |
440
+ | `right-up-right` | `east-northeast` | `left-down-left` | `west-southwest` |
441
+ | `right` | `east` | `left` | `west` |
442
+ | `right-down-right` | `east-southeast` | `left-up-left` | `west-northwest` |
443
+ | `down-right` | `southeast` | `up-left` | `northwest` |
444
+ | `down-down-right` | `south-southeast` | `up-up-left` | `north-northwest` |
445
+
446
+ ![Actor相対の16方向・角度指定と、背景相対の3配置を比較する図](docs/assets/placement-guide.svg)
447
+
448
+ 図中の16方向は、それぞれActor、実際のBubble外形、tail、文字を含む表示例です。本体とtailはJSClipperのunionによる単一pathなので、接合部に内部border線はありません。背景相対3図はStage外枠、安全領域、外形寸法、水平中央線、基準辺/中心を示します。図とTurboWarp Editorで描画する本体は、どちらも共有`renderBubbleSvg`から生成します。
449
+
450
+ ![Actor相対のdistance、tail length、offset、scaleを比較する図](docs/assets/actor-transform-guide.svg)
451
+
452
+ Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box。rendererの`getBoundsForBubble()`が返す上下左右)からtail先端までで、既定値は`12`です。`tail length`は通常位置における本体borderからtail先端までで、既定値は`18`です。
453
+
454
+ `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では無視します。
455
+
456
+ #### Portraitとblink / lip-sync
457
+
458
+ portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
459
+
460
+ ```mermaid
461
+ flowchart TB
462
+ bubble[Bubble surface]
463
+ body[Bubble body / text]
464
+ base[portraitBase\n顔・髪・輪郭]
465
+ blink[portraitBlink\n目パチ差分]
466
+ lipsync[portraitLipSync\n口パク差分]
467
+ continue[continueIndicator\n次へアイコン]
468
+ bubble --> body
469
+ bubble --> base
470
+ base --> blink
471
+ base --> lipsync
472
+ bubble --> continue
473
+ ```
474
+
475
+ | レイヤー | 表示中の動作 | 設定ブロック/API |
476
+ | ------------------- | ------------------------------------------------------ | ------------------------------------------- |
477
+ | `portraitBase` | 常時表示するベース画像 | `set portrait base` / `portrait.base` |
478
+ | `portraitBlink` | `talking`、`awaiting-continue`、`idle`のすべてでループ | `set blink frames` / `portrait.blink` |
479
+ | `portraitLipSync` | `talking`中だけループし、待機時は停止・非表示 | `set lip-sync frames` / `portrait.lipSync` |
480
+ | `continueIndicator` | `awaiting-continue`中だけループ | `set continue frames` / `continueIndicator` |
481
+
482
+ 目パチと口パクは1枚の静止画でも利用できます。口パクのキーワードは、話す行為全体ではなく口元の表情差分を指定する意味で`lip-sync`に統一しています。`continue`は、入力待ちを表すアイコンのanimationであり、JavaScriptの`continue`文を実行する機能ではありません。
483
+
484
+ ![portrait base、blink、lip-sync、continue indicatorを別レイヤーとして重ねる概念図](docs/assets/animation-mode-guide.svg)
485
+
486
+ #### Bubble animation
487
+
488
+ Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
489
+
490
+ ```mermaid
491
+ flowchart LR
492
+ start[表示開始] --> in[表示開始animation\nfadeIn / floatIn / zoomIn / riseUp]
493
+ in --> visible[表示中]
494
+ visible --> shake[shake\n方向・回数・ease]
495
+ visible --> explode[explode\n相対サイズ・回数・ease]
496
+ visible --> shape[animateBubbleShape\n速度・時間]
497
+ visible --> waiting[awaiting-continue]
498
+ waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
499
+ out --> released[close・resource解放]
500
+ ```
501
+
502
+ ##### 表示開始と表示終了
503
+
504
+ PowerPointの用語を参考にしつつ、Bubbleの仕様名は「表示開始animation」「表示終了animation」とします。表示開始には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。表示開始・表示終了animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、表示終了時には現在の外形を基準に終点を計算します。
505
+
506
+ Bubbleを消すときは`close this bubble`を実行します。設定済みの表示終了animationを適用してから、表示と所有resourceを解放します。表示終了animationのsetterは終了時の演出を設定するだけで、それ自体は何も非表示にしません。組み込み`say`/`think`はTurboWarp互換のため空文字でもcloseします。現在の表示を破棄してhidden stateを保持しないので、別の`hide`ブロックは設けません。
507
+
508
+ ##### 表示中の変形
509
+
510
+ - `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
511
+ - `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
512
+ - `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
513
+
514
+ TurboWarp adapterは最大16ms単位のscheduler tickで各animationを進め、`ease`を各フレームの進行率へ適用します。既定のSVG overlayは共有surface groupのopacityとtransformを変更し、明示的な`scratch-render`は同じmotionをrenderer effect、位置、scaleへ変換します。`shake`は指定回数の往復を行い、`explode`はText・portrait・本体をまとめて拡大して元へ戻します。`durationSeconds`を省略した`shake`/`explode`には、回数に応じた既定時間を使います。
515
+
516
+ `animateBubbleShape`は、`renderBubbleSvg`が生成する現在形状と指定形状を各フレームでcross-fadeします。overlay backendは許可済みの本体要素だけを再構築し、`scratch-render`は本体skinを更新します。どちらもTextとportraitは再生成しません。`speed`は指定時間内の形状遷移速度倍率です。
517
+
518
+ animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとbackend所有の描画resourceを先に解放します。`shake`には`ease`を指定でき、`explode`には`relativeScale`、`count`、`ease`、`animateBubbleShape`には`speed`と`durationSeconds`を指定できます。
519
+
520
+ #### Animation mode
521
+
522
+ | mode | 目パチ | 口パク | continue frames |
523
+ | ------------------- | ------ | ------------ | --------------- |
524
+ | `talking` | 実行 | 実行 | 非表示 |
525
+ | `awaiting-continue` | 実行 | 停止・非表示 | ループ実行 |
526
+ | `idle` | 実行 | 停止・非表示 | 停止・非表示 |
527
+
528
+ `say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
529
+
530
+ #### ブロック構成例
531
+
532
+ ```text
533
+ define bubble style [hero-dialogue] using text style [default]
534
+ set bubble placement [up-right] for bubble style [hero-dialogue]
535
+ set bubble distance [12] for bubble style [hero-dialogue]
536
+ set bubble visual style [NORMAL] for bubble style [hero-dialogue]
537
+ set bubble tail length [18] for bubble style [hero-dialogue]
538
+ set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
539
+ set portrait base [HeroFace] for bubble style [hero-dialogue]
540
+ set portrait [top-left] offset x [-4] y [6] zoom [120] % corner radius [12] px for bubble style [hero-dialogue]
541
+ set blink frames [HeroEyesOpen,HeroEyesClosed] every [0.4] seconds for bubble style [hero-dialogue]
542
+ set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
543
+ set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
544
+ set bubble reveal unit [WORD] every [0.05] seconds layout [RESERVED] for bubble style [hero-dialogue]
545
+ set bubble word delimiters [ /] show [false] for bubble style [hero-dialogue]
546
+ set bubble reveal sound [Typewriter] for bubble style [hero-dialogue]
547
+ set bubble voice [HeroVoice] for bubble style [hero-dialogue]
548
+ set bubble show animation [fadeIn] for [0.2] seconds for bubble style [hero-dialogue]
549
+ set bubble hide animation [fadeOut] for [0.2] seconds for bubble style [hero-dialogue]
550
+ set runtime variable [input] to []
551
+ listen for key [Space] set runtime var [input] to [pressed]
552
+ listen for touch on this sprite set runtime var [input] to [pressed]
553
+ show [海へ/出発!] with bubble style [hero-dialogue]
554
+ finish [WORD] with condition [input == "pressed"] or timeout after [10] seconds
555
+ shake this bubble direction [90] count [2] ease [easeInOut]
556
+ close this bubble
557
+ ```
558
+
559
+ プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、overlay DOM、画像leaseを自動解放します。明示的に`scratch-render`を選んだ場合は、従来どおり所有するSVG skinとdrawableも解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
560
+
561
+ ### Composition API
562
+
563
+ TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではstandalone SVG Text 0.8.1があればnamed-style handoffを使い、なければ内包layout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
564
+
565
+ ```ts
566
+ import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
567
+
568
+ const bubbles = createTurboWarpBubbleComposition(runtime);
569
+ ```
570
+
571
+ 描画surfaceをhost側で実装する場合は、以下の低レベルComposition APIを利用します。
572
+
573
+ ```ts
574
+ import {
575
+ createBubbleComposition,
576
+ type BubbleImageCapability,
577
+ type BubbleSurfaceFactory,
578
+ type BubbleTextCapability,
579
+ } from "@kubohiroya/turbowarp-bubble/composition";
580
+
581
+ // These are host-owned capabilities. They may be backed by Asset Manager,
582
+ // another asset service, or local application code.
583
+ declare const imageResolver: BubbleImageCapability;
584
+ declare const textCapability: BubbleTextCapability;
585
+ declare const bubbleSurfaceHost: BubbleSurfaceFactory;
586
+
587
+ const bubbles = createBubbleComposition({
588
+ imageResolver,
589
+ textCapability,
590
+ createSurface: bubbleSurfaceHost,
591
+ });
592
+ ```
593
+
594
+ `declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleTextCapability`(文字layout/描画・計測・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。`@kubohiroya/turbowarp-svg-text/composition`を使う場合は、skinを使うhostなら`createSvgTextCompositionCapability(createSvgTextComposition({ runtime }))`、SVG overlayなら`createSvgTextOverlayTextCapability(createSvgTextLayoutComposition())`で変換します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
595
+
596
+ テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、`audio.voice`、`audio.reveal`、`audio.finish`によるフルボイス、表示単位ごとの効果音、完了音を登録・再生するメディア経路です。TurboWarp adapterはstock Asset Managerへ遅延接続し、低レベルComposition APIのhostは独自の`audio` capabilityを注入できます。
597
+
598
+ `createSurface`が返すsurfaceは、次のtargetを持ちます。
599
+
600
+ surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
601
+
602
+ - `text`: `textCapability`が文字layoutを適用するtarget
603
+ - `portraitBase`: キャラクター表情のベース画像target
604
+ - `portraitBlink`: 目パチ差分target
605
+ - `portraitLipSync`: 口パク差分target
606
+ - `continueIndicator`: 「次へ」アイコンtarget
607
+
608
+ 画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
609
+
610
+ #### Styleと表示
611
+
612
+ ```ts
613
+ bubbles.defineStyle({
614
+ name: "hero-dialogue",
615
+ textStyle: "dialogue-text",
616
+ placement: "north-northeast",
617
+ distance: 12,
618
+ visualStyle: "NORMAL",
619
+ tailLength: 18,
620
+ offset: [10, -10, 120],
621
+ portrait: {
622
+ base: "HeroFace",
623
+ blink: {
624
+ frames: ["HeroEyesOpen", "HeroEyesClosed"],
625
+ frameIntervalSeconds: 0.4,
626
+ },
627
+ lipSync: {
628
+ frames: ["HeroMouthClosed", "HeroMouthOpen"],
629
+ frameIntervalSeconds: 0.1,
630
+ },
631
+ },
632
+ continueIndicator: {
633
+ frames: ["Next1", "Next2"],
634
+ frameIntervalSeconds: 0.2,
635
+ },
636
+ reveal: {
637
+ unit: "CHARACTER",
638
+ layout: "RESERVED",
639
+ intervalSeconds: 0.05,
640
+ sound: "Typewriter",
641
+ },
642
+ audio: {
643
+ voice: "HeroVoice",
644
+ reveal: "Typewriter",
645
+ finish: "Ready",
646
+ },
647
+ showAnimation: { name: "fadeIn", durationSeconds: 0.2 },
648
+ hideAnimation: { name: "fadeOut", durationSeconds: 0.2 },
649
+ });
650
+
651
+ bubbles.defineStyle({
652
+ name: "narration",
653
+ textStyle: "dialogue-text",
654
+ placement: "FOOTER_LIKE",
655
+ maxWidth: 320,
656
+ textLocale: "ja",
657
+ });
658
+
659
+ const bubble = await bubbles.show({
660
+ actor: heroTarget,
661
+ actorKey: "Hero",
662
+ kind: "say",
663
+ text: "海へ出発!",
664
+ styleName: "hero-dialogue",
665
+ });
666
+ ```
667
+
668
+ `show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-continue`へ変更します。
669
+
670
+ ```ts
671
+ await bubble.setAnimationMode("awaiting-continue");
672
+ // 口パクを停止して非表示にし、「次へ」アイコンをループ表示します。
673
+
674
+ await bubble.setAnimationMode("idle");
675
+ // 吹き出しを残したまま、口パクと「次へ」アイコンを停止します。
676
+
677
+ await bubble.revealNext();
678
+ await bubble.revealAll();
679
+ await bubble.animate({
680
+ name: "shake",
681
+ direction: 90,
682
+ count: 2,
683
+ ease: "easeInOut",
684
+ });
685
+ await bubble.finish({
686
+ unit: "CHARACTER",
687
+ condition: () => inputState === "pressed",
688
+ timeoutSeconds: 10,
689
+ });
690
+
691
+ await bubble.close();
692
+ ```
693
+
694
+ 返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、text capability target、surfaceを解放します。composition間で状態は共有しません。
695
+
696
+ ## ライセンスとソースコード
697
+
698
+ このパッケージの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から参照できます。
699
+
700
+ 配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
701
+
702
+ ## 開発
703
+
704
+ ```sh
705
+ pnpm install
706
+ pnpm check
707
+ ```
708
+
709
+ `pnpm check`は型検査、lint、format、単体テスト、配布物検査、外部consumer型検査、npm pack dry-runを実行します。