@kubohiroya/turbowarp-bubble 0.2.0 → 0.3.1
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 +171 -89
- package/dist/composition.js +1005 -697
- package/dist/extension-manifest.json +224 -0
- package/dist/turbowarp-adapter.js +1333 -903
- package/dist/turbowarp-bubble.js +1158 -30
- package/dist/types/bubble-svg.d.ts +10 -0
- package/dist/types/composition.d.ts +47 -1
- package/dist/types/reveal.d.ts +26 -0
- package/dist/types/turbowarp-adapter.d.ts +2 -0
- package/docs/assets/animation-mode-guide.svg +3 -12
- package/docs/assets/bubble-lifecycle.gif +0 -0
- package/docs/block-manual.ja.md +71 -30
- package/docs/block-manual.md +71 -30
- package/docs/index.html +75 -11
- package/docs/ja/index.html +75 -11
- package/package.json +30 -26
package/README.md
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
# TurboWarp Bubble
|
|
2
2
|
|
|
3
|
-
`@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition API
|
|
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[
|
|
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
|
-
| 領域
|
|
27
|
-
|
|
|
28
|
-
| 文字描画・改行
|
|
29
|
-
| 逐次表示
|
|
30
|
-
| portrait
|
|
31
|
-
| Bubble外形
|
|
32
|
-
| 表示mode
|
|
33
|
-
|
|
|
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
|
-
##
|
|
44
|
+
## 概念と表示仕様
|
|
36
45
|
|
|
37
|
-
|
|
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
|
-
|
|
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
|
-
|
|
63
|
+
extension --> core
|
|
64
|
+
extension -.optional.-> input
|
|
52
65
|
```
|
|
53
66
|
|
|
54
|
-
`@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portrait
|
|
67
|
+
`@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationは担当しません。画像解決、音声再生、入力、条件評価はCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyとして対応機能を使う場合だけ接続します。
|
|
55
68
|
|
|
56
|
-
|
|
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[
|
|
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
|
|
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
|
|
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` |
|
|
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
|
|
138
|
-
| アプリ/host |
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
193
|
+
### インストール
|
|
179
194
|
|
|
180
|
-
|
|
195
|
+
```sh
|
|
196
|
+
pnpm add @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
|
|
197
|
+
```
|
|
181
198
|
|
|
182
|
-
|
|
199
|
+
npmを使う場合は同じ依存を次のように追加します。
|
|
183
200
|
|
|
184
201
|
```sh
|
|
185
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
206
|
-
https://unpkg.com/@kubohiroya/turbowarp-svg-text/dist/svg-text.js
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
https://unpkg.com/@kubohiroya/turbowarp-
|
|
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.1/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
|
-
|
|
297
|
+
#### Placement
|
|
240
298
|
|
|
241
299
|
`PLACEMENT`はActor相対と背景相対の二系統です。省略時は`up-right`です。
|
|
242
300
|
|
|
@@ -258,7 +316,7 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
|
|
|
258
316
|
|
|
259
317
|

|
|
260
318
|
|
|
261
|
-
図中の16方向は、それぞれActor、実際のBubble外形、tail
|
|
319
|
+
図中の16方向は、それぞれActor、実際のBubble外形、tail、文字を含む表示例です。本体とtailはJSClipperのunionによる単一pathなので、接合部に内部border線はありません。背景相対3図はStage外枠、安全領域、外形寸法、水平中央線、基準辺/中心を示します。図とTurboWarp Editorの本体drawableは、どちらも共有`renderBubbleSvg`から生成します。
|
|
262
320
|
|
|
263
321
|

|
|
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
|
-
|
|
327
|
+
#### Portraitとblink / lip-sync
|
|
270
328
|
|
|
271
329
|
portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
|
|
272
330
|
|
|
@@ -296,37 +354,39 @@ flowchart TB
|
|
|
296
354
|
|
|
297
355
|

|
|
298
356
|
|
|
299
|
-
|
|
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[
|
|
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[
|
|
369
|
+
waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
|
|
312
370
|
out --> released[close・resource解放]
|
|
313
371
|
```
|
|
314
372
|
|
|
315
|
-
|
|
373
|
+
##### 表示開始と表示終了
|
|
316
374
|
|
|
317
|
-
PowerPoint
|
|
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
|
|
381
|
+
- `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
|
|
324
382
|
|
|
325
|
-
animation
|
|
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
|
-
|
|
385
|
+
`animateBubbleShape`は、現在形状と指定形状を各フレームでcross-fadeするSVG body skinへ更新します。Textとportraitは再生成せず、外形だけを連続的に切り替えます。`speed`は指定時間内の形状遷移速度倍率です。
|
|
328
386
|
|
|
329
|
-
|
|
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
|
-
|
|
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 {
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
556
|
+
## ライセンスとソースコード
|
|
475
557
|
|
|
476
|
-
|
|
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
|
-
|
|
560
|
+
配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
|
|
479
561
|
|
|
480
562
|
## 開発
|
|
481
563
|
|