@kubohiroya/turbowarp-bubble 0.7.0 → 0.8.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 +69 -28
- package/THIRD_PARTY_NOTICES.md +10 -0
- package/dist/turbowarp-adapter.js +2098 -939
- package/dist/turbowarp-bubble.js +1605 -121
- package/dist/types/asset-manager-image-adapter.d.ts +18 -0
- package/dist/types/surface-motion.d.ts +8 -0
- package/dist/types/svg-overlay-surface.d.ts +97 -0
- package/dist/types/text-capability.d.ts +2 -2
- package/dist/types/turbowarp-adapter.d.ts +19 -2
- package/dist/types/turbowarp-svg-text-adapter.d.ts +35 -0
- package/docs/assets/block-quick-start.svg +27 -52
- package/docs/block-manual.ja.md +17 -24
- package/docs/block-manual.md +30 -37
- package/docs/index.html +23 -32
- package/docs/ja/index.html +23 -32
- package/docs/release-notes-0.8.0.md +45 -0
- package/package.json +6 -9
package/README.md
CHANGED
|
@@ -34,7 +34,7 @@ flowchart LR
|
|
|
34
34
|
|
|
35
35
|
| 領域 | このREADMEで説明する内容 | 現在の公開API |
|
|
36
36
|
| ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------- |
|
|
37
|
-
| 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(
|
|
37
|
+
| 文字描画・改行 | `BubbleTextCapability`、名前付きstyle、実測幅、`maxWidth`、UAX #14準拠の改行 | 実装済み(SVG Text 0.8.0のhost-neutral layoutを標準接続) |
|
|
38
38
|
| 逐次表示 | `CHARACTER`/`WORD`/`LINE`/`BLOCK`、区切り文字、単位ごとの効果音、finish条件 | 実装済み(`revealNext`/`revealAll`/`finish`、対応ブロック) |
|
|
39
39
|
| portrait | ベース画像、`blink`、`lip-sync`の独立レイヤー | 実装済み(Asset Manager capability) |
|
|
40
40
|
| Bubble外形 | `NORMAL`等のvisual style、placement、tail、offset、scale | 実装済み |
|
|
@@ -52,7 +52,7 @@ flowchart TB
|
|
|
52
52
|
core["Bubble core\n外形・配置・ライフサイクル・animation state"]
|
|
53
53
|
contract["BubbleTextCapability\nhost-neutralな文字契約"]
|
|
54
54
|
twAdapter["TurboWarp Bubble adapter\nrenderer / runtime / targetへの接続"]
|
|
55
|
-
svgAdapter["SVG Text adapter\
|
|
55
|
+
svgAdapter["SVG Text 0.8 layout adapter\nrenderer非依存の行layout・計測"]
|
|
56
56
|
assets["任意のImage / Audio capability\nportrait・lip-sync・音声"]
|
|
57
57
|
input["任意のInput / Expression capability\n入力・待機条件"]
|
|
58
58
|
host["独自Webアプリ / host"]
|
|
@@ -67,7 +67,58 @@ flowchart TB
|
|
|
67
67
|
extension -."optional".-> input
|
|
68
68
|
```
|
|
69
69
|
|
|
70
|
-
この構成では、Bubble coreが`BubbleTextCapability
|
|
70
|
+
この構成では、Bubble coreが`BubbleTextCapability`というホスト非依存の契約だけを参照します。TurboWarp adapterの既定経路は直接依存する`@kubohiroya/turbowarp-svg-text@0.8.0`の`createSvgTextLayoutComposition().layoutText()`を使い、SVG skinを生成せず行layoutと文字幅を得ます。吹き出しの外枠、tail、portraitの配置、表示開始・表示終了animationはSVG Textの責務に含めません。Composition APIのhostは別の実装を`textCapability`として注入できます。画像解決、音声再生、入力、条件評価もCapabilityとして切り離し、Asset Manager、Async Input、Runtime Expressionは対応機能を使う場合だけ接続します。
|
|
71
|
+
|
|
72
|
+
### 描画backend(SVG overlayが既定)
|
|
73
|
+
|
|
74
|
+
`bubbleRenderBackend`を省略した場合の既定値は`"svg-overlay"`です。`renderer.addOverlay(root, "scale")`でstage canvas上に共有SVG rootを置き、body、tail、text、portrait、corner clip、continue indicatorをDOM要素として描画します。文字にはBubbleが内包するSVG Text 0.8.0のhost-neutral layoutを使います。この既定経路ではBubbleの表示、text更新、style更新、animationのために`createDrawable()`、`createSVGSkin()`、`createBitmapSkin()`を呼ばず、Bubble由来の処理はscratch-renderの`SVGSkin`/`Silhouette`経路へ入りません。`"scratch-render"`は互換性とロールバックのため明示指定時だけ使用します。
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
import { createAssetManagerComposition } from "@kubohiroya/turbowarp-asset-manager/composition";
|
|
78
|
+
import { createSvgTextLayoutComposition } from "@kubohiroya/turbowarp-svg-text/composition";
|
|
79
|
+
import {
|
|
80
|
+
createAssetManagerSvgOverlayImageCapability,
|
|
81
|
+
createSvgTextOverlayTextCapability,
|
|
82
|
+
createTurboWarpBubbleComposition,
|
|
83
|
+
} from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
|
|
84
|
+
|
|
85
|
+
const assets = createAssetManagerComposition();
|
|
86
|
+
const textLayouts = createSvgTextLayoutComposition();
|
|
87
|
+
|
|
88
|
+
textLayouts.defineStyle({
|
|
89
|
+
name: "dialogue-text",
|
|
90
|
+
alignment: "left",
|
|
91
|
+
backgroundColor: "transparent",
|
|
92
|
+
font: "Helvetica",
|
|
93
|
+
fontPercent: 100,
|
|
94
|
+
textColor: "#575e75",
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
const bubbles = createTurboWarpBubbleComposition(runtime, {
|
|
98
|
+
svgOverlayTextCapability: createSvgTextOverlayTextCapability(textLayouts),
|
|
99
|
+
svgOverlayImageCapability:
|
|
100
|
+
createAssetManagerSvgOverlayImageCapability(assets),
|
|
101
|
+
});
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`svgOverlayTextCapability`を省略すると、BubbleはSVG Text 0.8.0のlayout compositionを生成します。`default`および初めて参照されたtext-style名は、Bubble内で背景透明のSVG Text既定styleとして初期化されます。上のようにcapabilityを明示すると、hostが定義したnamed styleへ置換できます。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"`です。
|
|
105
|
+
|
|
106
|
+
既定文字providerは直接依存するSVG Text 0.8.0です。画像adapterには`resolveDOMImageResource()`を公開するAsset Manager 0.12.0以降が必要です。
|
|
107
|
+
|
|
108
|
+
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)で公開済みです。Bubbleは上流の公開APIだけを利用し、private field参照やskinからの抽出では代替しません。必要な公開capabilityがないhostで`svg-overlay`を選ぶと`BUBBLE-RUNTIME-004`を返します。明示的に`svgOverlayUnsupportedBehavior: "fallback"`を指定した場合だけ`scratch-render`へ戻ります。
|
|
109
|
+
|
|
110
|
+
| host/取得方法 | `scratch-render` | `svg-overlay` |
|
|
111
|
+
| ----------------------------------------- | ---------------- | ------------------------------------------------------ |
|
|
112
|
+
| TurboWarp Web/Desktop | 対応 | overlay APIと上記公開capabilityがある構成で対応 |
|
|
113
|
+
| TurboWarp Packager/player HTML | 対応 | 同上。packaged DOMにoverlay rootを保持できる場合に対応 |
|
|
114
|
+
| `renderer.addOverlay`非対応host | 対応 | 既定は明示error。設定時だけfallback |
|
|
115
|
+
| OS screenshot/画面収録 | 表示される | 最終browser compositeに表示される |
|
|
116
|
+
| `renderer.canvas.toDataURL()`/`toBlob()` | 表示される | raw WebGL canvasには含まれない |
|
|
117
|
+
| `renderer.canvas.captureStream()` | 表示される | raw WebGL streamには含まれない |
|
|
118
|
+
|
|
119
|
+
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)`を呼びます。
|
|
120
|
+
|
|
121
|
+
自動回帰テストでは、既定設定で表示、text更新、shake、shape animationを行ってもBubble由来renderer skin/drawable作成が0回であること、native size更新、共有root、上流SVG Text 0.8.0の行座標・角丸、許可属性、object URL解放を検証します。Web/Desktop/Packagerでのvisual parityとframe time/memoryのmanual gateは[SVG overlay release note](docs/release-notes-0.8.0.md)に記録します。
|
|
71
122
|
|
|
72
123
|
### 逐次表示の単位(CHARACTER / WORD / LINE / BLOCK)
|
|
73
124
|
|
|
@@ -150,13 +201,13 @@ Asset Managerを音声providerとして接続すると、次の音声を同じ
|
|
|
150
201
|
| ------------------------------------------ | ------------------------------------------------------------------------------ |
|
|
151
202
|
| `@kubohiroya/turbowarp-asset-manager` | 任意のImage/Audio capabilityをTurboWarp assetへ接続(画像解決・音声再生) |
|
|
152
203
|
| Bubble core(`composition`) | `BubbleTextCapability`契約、吹き出しsurface、配置、逐次表示、animation |
|
|
153
|
-
| `@kubohiroya/turbowarp-svg-text` |
|
|
204
|
+
| `@kubohiroya/turbowarp-svg-text` | 0.8.0のhost-neutralなplain/ruby layoutと文字幅計測 |
|
|
154
205
|
| `@kubohiroya/turbowarp-async-input` | キー入力・タップをTemporary Variablesのruntime変数へ反映 |
|
|
155
206
|
| `@kubohiroya/turbowarp-runtime-expression` | runtime変数を参照する安全な待機条件の評価 |
|
|
156
207
|
| `@kubohiroya/turbowarp-bubble` | 吹き出しsurface、配置、逐次表示、say/think、表情レイヤー、animation、入力待機 |
|
|
157
208
|
| アプリ/host | 必要に応じたアプリ固有の入力からcomposition APIへの変換 |
|
|
158
209
|
|
|
159
|
-
Bubbleは依存パッケージを再export
|
|
210
|
+
Bubbleは依存パッケージを再exportしません。低レベルComposition APIは`textCapability`を必須の契約として受け取り、SVG Textに限定されません。TurboWarp adapterは直接依存するSVG Text 0.8.0のlayout compositionを既定providerとして生成します。画像・音声・入力・条件評価はCapabilityとして差し替えられ、TurboWarp adapterではAsset Managerを遅延接続し、Composition APIでは`imageResolver`/`audio`をhostが任意に実装できます。Asset Managerを使う機能は画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音などの外部メディアも対象にします。
|
|
160
211
|
|
|
161
212
|
### 自動改行と禁則処理の基盤
|
|
162
213
|
|
|
@@ -229,13 +280,7 @@ const reveal = normalizeBubbleReveal({ unit: "CHARACTER" });
|
|
|
229
280
|
const chunks = splitBubbleText("A👩🚀B", reveal);
|
|
230
281
|
```
|
|
231
282
|
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
TurboWarp adapterの既定文字経路を使う場合は、SVG Textを追加します。
|
|
235
|
-
|
|
236
|
-
```sh
|
|
237
|
-
pnpm add @kubohiroya/turbowarp-svg-text
|
|
238
|
-
```
|
|
283
|
+
SVG Text 0.8.0は既定のskin非依存文字providerとして通常dependencyに含まれます。別途インストールしたり、standalone SVG Text拡張を先に読み込んだりする必要はありません。optional peer dependencyはAsset Managerが`>=0.7.0 <1`、Async InputとRuntime Expressionがそれぞれ`>=0.3.0 <1`です。hostが独自の`svgOverlayTextCapability`を注入する場合も、Bubble自身が利用する0.8.0 dependencyは固定されます。
|
|
239
284
|
|
|
240
285
|
画像portrait、lip-sync、continue indicator、または音声アセットを使う機能を利用する場合はAsset Managerを追加します。`CONDITION`付きの待機ブロックを使う場合はAsync InputとRuntime Expressionを追加します。
|
|
241
286
|
|
|
@@ -261,17 +306,13 @@ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget
|
|
|
261
306
|
|
|
262
307
|
1. TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
|
|
263
308
|
2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
|
|
264
|
-
3.
|
|
265
|
-
4.
|
|
266
|
-
5.
|
|
267
|
-
6. 最後にBubbleを読み込みます。依存拡張を先に読み込むと、対応するブロックとcapabilityが接続されます。
|
|
309
|
+
3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Managerを読み込みます。
|
|
310
|
+
4. `wait with this bubble until condition ...`を使う場合はAsync InputとRuntime Expressionを読み込みます。
|
|
311
|
+
5. 最後にBubbleを読み込みます。SVG Text 0.8.0のlayout providerはBubble bundleに含まれます。
|
|
268
312
|
|
|
269
|
-
|
|
313
|
+
文字だけの最小構成はBubbleです。Temporary Variables、Asset Manager、Async Input、Runtime Expressionは、対応する機能を使わなければ追加しなくても構いません。拡張機能を読み込んだ後、`define bubble style`、`say`または`think`の順でブロックを配置します。text styleには`default`または任意の名前を指定でき、standalone既定providerでは背景透明のSVG Text既定値として初期化されます。
|
|
270
314
|
|
|
271
315
|
```text
|
|
272
|
-
# SVG Text(必須)
|
|
273
|
-
https://unpkg.com/@kubohiroya/turbowarp-svg-text@0.4.0/dist/svg-text.js
|
|
274
|
-
|
|
275
316
|
# portrait/blink/lip-sync/continue/音声を使う場合だけ追加
|
|
276
317
|
https://unpkg.com/@kubohiroya/turbowarp-asset-manager@0.7.0/dist/asset-manager.js
|
|
277
318
|
|
|
@@ -280,7 +321,7 @@ https://unpkg.com/@kubohiroya/turbowarp-async-input@0.3.0/dist/async-input.js
|
|
|
280
321
|
https://unpkg.com/@kubohiroya/turbowarp-runtime-expression@0.3.0/dist/runtime-expression.js
|
|
281
322
|
|
|
282
323
|
# Bubble(必ず最後)
|
|
283
|
-
https://unpkg.com/@kubohiroya/turbowarp-bubble@0.
|
|
324
|
+
https://unpkg.com/@kubohiroya/turbowarp-bubble@0.8.0/dist/turbowarp-bubble.js
|
|
284
325
|
```
|
|
285
326
|
|
|
286
327
|
TurboWarpのカスタム拡張機能はURLからJavaScriptを読み込むため、初回読み込み時にネットワーク接続が必要です。開発中は、リポジトリをローカルHTTPサーバーで配信して`dist/turbowarp-bubble.js`を指定できます。`file://`で直接開いたファイルや、サンドボックス付きの拡張機能としては動作しません。
|
|
@@ -300,13 +341,13 @@ Scratch公式エディター(Scratch 3.0)から、TurboWarp Bubbleをカス
|
|
|
300
341
|
|
|
301
342
|
Scratch互換の別runtimeで利用するには、そのruntimeがTurboWarpと同じunsandboxed APIとrenderer契約を実装している必要があります。独自Webアプリでは、TurboWarp用のブロック拡張機能ではなく、`@kubohiroya/turbowarp-bubble/composition`または`@kubohiroya/turbowarp-bubble/turbowarp-adapter`を利用してください。
|
|
302
343
|
|
|
303
|
-
Bubbleは呼び出し元のsprite、clone、またはStage
|
|
344
|
+
Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所有します。既定backendではSVG本体、文字、表情ベース、目パチ、口パク、次へアイコンを共有overlay DOM内のレイヤーとして生成するため、レイヤー用spriteをプロジェクトへ追加する必要はありません。Stageから表示できるのは背景相対placementを使うstyleだけです。
|
|
304
345
|
|
|
305
346
|
#### 提供ブロック
|
|
306
347
|
|
|
307
348
|
| ブロック | 動作 |
|
|
308
349
|
| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
|
|
309
|
-
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble style
|
|
350
|
+
| `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義し、文字layout style名を関連付ける |
|
|
310
351
|
| `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
|
|
311
352
|
| `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
|
|
312
353
|
| `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Bubble本体のSVG形状を10種類から設定する |
|
|
@@ -432,7 +473,7 @@ animationは`show`、`handle.animate()`、`handle.setAnimationMode()`、`handle.
|
|
|
432
473
|
#### ブロック構成例
|
|
433
474
|
|
|
434
475
|
```text
|
|
435
|
-
define bubble style [hero-dialogue] using text style [
|
|
476
|
+
define bubble style [hero-dialogue] using text style [default]
|
|
436
477
|
set bubble placement [up-right] for bubble style [hero-dialogue]
|
|
437
478
|
set bubble distance [12] for bubble style [hero-dialogue]
|
|
438
479
|
set bubble visual style [NORMAL] for bubble style [hero-dialogue]
|
|
@@ -450,11 +491,11 @@ wait with this bubble until condition [input == "pressed"] or timeout after [10]
|
|
|
450
491
|
close this bubble
|
|
451
492
|
```
|
|
452
493
|
|
|
453
|
-
プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、SVG
|
|
494
|
+
プロジェクト開始・停止、対象sprite/cloneの停止、runtime破棄でも、所有するtimer、overlay DOM、画像leaseを自動解放します。明示的に`scratch-render`を選んだ場合は、従来どおり所有するSVG skinとdrawableも解放します。依存拡張が未ロードの場合は、必要なnpmパッケージ名を含むerrorを返します。
|
|
454
495
|
|
|
455
496
|
### Composition API
|
|
456
497
|
|
|
457
|
-
TurboWarp runtimeのrenderer
|
|
498
|
+
TurboWarp runtimeのrendererへ接続するhostでは、公開adapterを利用できます。既定ではSVG Text 0.8.0のlayout compositionとSVG overlayを使用します。画像portrait、lip-sync、continue indicator、または音声アセットを使う場合だけ、Asset Managerを追加でロードしてください。
|
|
458
499
|
|
|
459
500
|
```ts
|
|
460
501
|
import { createTurboWarpBubbleComposition } from "@kubohiroya/turbowarp-bubble/turbowarp-adapter";
|
|
@@ -485,7 +526,7 @@ const bubbles = createBubbleComposition({
|
|
|
485
526
|
});
|
|
486
527
|
```
|
|
487
528
|
|
|
488
|
-
`declare`部分はサンプルを短くするための型宣言です。実際のhostでは、`BubbleTextCapability`(文字
|
|
529
|
+
`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)`を使えます。
|
|
489
530
|
|
|
490
531
|
テキストだけを表示する場合は、Asset Managerのimport、`createAssetManagerComposition()`、`imageResolver`プロパティをすべて省略できます。Asset Managerは画像だけでなく、フルボイス、タイプライター音、行・段落ごとの効果音を登録・再生するためのメディア経路として利用します。音声付きBubble APIは表示機能と同じ名前付きアセットを使う設計にします。
|
|
491
532
|
|
|
@@ -493,7 +534,7 @@ const bubbles = createBubbleComposition({
|
|
|
493
534
|
|
|
494
535
|
surfaceは`updateStyle(style)`も実装し、吹き出しの位置・形状・サイズを更新できるようにします。表示中のBubbleのstyleを変更する場合は、返されたhandleの`updateStyle(style)`を呼び出します。更新後のstyleで画像レイヤーを使う場合、surfaceが対応するtargetをあらかじめ返している必要があります。
|
|
495
536
|
|
|
496
|
-
- `text`: `textCapability
|
|
537
|
+
- `text`: `textCapability`が文字layoutを適用するtarget
|
|
497
538
|
- `portraitBase`: キャラクター表情のベース画像target
|
|
498
539
|
- `portraitBlink`: 目パチ差分target
|
|
499
540
|
- `portraitLipSync`: 口パク差分target
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -2,6 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
The distributed JavaScript bundles include the following third-party software.
|
|
4
4
|
|
|
5
|
+
## @kubohiroya/turbowarp-svg-text
|
|
6
|
+
|
|
7
|
+
Repository: https://github.com/kubohiroya/turbowarp-svg-text
|
|
8
|
+
|
|
9
|
+
Copyright (c) Hiroya Kubo
|
|
10
|
+
|
|
11
|
+
This component is distributed under the Mozilla Public License 2.0. Its
|
|
12
|
+
source code is available from the repository above. The license text is
|
|
13
|
+
available at https://www.mozilla.org/MPL/2.0/.
|
|
14
|
+
|
|
5
15
|
## jsclipper
|
|
6
16
|
|
|
7
17
|
Repository: https://github.com/platener/jsclipper
|