@kubohiroya/turbowarp-bubble 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +355 -79
- package/dist/composition.js +972 -597
- package/dist/extension-manifest.json +240 -16
- package/dist/turbowarp-adapter.js +1728 -626
- package/dist/turbowarp-bubble.js +2811 -233
- package/dist/types/bubble-svg.d.ts +10 -0
- package/dist/types/composition.d.ts +96 -18
- package/dist/types/reveal.d.ts +26 -0
- package/dist/types/turbowarp-adapter.d.ts +12 -2
- package/docs/assets/animation-mode-guide.svg +5 -14
- package/docs/assets/block-quick-start.svg +8 -8
- package/docs/assets/bubble-lifecycle.gif +0 -0
- package/docs/block-manual.ja.md +88 -47
- package/docs/block-manual.md +95 -54
- package/docs/index.html +103 -39
- package/docs/ja/index.html +95 -31
- package/package.json +20 -7
package/README.md
CHANGED
|
@@ -1,21 +1,160 @@
|
|
|
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との互換性)に記載しています。
|
|
13
|
+
|
|
14
|
+
## 機能の全体像
|
|
15
|
+
|
|
16
|
+
Bubbleは、文字を描くText provider、吹き出しの外形と配置を管理するBubble layer、画像・音声を解決する任意のAsset capabilityを組み合わせます。これにより、TurboWarpの機能拡張としても、アプリのhostから呼び出すcompositionとしても同じ表示モデルを利用できます。
|
|
17
|
+
|
|
18
|
+
```mermaid
|
|
19
|
+
flowchart LR
|
|
20
|
+
input[セリフ入力] --> reveal[表示単位の選択]
|
|
21
|
+
reveal --> text[CHARACTER / WORD / LINE / BLOCK]
|
|
22
|
+
text --> layout[改行・サイズ計算]
|
|
23
|
+
layout --> body[Bubble外形・tail・placement]
|
|
24
|
+
text --> voice[フルボイス/単位ごとの効果音]
|
|
25
|
+
body --> portrait[portraitレイヤー]
|
|
26
|
+
portrait --> blink[blink]
|
|
27
|
+
portrait --> lipsync[lip-sync]
|
|
28
|
+
body --> motion[表示開始・表示中・表示終了animation]
|
|
29
|
+
body --> wait[continue待機]
|
|
30
|
+
wait --> close[終了・resource解放]
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
このREADMEでは、現在公開している機能と、3層構成で接続する表示仕様を同じ用語で説明します。公開APIにまだ現れていない仕様は「実装状況」欄で明示しています。
|
|
34
|
+
|
|
35
|
+
| 領域 | このREADMEで説明する内容 | 現在の公開API |
|
|
36
|
+
| ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|
|
37
|
+
| 文字描画・改行 | 名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(SVG Text capability) |
|
|
38
|
+
| 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | 実装済み(`revealNext`/`revealAll`/`finish`、対応ブロック) |
|
|
39
|
+
| portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | 実装済み(Asset Manager capability) |
|
|
40
|
+
| Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | 実装済み |
|
|
41
|
+
| 表示mode | `talking`/`awaiting-continue`/`idle` | 実装済み |
|
|
42
|
+
| 表示開始・表示中・表示終了animation | `fadeIn`、`floatIn`、`shake`、`animateBubbleShape`等 | 実装済み(`handle.animate`、style設定、対応ブロック) |
|
|
43
|
+
|
|
44
|
+
## 概念と表示仕様
|
|
45
|
+
|
|
46
|
+
### 3層構成と責務
|
|
47
|
+
|
|
48
|
+
依存の向きは、純粋なBubble compositionを中心に、TurboWarp adapterと各providerを外側へ置く構成です。矢印は「利用する側」から「利用される側」へ向けています。
|
|
49
|
+
|
|
50
|
+
```mermaid
|
|
51
|
+
flowchart TB
|
|
52
|
+
core[Bubble composition\n外形・配置・ライフサイクル・animation state]
|
|
53
|
+
adapter[TurboWarp adapter\nrenderer / runtime / targetへの接続]
|
|
54
|
+
text[SVG Text provider\n文字skin・計測・named style]
|
|
55
|
+
image[Image capability\nportrait・blink・lip-sync・continue画像]
|
|
56
|
+
audio[Audio capability\nvoice・表示単位ごとの効果音]
|
|
57
|
+
input[Async Input + Runtime Expression\n入力と待機条件]
|
|
58
|
+
extension[TurboWarp extension\nblocks / Scratch target]
|
|
59
|
+
adapter --> core
|
|
60
|
+
adapter --> text
|
|
61
|
+
core -.任意Capability.-> image
|
|
62
|
+
core -.任意Capability.-> audio
|
|
63
|
+
extension --> core
|
|
64
|
+
extension -.optional.-> input
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`@kubohiroya/turbowarp-svg-text`は文字のSVG skinと文字幅の測定を担当し、吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationは担当しません。画像解決、音声再生、入力、条件評価はCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyとして対応機能を使う場合だけ接続します。
|
|
68
|
+
|
|
69
|
+
### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
|
|
70
|
+
|
|
71
|
+
セリフ全体を一度に表示するだけでなく、表示対象を「どの単位で一つずつ増やすか」として扱います。`CHARACTER`は形態素解析ではなく、表示上の書記素クラスタ(結合文字や絵文字を途中で分割しない単位)を前提にします。
|
|
72
|
+
|
|
73
|
+
仕様上の綴りは`CHARACTER`です(`charactor`ではありません)。`BLOCK`は、改行を含む複数行を一つの表示単位として扱う名前で、ここでいうblockはScratchのblockではありません。
|
|
74
|
+
|
|
75
|
+
```mermaid
|
|
76
|
+
flowchart LR
|
|
77
|
+
source["全文: 私の/名前は/中野/です"] --> mode{"表示単位"}
|
|
78
|
+
mode -->|CHARACTER| c["私 → 私の → 私の/ → …"]
|
|
79
|
+
mode -->|WORD| w["私の → 私の/名前は → …"]
|
|
80
|
+
mode -->|LINE| l["1行ずつ追加"]
|
|
81
|
+
mode -->|BLOCK| b["複数行/段落をまとめて追加"]
|
|
82
|
+
delimiter["任意の区切り文字集合<br/>例: スラッシュ、空白、縦線"] -.-> w
|
|
83
|
+
visibility{"区切り文字の表示"} -->|visible| shown["区切り文字も描画"]
|
|
84
|
+
visibility -->|invisible| hidden["区切り文字を隠して描画"]
|
|
85
|
+
delimiter --> visibility
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### WORDの区切り文字
|
|
89
|
+
|
|
90
|
+
日本語の形態素解析は行いません。`WORD`は空白で区切る言語、または利用者が区切りを埋め込める言語を対象にします。例えば`私の/名前は/中野/です`を入力し、`/`をWORD delimiterにして不可視にすれば、`私の`→`名前は`→`中野`→`です`の順で表示できます。区切り文字を可視にすれば、スラッシュを演出として残せます。
|
|
91
|
+
|
|
92
|
+
区切り文字は単一文字に限定せず、任意の文字集合として指定します。delimiter自体を表示単位に含めるか、取り除いてからText providerへ渡すかを選べるようにします。
|
|
93
|
+
|
|
94
|
+
### DYNAMICとRESERVED
|
|
95
|
+
|
|
96
|
+
逐次表示中の吹き出しサイズは、次の2方式を選べるようにします。
|
|
97
|
+
|
|
98
|
+
```mermaid
|
|
99
|
+
sequenceDiagram
|
|
100
|
+
participant Host as Host
|
|
101
|
+
participant Bubble as Bubble surface
|
|
102
|
+
participant Text as Text provider
|
|
103
|
+
Host->>Text: 全文をmeasure
|
|
104
|
+
alt RESERVED
|
|
105
|
+
Text-->>Bubble: 最終幅・最終行数
|
|
106
|
+
Bubble->>Bubble: 最終サイズを先に確保
|
|
107
|
+
loop 表示単位ごと
|
|
108
|
+
Host->>Text: 可視範囲を更新
|
|
109
|
+
Text-->>Bubble: 文字だけ更新
|
|
110
|
+
end
|
|
111
|
+
else DYNAMIC
|
|
112
|
+
loop 表示単位ごと
|
|
113
|
+
Host->>Text: 可視範囲を更新
|
|
114
|
+
Text-->>Bubble: 現在の幅・行数
|
|
115
|
+
Bubble->>Bubble: 外形とplacementを再計算
|
|
116
|
+
end
|
|
117
|
+
end
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
`RESERVED`は表示中に外形が動きにくく、`DYNAMIC`は短い文では余白を抑えられます。いずれもBubble外形のanimationやportraitレイヤーとは独立したレイアウト方針です。Composition APIではstyleの`reveal`、`handle.revealNext()`、`handle.revealAll()`が分割・タイミングの接続点になり、`intervalSeconds`を指定した自動送りにも対応します。
|
|
121
|
+
|
|
122
|
+
逐次表示を最後まで進めてから待機へ移る場合は、表示単位を明示したfinish指定を使います。
|
|
123
|
+
|
|
124
|
+
```text
|
|
125
|
+
finish [CHARACTER / WORD / LINE / BLOCK]
|
|
126
|
+
with condition [CONDITION]
|
|
127
|
+
or timeout after [TIMEOUT] seconds
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
`CONDITION`が成立したら未表示の単位を最後まで進め、成立しない場合も`TIMEOUT`秒後に同じ完了処理へ移します。`TIMEOUT`を`0`にすると時間制限を設けません。完了後は`awaiting-continue`へ移すか、hostが`close`または表示終了animationを開始します。Composition APIでは`handle.finish({ unit, condition, timeoutSeconds })`、手続き型拡張では`finish [UNIT] ...`ブロックを使います。
|
|
131
|
+
|
|
132
|
+
### 音声と表示単位
|
|
133
|
+
|
|
134
|
+
`finish`は公開Composition APIの`handle.finish({ unit, condition, timeoutSeconds })`と、TurboWarpの`finish [UNIT] ...`ブロックで利用できます。これは逐次表示を最後まで進め、条件成立またはtimeoutで音声と待機状態を確定します。
|
|
135
|
+
|
|
136
|
+
Asset Managerを音声providerとして接続すると、次の音声を同じ表示ライフサイクルに関連付けられます。
|
|
4
137
|
|
|
5
|
-
|
|
138
|
+
- 表示開始時のフルボイス
|
|
139
|
+
- `CHARACTER`/`WORD`/`LINE`/`BLOCK`を一つ進めるごとの効果音
|
|
140
|
+
- 表示終了、continue待機、timeoutの通知音
|
|
6
141
|
|
|
7
|
-
|
|
8
|
-
| ------------------------------------------ | ------------------------------------------------------------------------- |
|
|
9
|
-
| `@kubohiroya/turbowarp-asset-manager` | アセット名の登録、画像種別の検証、画像targetへの適用 |
|
|
10
|
-
| `@kubohiroya/turbowarp-svg-text` | 名前付き文字styleと、文字列からSVGスキンへの変換 |
|
|
11
|
-
| `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
|
|
12
|
-
| `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
|
|
13
|
-
| `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、say/think、表情レイヤー、animation mode、入力待機 |
|
|
14
|
-
| アプリ/host | 必要に応じたDSLからcomposition APIへの変換 |
|
|
142
|
+
表示単位ごとの効果音は、文字列を音声として合成する機能ではなく、名前付き音声assetを再生する経路です。音声がない場合でも、文字表示・portrait・Bubble外形は独立して利用できます。
|
|
15
143
|
|
|
16
|
-
|
|
144
|
+
### パッケージ境界
|
|
17
145
|
|
|
18
|
-
|
|
146
|
+
| パッケージ | 責務 |
|
|
147
|
+
| ------------------------------------------ | ------------------------------------------------------------------------------ |
|
|
148
|
+
| `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
|
|
149
|
+
| `@kubohiroya/turbowarp-svg-text` | 名前付き文字styleと、文字列からSVGスキンへの変換 |
|
|
150
|
+
| `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
|
|
151
|
+
| `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
|
|
152
|
+
| `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
|
|
153
|
+
| アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
|
|
154
|
+
|
|
155
|
+
Bubbleは依存パッケージを再exportしません。SVG Textは現在の文字描画に必要ですが、画像・音声・入力・条件評価はCapabilityとして差し替えられます。TurboWarp adapterではAsset Managerを自動接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
|
|
156
|
+
|
|
157
|
+
### 自動改行と禁則処理の基盤
|
|
19
158
|
|
|
20
159
|
Bubbleの任意`maxWidth`による自動改行では、`@cto.af/linebreak`を利用してUnicode UAX #14準拠の改行可能位置を求めます。依存は`LineBreakProvider` interfaceの内側へ閉じ込め、実際のフォントで測った幅から、上限内に収まる最も後ろの候補をBubble側で選びます。
|
|
21
160
|
|
|
@@ -31,13 +170,13 @@ const layout = wrapText({
|
|
|
31
170
|
});
|
|
32
171
|
```
|
|
33
172
|
|
|
34
|
-
|
|
173
|
+
Composition APIのBubble styleへ`maxWidth`と任意の`textLocale`を渡すと、Text capabilityの`measureText`を使ってこの`wrapText`基盤が実際の表示文字列を自動改行します。SVG Textまたはhost側のText capabilityが`measureText`を提供しない場合、`maxWidth`を使った表示は明示的なcapabilityエラーになります。
|
|
35
174
|
|
|
36
175
|

|
|
37
176
|
|
|
38
177
|
図の各行はproductionの`wrapText`を直接呼んだ結果です。図版専用の手作業改行は使っていません。
|
|
39
178
|
|
|
40
|
-
|
|
179
|
+
### Bubble visual styleの形状
|
|
41
180
|
|
|
42
181
|
形状候補は`NORMAL`、`THINKING`、`DREAMING`、`YELLING`、`OFF_PANEL`、`WAVY`、`WHISPERING`、`ANNOUNCEMENT`、`NARRATION`、`NO_BUBBLE`です。
|
|
43
182
|
|
|
@@ -49,41 +188,88 @@ standalone機能拡張では、`set bubble visual style`ブロックで形状を
|
|
|
49
188
|
|
|
50
189
|
配布bundleに含まれる依存ライブラリのライセンスは、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)を参照してください。
|
|
51
190
|
|
|
52
|
-
##
|
|
191
|
+
## 利用方法
|
|
53
192
|
|
|
54
|
-
|
|
193
|
+
### インストール
|
|
55
194
|
|
|
56
|
-
|
|
195
|
+
```sh
|
|
196
|
+
pnpm add @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
|
|
197
|
+
```
|
|
57
198
|
|
|
58
|
-
|
|
199
|
+
npmを使う場合は同じ依存を次のように追加します。
|
|
59
200
|
|
|
60
201
|
```sh
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
202
|
+
npm install @kubohiroya/turbowarp-bubble @kubohiroya/turbowarp-svg-text
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
現在のpeer dependency範囲は、SVG Textが`>=0.4.0 <1`、Asset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`です。Asset Manager、Async Input、Runtime Expressionはoptional peer dependencyです。
|
|
206
|
+
|
|
207
|
+
画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
|
|
208
|
+
|
|
209
|
+
```sh
|
|
210
|
+
pnpm add @kubohiroya/turbowarp-asset-manager \
|
|
64
211
|
@kubohiroya/turbowarp-async-input \
|
|
65
212
|
@kubohiroya/turbowarp-runtime-expression
|
|
66
213
|
```
|
|
67
214
|
|
|
68
|
-
|
|
215
|
+
```sh
|
|
216
|
+
npm install @kubohiroya/turbowarp-asset-manager \
|
|
217
|
+
@kubohiroya/turbowarp-async-input \
|
|
218
|
+
@kubohiroya/turbowarp-runtime-expression
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### TurboWarp機能拡張
|
|
222
|
+
|
|
223
|
+
ブロックの組み方、表情差分の準備、入力待ち、clone、エラー対処を含む手順は、ブロック利用マニュアル([English](https://kubohiroya.github.io/turbowarp-bubble/) / [日本語](https://kubohiroya.github.io/turbowarp-bubble/ja/))を参照してください。`talking`から`awaiting-continue`、入力成立、`close`までのアニメーション例も掲載しています。
|
|
224
|
+
|
|
225
|
+
#### TurboWarpでの導入
|
|
69
226
|
|
|
70
|
-
|
|
227
|
+
TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget APIへ接続する**unsandboxedカスタム拡張機能**です。TurboWarp Editorでは、次の順で読み込みます。
|
|
71
228
|
|
|
72
|
-
|
|
229
|
+
1. TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
|
|
230
|
+
2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
|
|
231
|
+
3. SVG Textを読み込みます。Bubbleの文字style定義と文字幅計測に必要です。
|
|
232
|
+
4. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Managerを読み込みます。
|
|
233
|
+
5. `wait with this bubble until condition ...`を使う場合はAsync InputとRuntime Expressionを読み込みます。
|
|
234
|
+
6. 最後にBubbleを読み込みます。依存拡張を先に読み込むと、対応するブロックとcapabilityが接続されます。
|
|
73
235
|
|
|
74
|
-
|
|
236
|
+
最小構成はTemporary Variables、SVG Text、Bubbleです。Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define text style`、`define bubble style`、`say`または`think`の順でブロックを配置します。
|
|
75
237
|
|
|
76
238
|
```text
|
|
77
|
-
|
|
78
|
-
https://unpkg.com/@kubohiroya/turbowarp-svg-text/dist/svg-text.js
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
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.0/dist/turbowarp-bubble.js
|
|
82
251
|
```
|
|
83
252
|
|
|
253
|
+
TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発中は、リポジトリをローカルHTTPサーバーで配信して`dist/turbowarp-bubble.js`を指定できます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。
|
|
254
|
+
|
|
255
|
+
#### Scratchとの互換性
|
|
256
|
+
|
|
257
|
+
Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカスタム拡張機能として直接利用することはできません。Scratch公式にはTurboWarpのunsandboxed拡張機能、renderer内部API、target drawable APIがないためです。Scratch向けの.sb3プロジェクトへこのREADMEのURLを追加しても、Bubbleのブロックは登録されません。
|
|
258
|
+
|
|
259
|
+
利用環境ごとの位置付けは次のとおりです。
|
|
260
|
+
|
|
261
|
+
| 環境 | 利用方法 | 対応 |
|
|
262
|
+
| ------------------------------- | --------------------------------------------------------------------- | ---------------------------- |
|
|
263
|
+
| TurboWarp Editor | `dist/turbowarp-bubble.js`をunsandboxedカスタム拡張機能として読み込む | 対応 |
|
|
264
|
+
| TurboWarp Packager/互換runtime | unsandboxedカスタム拡張機能とrenderer APIが利用できる構成で読み込む | 対応(環境ごとに確認が必要) |
|
|
265
|
+
| Scratch公式エディター | 公式拡張機能またはサンドボックス拡張機能として読み込む | 非対応 |
|
|
266
|
+
| 独自Webアプリ/ホスト | npmのcomposition APIまたはTurboWarp adapterをJavaScriptから利用する | 対応 |
|
|
267
|
+
|
|
268
|
+
Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
|
|
269
|
+
|
|
84
270
|
Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。SVG本体、文字、表情ベース、目パチ、口パク、次へアイコンのrenderer drawableは自動生成されるため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
|
|
85
271
|
|
|
86
|
-
|
|
272
|
+
#### 提供ブロック
|
|
87
273
|
|
|
88
274
|
| ブロック | 動作 |
|
|
89
275
|
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
@@ -95,11 +281,11 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
|
|
|
95
281
|
| `set bubble offset x [X] y [Y] scale [SCALE] % for bubble style [STYLE]` | 本体位置と、文字を含むBubble全体の拡大率を設定する |
|
|
96
282
|
| `set portrait base [ASSET] for bubble style [STYLE]` | 表情ベース画像を設定する。空文字でportrait全体を解除する |
|
|
97
283
|
| `set blink frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 目パチ差分を設定する。空リストで解除する |
|
|
98
|
-
| `set
|
|
99
|
-
| `set
|
|
284
|
+
| `set lip-sync frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 口パク差分を設定する。空リストで解除する |
|
|
285
|
+
| `set continue frames [ASSETS] every [SECONDS] seconds for bubble style [STYLE]` | 入力待ちアイコンを設定する。2フレーム以上必要。空リストで解除する |
|
|
100
286
|
| `say [MESSAGE] with bubble style [STYLE]` | `talking` modeでsay表示を開始または置換する |
|
|
101
287
|
| `think [MESSAGE] with bubble style [STYLE]` | `talking` modeでthink表示を開始または置換する |
|
|
102
|
-
| `set this bubble animation mode [MODE]` | `talking`/`awaiting-
|
|
288
|
+
| `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を切り替える |
|
|
103
289
|
| `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | 条件成立またはtimeoutまでBubbleを表示したまま待つ |
|
|
104
290
|
| `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
|
|
105
291
|
| `Bubble version` | 実装versionを返す |
|
|
@@ -108,7 +294,7 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
|
|
|
108
294
|
|
|
109
295
|
visual styleを設定しない場合は`NORMAL`です。本体drawableは文字・表情より背面に生成され、close、対象停止、runtime破棄時にSVG skinとともに解放されます。
|
|
110
296
|
|
|
111
|
-
|
|
297
|
+
#### Placement
|
|
112
298
|
|
|
113
299
|
`PLACEMENT`はActor相対と背景相対の二系統です。省略時は`up-right`です。
|
|
114
300
|
|
|
@@ -130,7 +316,7 @@ Actor相対の正規方向名は次の16個です。別名は大文字小文字
|
|
|
130
316
|
|
|
131
317
|

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

|
|
136
322
|
|
|
@@ -138,17 +324,79 @@ Actor相対の`distance`はActorのStage座標AABB(axis-aligned bounding box
|
|
|
138
324
|
|
|
139
325
|
`offset x/y/scale`の既定値は`[0, 0, 100]`です。xは右、yは上が正です。scaleはBubble外形だけでなく、SVG Textの文字(フォントサイズ)、表情画像、次へアイコン、内部余白へ一体で適用します。scaleだけを変えた場合は、拡大量の半径分だけ本体中心をActorから離し、Actor側の間隔を維持します。その後x/y offsetを加え、固定したtail先端へ向けてtailを再生成するため、offset後の実長は`tail length`から変化し得ます。Stage端では全体が画面内に収まるようクランプします。これら3設定は背景相対placementでは無視します。
|
|
140
326
|
|
|
141
|
-
|
|
327
|
+
#### Portraitとblink / lip-sync
|
|
328
|
+
|
|
329
|
+
portraitは、位置合わせ済みの透明画像を重ねるレイヤーです。ベース画像と差分画像を同じcanvasサイズ・中心位置で用意すると、顔を描き直さずに目と口だけを更新できます。
|
|
330
|
+
|
|
331
|
+
```mermaid
|
|
332
|
+
flowchart TB
|
|
333
|
+
bubble[Bubble surface]
|
|
334
|
+
body[Bubble body / text]
|
|
335
|
+
base[portraitBase\n顔・髪・輪郭]
|
|
336
|
+
blink[portraitBlink\n目パチ差分]
|
|
337
|
+
lipsync[portraitLipSync\n口パク差分]
|
|
338
|
+
continue[continueIndicator\n次へアイコン]
|
|
339
|
+
bubble --> body
|
|
340
|
+
bubble --> base
|
|
341
|
+
base --> blink
|
|
342
|
+
base --> lipsync
|
|
343
|
+
bubble --> continue
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
| レイヤー | 表示中の動作 | 設定ブロック/API |
|
|
347
|
+
| ------------------- | ------------------------------------------------------ | ------------------------------------------- |
|
|
348
|
+
| `portraitBase` | 常時表示するベース画像 | `set portrait base` / `portrait.base` |
|
|
349
|
+
| `portraitBlink` | `talking`、`awaiting-continue`、`idle`のすべてでループ | `set blink frames` / `portrait.blink` |
|
|
350
|
+
| `portraitLipSync` | `talking`中だけループし、待機時は停止・非表示 | `set lip-sync frames` / `portrait.lipSync` |
|
|
351
|
+
| `continueIndicator` | `awaiting-continue`中だけループ | `set continue frames` / `continueIndicator` |
|
|
352
|
+
|
|
353
|
+
目パチと口パクは1枚の静止画でも利用できます。口パクのキーワードは、話す行為全体ではなく口元の表情差分を指定する意味で`lip-sync`に統一しています。`continue`は、入力待ちを表すアイコンのanimationであり、JavaScriptの`continue`文を実行する機能ではありません。
|
|
354
|
+
|
|
355
|
+

|
|
356
|
+
|
|
357
|
+
#### Bubble animation
|
|
358
|
+
|
|
359
|
+
Bubbleのanimationは、画像フレームのループ(blink、lip-sync、continue)と、Bubble surface自体の変形を分けて考えます。現在公開している`set this bubble animation mode`は前者の動作modeを切り替えます。後者は、同じsurfaceへ適用する汎用animation仕様として整理します。
|
|
360
|
+
|
|
361
|
+
```mermaid
|
|
362
|
+
flowchart LR
|
|
363
|
+
start[表示開始] --> in[表示開始animation\nfadeIn / floatIn / zoomIn / riseUp]
|
|
364
|
+
in --> visible[表示中]
|
|
365
|
+
visible --> shake[shake\n方向・回数・ease]
|
|
366
|
+
visible --> explode[explode\n相対サイズ・回数・ease]
|
|
367
|
+
visible --> shape[animateBubbleShape\n速度・時間]
|
|
368
|
+
visible --> waiting[awaiting-continue]
|
|
369
|
+
waiting --> out[表示終了animation\nfadeOut / floatOut / zoomOut / sink]
|
|
370
|
+
out --> released[close・resource解放]
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
##### 表示開始と表示終了
|
|
374
|
+
|
|
375
|
+
PowerPointの用語を参考にしつつ、Bubbleの仕様名は「表示開始animation」「表示終了animation」とします。表示開始には`fadeIn`、`floatIn`、`zoomIn`、`riseUp`、表示終了には`fadeOut`、`floatOut`、`zoomOut`、`sink`を使います。表示開始・表示終了animationは`RESERVED`だけに限定しません。`DYNAMIC`で表示サイズを更新しているBubbleにも適用でき、表示終了時には現在の外形を基準に終点を計算します。
|
|
376
|
+
|
|
377
|
+
##### 表示中の変形
|
|
142
378
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
| `awaiting-advance` | 実行 | 停止・非表示 | ループ実行 |
|
|
147
|
-
| `idle` | 実行 | 停止・非表示 | 停止・非表示 |
|
|
379
|
+
- `shake + direction + count + ease`: 吹き出し全体を指定方向へ揺らします。`direction`は水平・垂直・斜めを指定でき、`count`は往復回数、`ease`は各往復の速度曲線です。
|
|
380
|
+
- `explode + relativeScale + count + ease`: 現在サイズを基準に拡大・縮小を繰り返します。portraitとTextを含むsurface全体へ同じ相対変化を適用します。
|
|
381
|
+
- `animateBubbleShape + speed + duration`: `THINKING`、`DREAMING`、`YELLING`、`WAVY`、`WHISPERING`などの外形を指定速度・時間で切り替えます。`visualStyle`の切替と、表示中のsurface animationを分離できます。
|
|
148
382
|
|
|
149
|
-
|
|
383
|
+
TurboWarp adapterは16ms単位のscheduler tickで各animationを進め、`ease`を各フレームの進行率へ適用します。`fadeIn`/`fadeOut`はrendererの`ghost`効果、`float`/`rise`/`sink`は位置、`zoom`/`explode`は倍率をText・portrait・Bubble本体へ同じように適用します。`shake`は指定回数の往復を行い、`explode`は拡大と復帰を繰り返します。`durationSeconds`を省略した`shake`/`explode`には、回数に応じた既定時間を使います。
|
|
150
384
|
|
|
151
|
-
|
|
385
|
+
`animateBubbleShape`は、現在形状と指定形状を各フレームでcross-fadeするSVG body skinへ更新します。Textとportraitは再生成せず、外形だけを連続的に切り替えます。`speed`は指定時間内の形状遷移速度倍率です。
|
|
386
|
+
|
|
387
|
+
animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.updateStyle()`、`handle.close()`のライフサイクルに接続します。新しいBubbleで同じ`actorKey`を置き換えると、旧animationのtimerとdrawableを先に解放します。`shake`には`ease`を指定でき、`explode`には`relativeScale`、`count`、`ease`、`animateBubbleShape`には`speed`と`durationSeconds`を指定できます。
|
|
388
|
+
|
|
389
|
+
#### Animation mode
|
|
390
|
+
|
|
391
|
+
| mode | 目パチ | 口パク | continue frames |
|
|
392
|
+
| ------------------- | ------ | ------------ | --------------- |
|
|
393
|
+
| `talking` | 実行 | 実行 | 非表示 |
|
|
394
|
+
| `awaiting-continue` | 実行 | 停止・非表示 | ループ実行 |
|
|
395
|
+
| `idle` | 実行 | 停止・非表示 | 停止・非表示 |
|
|
396
|
+
|
|
397
|
+
`say`/`think`ブロックは`talking`で表示を開始し、すぐ次のブロックへ進みます。`wait with this bubble ...`は自動的に`awaiting-continue`へ移り、Async Inputが更新するruntime変数をRuntime Expressionで評価します。条件成立またはtimeout後は`idle`へ移って次のブロックへ進みます。
|
|
398
|
+
|
|
399
|
+
#### ブロック構成例
|
|
152
400
|
|
|
153
401
|
```text
|
|
154
402
|
define bubble style [hero-dialogue] using text style [dialogue-text]
|
|
@@ -159,8 +407,8 @@ set bubble tail length [18] for bubble style [hero-dialogue]
|
|
|
159
407
|
set bubble offset x [10] y [-10] scale [120] % for bubble style [hero-dialogue]
|
|
160
408
|
set portrait base [HeroFace] for bubble style [hero-dialogue]
|
|
161
409
|
set blink frames [HeroEyesOpen,HeroEyesClosed] every [0.4] seconds for bubble style [hero-dialogue]
|
|
162
|
-
set
|
|
163
|
-
set
|
|
410
|
+
set lip-sync frames [HeroMouthClosed,HeroMouthOpen] every [0.1] seconds for bubble style [hero-dialogue]
|
|
411
|
+
set continue frames [Next1,Next2] every [0.2] seconds for bubble style [hero-dialogue]
|
|
164
412
|
set runtime variable [input] to []
|
|
165
413
|
listen for key [Space] set runtime var [input] to [pressed]
|
|
166
414
|
listen for touch on this sprite set runtime var [input] to [pressed]
|
|
@@ -171,9 +419,9 @@ close this bubble
|
|
|
171
419
|
|
|
172
420
|
プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、SVG text skin、drawableを自動解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
|
|
173
421
|
|
|
174
|
-
|
|
422
|
+
### Composition API
|
|
175
423
|
|
|
176
|
-
TurboWarp runtimeのrenderer、
|
|
424
|
+
TurboWarp runtimeのrenderer、SVG Textへ直接接続するhostでは、公開adapterを利用できます。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
|
|
177
425
|
|
|
178
426
|
```ts
|
|
179
427
|
import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
|
|
@@ -184,43 +432,43 @@ const bubbles = createTurboWarpBubbleComposition(runtime);
|
|
|
184
432
|
描画surfaceをhost側で実装する場合は、以下の低レベルComposition APIを利用します。
|
|
185
433
|
|
|
186
434
|
```ts
|
|
187
|
-
import {
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
fontPercent: 100,
|
|
200
|
-
alignment: "left",
|
|
201
|
-
});
|
|
435
|
+
import {
|
|
436
|
+
createBubbleComposition,
|
|
437
|
+
type BubbleImageCapability,
|
|
438
|
+
type BubbleSurfaceFactory,
|
|
439
|
+
type BubbleSvgText,
|
|
440
|
+
} from "@kubohiroya/turbowarp-bubble/composition";
|
|
441
|
+
|
|
442
|
+
// These are host-owned capabilities. They may be backed by Asset Manager,
|
|
443
|
+
// another asset service, or local application code.
|
|
444
|
+
declare const imageResolver: BubbleImageCapability;
|
|
445
|
+
declare const svgText: BubbleSvgText;
|
|
446
|
+
declare const bubbleSurfaceHost: BubbleSurfaceFactory;
|
|
202
447
|
|
|
203
448
|
const bubbles = createBubbleComposition({
|
|
204
|
-
|
|
449
|
+
imageResolver,
|
|
205
450
|
svgText,
|
|
206
|
-
|
|
207
|
-
// hostがActorの近くへsurfaceを配置し、各レイヤー用のtargetを返します。
|
|
208
|
-
return bubbleSurfaceHost.create({ actor, actorKey, kind, style });
|
|
209
|
-
},
|
|
451
|
+
createSurface: bubbleSurfaceHost,
|
|
210
452
|
});
|
|
211
453
|
```
|
|
212
454
|
|
|
455
|
+
`declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleSvgText`(文字skinの適用・解放)、`BubbleImageCapability`(画像名の解決)、`BubbleAudioCapability`(音声再生)、`BubbleSurfaceFactory`(外枠・text・portrait各targetの生成)を実装して渡します。TurboWarp runtimeを使う場合は、これらを個別に実装せず`createTurboWarpBubbleComposition(runtime)`を使えます。
|
|
456
|
+
|
|
457
|
+
テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
|
|
458
|
+
|
|
213
459
|
`createSurface`が返すsurfaceは、次のtargetを持ちます。
|
|
214
460
|
|
|
461
|
+
surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
|
|
462
|
+
|
|
215
463
|
- `text`: SVG Textが文字スキンを適用するtarget
|
|
216
464
|
- `portraitBase`: キャラクター表情のベース画像target
|
|
217
465
|
- `portraitBlink`: 目パチ差分target
|
|
218
|
-
- `
|
|
219
|
-
- `
|
|
466
|
+
- `portraitLipSync`: 口パク差分target
|
|
467
|
+
- `continueIndicator`: 「次へ」アイコンtarget
|
|
220
468
|
|
|
221
469
|
画像レイヤーのtarget IDは互いに異なる必要があります。styleで使わないレイヤーのtargetは省略できます。
|
|
222
470
|
|
|
223
|
-
|
|
471
|
+
#### Styleと表示
|
|
224
472
|
|
|
225
473
|
```ts
|
|
226
474
|
bubbles.defineStyle({
|
|
@@ -237,21 +485,35 @@ bubbles.defineStyle({
|
|
|
237
485
|
frames: ["HeroEyesOpen", "HeroEyesClosed"],
|
|
238
486
|
frameIntervalSeconds: 0.4,
|
|
239
487
|
},
|
|
240
|
-
|
|
488
|
+
lipSync: {
|
|
241
489
|
frames: ["HeroMouthClosed", "HeroMouthOpen"],
|
|
242
490
|
frameIntervalSeconds: 0.1,
|
|
243
491
|
},
|
|
244
492
|
},
|
|
245
|
-
|
|
493
|
+
continueIndicator: {
|
|
246
494
|
frames: ["Next1", "Next2"],
|
|
247
495
|
frameIntervalSeconds: 0.2,
|
|
248
496
|
},
|
|
497
|
+
reveal: {
|
|
498
|
+
unit: "CHARACTER",
|
|
499
|
+
layout: "RESERVED",
|
|
500
|
+
intervalSeconds: 0.05,
|
|
501
|
+
sound: "Typewriter",
|
|
502
|
+
},
|
|
503
|
+
audio: {
|
|
504
|
+
voice: "HeroVoice",
|
|
505
|
+
reveal: "Typewriter",
|
|
506
|
+
},
|
|
507
|
+
showAnimation: { name: "fadeIn", durationSeconds: 0.2 },
|
|
508
|
+
hideAnimation: { name: "fadeOut", durationSeconds: 0.2 },
|
|
249
509
|
});
|
|
250
510
|
|
|
251
511
|
bubbles.defineStyle({
|
|
252
512
|
name: "narration",
|
|
253
513
|
textStyle: "dialogue-text",
|
|
254
514
|
placement: "FOOTER_LIKE",
|
|
515
|
+
maxWidth: 320,
|
|
516
|
+
textLocale: "ja",
|
|
255
517
|
});
|
|
256
518
|
|
|
257
519
|
const bubble = await bubbles.show({
|
|
@@ -263,25 +525,39 @@ const bubble = await bubbles.show({
|
|
|
263
525
|
});
|
|
264
526
|
```
|
|
265
527
|
|
|
266
|
-
`show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-
|
|
528
|
+
`show`の初期animation modeは`talking`です。目パチは表示中継続し、口パクが動きます。全文表示後にアプリが「次へ」操作待ちへ移るとき、modeを`awaiting-continue`へ変更します。
|
|
267
529
|
|
|
268
530
|
```ts
|
|
269
|
-
await bubble.setAnimationMode("awaiting-
|
|
531
|
+
await bubble.setAnimationMode("awaiting-continue");
|
|
270
532
|
// 口パクを停止して非表示にし、「次へ」アイコンをループ表示します。
|
|
271
533
|
|
|
272
534
|
await bubble.setAnimationMode("idle");
|
|
273
535
|
// 吹き出しを残したまま、口パクと「次へ」アイコンを停止します。
|
|
274
536
|
|
|
537
|
+
await bubble.revealNext();
|
|
538
|
+
await bubble.revealAll();
|
|
539
|
+
await bubble.animate({
|
|
540
|
+
name: "shake",
|
|
541
|
+
direction: 90,
|
|
542
|
+
count: 2,
|
|
543
|
+
ease: "easeInOut",
|
|
544
|
+
});
|
|
545
|
+
await bubble.finish({
|
|
546
|
+
unit: "CHARACTER",
|
|
547
|
+
condition: () => inputState === "pressed",
|
|
548
|
+
timeoutSeconds: 10,
|
|
549
|
+
});
|
|
550
|
+
|
|
275
551
|
await bubble.close();
|
|
276
552
|
```
|
|
277
553
|
|
|
278
|
-
返されたhandleの`setText(text)`は同じsurface
|
|
554
|
+
返されたhandleの`setText(text)`は同じsurface上の本文を更新し、文字送りなどに利用できます。`handle.updateStyle(style)`は表示中のBubbleへstyle変更を即時適用します。同じ`actorKey`へ新しいBubbleを表示すると、以前のBubbleを完全に破棄してから置き換えます。`releaseTarget`、`releaseAll`、`dispose`も、所有するtimer、SVG Text target、surfaceを解放します。composition間で状態は共有しません。
|
|
279
555
|
|
|
280
|
-
##
|
|
556
|
+
## ライセンスとソースコード
|
|
281
557
|
|
|
282
|
-
|
|
558
|
+
このパッケージのSource Code Formは[MPL-2.0](https://www.mozilla.org/MPL/2.0/)の条件で提供します。対応するソースコードは[GitHubリポジトリ](https://github.com/kubohiroya/turbowarp-bubble)から取得できます。npmおよびCDNで配布するJavaScript bundleに対応するソースコードも、このリポジトリの同じpackage versionから参照できます。
|
|
283
559
|
|
|
284
|
-
|
|
560
|
+
配布物に組み込まれる第三者ソフトウェアの著作権表示とライセンス条件は、[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)にまとめています。
|
|
285
561
|
|
|
286
562
|
## 開発
|
|
287
563
|
|