@kubohiroya/turbowarp-bubble 0.9.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.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  `@kubohiroya/turbowarp-bubble` is an unsandboxed extension that manages TurboWarp `say` and `think` displays as separate text, character-expression, and input-waiting indicator layers. It also provides a composition API for using the same features directly from applications.
6
6
 
7
- The current release is Bubble 0.9.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.8.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. See the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles and TurboWarp-compatible basic bubbles.
7
+ The current release is Bubble 0.10.0. Its default rendering path is the skin-free SVG overlay backed by SVG Text 0.8.1. For the complete TurboWarp feature set, the currently recommended companion releases are Asset Manager 0.12.1, Async Input 0.4.0, and Runtime Expression 0.4.0. See the [0.10.0 release notes](docs/release-notes-0.10.0.md) for reusable named close policies and the [0.9.0 release notes](docs/release-notes-0.9.0.md) for the built-in `say`/`think` styles.
8
8
 
9
9
  ## How to read this README
10
10
 
@@ -34,7 +34,7 @@ flowchart LR
34
34
  wait --> close[Close and release resources]
35
35
  ```
36
36
 
37
- The table below maps the 0.9.0 feature set to its public entry points. The standalone extension exposes 29 palette blocks generated from 31 definitions; two hidden legacy definitions keep previously saved styled say/think blocks working. The full visible list appears under [Available blocks](#available-blocks).
37
+ The table below maps the 0.10.0 feature set to its public entry points. The standalone extension exposes 31 palette blocks generated from 33 definitions; two hidden legacy definitions keep previously saved styled say/think blocks working. The full visible list appears under [Available blocks](#available-blocks).
38
38
 
39
39
  | Area | What this README covers | Public entry points |
40
40
  | --------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
@@ -317,8 +317,8 @@ TurboWarp Bubble's `dist/turbowarp-bubble.js` is an **unsandboxed custom extensi
317
317
  1. For the input-wait example, open your project in the TurboWarp Editor and add Temporary Variables from the extension library.
318
318
  2. Select “Custom Extension” and enable Run without sandbox.
319
319
  3. Load Asset Manager 0.12.1 if you use portraits, blinking, lip-sync, continue frames, or audio.
320
- 4. Load Runtime Expression 0.4.0 for `finish [UNIT] ...`; load both Async Input 0.4.0 and Runtime Expression 0.4.0 for `wait with this bubble until condition ...`.
321
- 5. Load Bubble 0.9.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
320
+ 4. Load Runtime Expression 0.4.0 for `finish [UNIT] ...`; load both Async Input 0.4.0 and Runtime Expression 0.4.0 for condition-based waits and close policies. A timeout-only close policy needs neither extension.
321
+ 5. Load Bubble 0.10.0 last. The SVG Text 0.8.1 layout provider is included in the Bubble bundle.
322
322
 
323
323
  Bubble alone is the minimum configuration for text-only use. Temporary Variables, Asset Manager, Async Input, and Runtime Expression can be omitted when you do not use the features they support. After loading Bubble, its basic `say [MESSAGE]` and `think [MESSAGE]` blocks work immediately without a style definition. They select the built-in Bubble styles `say` and `think`, respectively. Each style binds its body shape and tail/trail shape as one visual choice, and both use the reserved text profile `default`. Use `define bubble style` and `show [MESSAGE] with bubble style [STYLE]` only when you need a named custom style. Other named text styles and every explicit body, placement, media, reveal, or motion setting select the custom profile.
324
324
 
@@ -326,14 +326,14 @@ Bubble alone is the minimum configuration for text-only use. Temporary Variables
326
326
  # Add only when using portraits, blink, lip-sync, continue, or audio
327
327
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
328
328
 
329
- # Add Async Input for the integrated wait block
329
+ # Add Async Input for integrated condition waits and close policies
330
330
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
331
331
 
332
- # Add Runtime Expression for finish or the integrated wait block
332
+ # Add Runtime Expression for finish or condition-based waits and close policies
333
333
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
334
334
 
335
335
  # Bubble (always load last)
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js
337
337
  ```
338
338
 
339
339
  TurboWarp custom extensions load JavaScript from URLs, so a network connection is required the first time they are loaded. For an unsandboxed development URL, TurboWarp requires the server origin to be exactly `http://localhost:8000/`; `127.0.0.1`, `0.0.0.0`, and other ports do not receive this exception. From the repository root, run `python3 -m http.server 8000`, then load `http://localhost:8000/dist/turbowarp-bubble.js`. Alternatively, choose the custom-extension file or text input and enable **Run extension without sandbox**. The extension does not work when opened directly with `file://` or when run as a sandboxed extension. See [TurboWarp's unsandboxed extension documentation](https://docs.turbowarp.org/development/extensions/unsandboxed) for the host restrictions.
@@ -360,6 +360,7 @@ Bubble owns a display for each calling sprite, clone, or Stage. With the default
360
360
  | Block | Behavior |
361
361
  | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
362
362
  | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Defines or replaces a Bubble style |
363
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | Defines or replaces a named closing condition |
363
364
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Sets an Actor-relative direction/angle or background-relative region |
364
365
  | `set portrait base [ASSET] for bubble style [STYLE]` | Sets the portrait base; an empty value removes the entire portrait |
365
366
  | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | Sets portrait placement, local transform, and rounded corners |
@@ -386,10 +387,25 @@ Bubble owns a display for each calling sprite, clone, or Stage. With the default
386
387
  | `show [MESSAGE] with bubble style [STYLE]` | Shows the body and tail/trail pair owned by the selected style |
387
388
  | `set this bubble animation mode [MODE]` | Selects `talking`, `awaiting-continue`, or `idle` |
388
389
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Waits for a Runtime Expression condition or optional timeout |
390
+ | `wait and close this bubble using close policy [POLICY]` | Snapshots a policy, waits for it, and closes the Bubble |
389
391
  | `close this bubble` | Releases this target's Bubble and owned resources |
390
392
  | `Bubble version` | Returns the implementation version |
391
393
 
392
- `ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and timeouts accept zero; a zero reveal interval disables automatic advance, while a zero timeout disables the time limit.
394
+ A Bubble close policy is control-flow configuration, not a visual Bubble style. `condition` waits without a time limit, `timeout` closes after a positive number of seconds, and `condition-or-timeout` closes when either trigger happens first. A condition must be non-empty, and an enabled timeout must be greater than zero.
395
+
396
+ ```text
397
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
398
+ say [This closes after three seconds.]
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 [Press a key or touch the sprite.]
403
+ wait and close this bubble using close policy [advance]
404
+ ```
405
+
406
+ The apply block snapshots the named definition when it starts. Replacing the same policy while it is waiting therefore affects only later applications. Timeout-only policies leave the Bubble in its current animation mode and require no input extension. Policies with a condition enter `awaiting-continue` and use Async Input plus Runtime Expression in the same way as the integrated wait block. Completion runs the configured hide animation and releases the Bubble. Replacing the Bubble, stopping its target or the project, or disposing the runtime cancels the pending policy without closing a replacement Bubble.
407
+
408
+ `ASSETS` is a comma-separated list of names registered with Asset Manager; surrounding whitespace is removed, and names cannot contain commas. Blink and lip-sync accept one or more frames, continue indicators require at least two, and an empty list removes the setting. Frame intervals must be finite and greater than zero. Reveal intervals, animation durations, and the legacy wait timeout accept zero; a zero reveal interval disables automatic advance, while a zero legacy timeout disables the time limit. A timeout selected explicitly by a close policy must be greater than zero.
393
409
 
394
410
  Bubble provides two built-in Bubble styles. `say` owns the speech body and speech tail; `think` owns the thought body and round trail. The body and tail/trail are one visual-style choice rather than independently selected properties. The matching short block selects each style automatically, so neither a style-definition block nor a style input is required. Both styles use the reserved text profile `default`: 14px Helvetica, 16px line height, a 170px maximum line width, 50px minimum text width, 10px padding, 16px corners, a white fill, and Scratch text/stroke colors. The 4px SVG stroke is painted before the white fill, which covers its inner half and leaves the same thin visible outline as TurboWarp's standard bubble. The profile starts on the Actor's right, flips to the left only when that side fits, follows Actor bounds, fences the Stage top and sides, formats numeric block inputs like Scratch, limits text to 330 characters, and closes on an empty block input.
395
411
 
package/README_ja.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  `@kubohiroya/turbowarp-bubble`は、TurboWarp上の`say`/`think`表示を、文字、キャラクター表情、入力待ちアイコンに分けて管理するunsandboxed機能拡張です。同じ機能をアプリから直接利用するためのcomposition APIも提供します。
6
6
 
7
- 現在のリリースはBubble 0.9.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です。組み込み`say`/`think` styleとTurboWarp互換の基本Bubbleについては[0.9.0 release notes](docs/release-notes-0.9.0.md)を参照してください。
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
8
 
9
9
  ## READMEの読み方
10
10
 
@@ -34,7 +34,7 @@ flowchart LR
34
34
  wait --> close[終了・resource解放]
35
35
  ```
36
36
 
37
- 次の表は0.9.0の機能と公開entry pointの対応です。standalone機能拡張は31定義から29個のpaletteブロックを公開し、保存済みprojectの互換性のため旧styled say/think 2定義を非表示で維持します。表示される全ブロックは[提供ブロック](#提供ブロック)に掲載しています。
37
+ 次の表は0.10.0の機能と公開entry pointの対応です。standalone機能拡張は33定義から31個のpaletteブロックを公開し、保存済みprojectの互換性のため旧styled say/think 2定義を非表示で維持します。表示される全ブロックは[提供ブロック](#提供ブロック)に掲載しています。
38
38
 
39
39
  | 領域 | このREADMEで説明する内容 | 公開entry point |
40
40
  | ----------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------ |
@@ -317,8 +317,8 @@ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget
317
317
  1. 入力待ちの例を使う場合は、TurboWarp Editorでプロジェクトを開き、拡張機能の追加からTemporary Variablesを追加します。
318
318
  2. 「カスタム拡張機能」を選び、サンドボックスなし(Run without sandbox)で実行できる状態にします。
319
319
  3. portrait、blink、lip-sync、continue frames、音声を使う場合はAsset Manager 0.12.1を読み込みます。
320
- 4. `finish [UNIT] ...`にはRuntime Expression 0.4.0、`wait with this bubble until condition ...`にはAsync Input 0.4.0とRuntime Expression 0.4.0を読み込みます。
321
- 5. 最後にBubble 0.9.0を読み込みます。SVG Text 0.8.1のlayout providerはBubble bundleに含まれます。
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
322
 
323
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
324
 
@@ -326,14 +326,14 @@ TurboWarp Bubbleの`dist/turbowarp-bubble.js`は、TurboWarpのrendererとtarget
326
326
  # portrait/blink/lip-sync/continue/音声を使う場合だけ追加
327
327
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js
328
328
 
329
- # 統合待機ブロックを使う場合はAsync Inputを追加
329
+ # conditionを使う統合待機またはclose policyでAsync Inputを追加
330
330
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js
331
331
 
332
- # finishまたは統合待機ブロックを使う場合はRuntime Expressionを追加
332
+ # finishまたはconditionを使う待機/close policyでRuntime Expressionを追加
333
333
  https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js
334
334
 
335
335
  # Bubble(必ず最後)
336
- https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js
336
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js
337
337
  ```
338
338
 
339
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)を参照してください。
@@ -360,6 +360,7 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
360
360
  | ブロック | 動作 |
361
361
  | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
362
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` | 名前付きの終了条件を定義または置換する |
363
364
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
364
365
  | `set portrait base [ASSET] for bubble style [STYLE]` | portraitベースを設定する。空値でportrait全体を解除する |
365
366
  | `set portrait [PLACEMENT] offset x [X] y [Y] zoom [ZOOM] % corner radius [RADIUS] px for bubble style [STYLE]` | portraitの配置、局所変形、角丸を設定する |
@@ -386,10 +387,25 @@ Bubbleは呼び出し元のsprite、clone、またはStageごとに表示を所
386
387
  | `show [MESSAGE] with bubble style [STYLE]` | 選択styleが持つ本体+tail/trailの組を表示する |
387
388
  | `set this bubble animation mode [MODE]` | `talking`/`awaiting-continue`/`idle`を選択する |
388
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を閉じる |
389
391
  | `close this bubble` | 呼び出し元のBubbleと所有resourceを解放する |
390
392
  | `Bubble version` | 実装versionを返す |
391
393
 
392
- `ASSETS`はAsset Managerへ登録済みの名前をカンマ区切りで指定します。前後の空白は除去され、名前自体にカンマは使用できません。目パチと口パクは1フレーム以上、continue indicatorは2フレーム以上が必要で、空リストにすると設定を解除します。frame間隔は0より大きい有限値です。逐次表示間隔、animation時間、timeoutには0も指定でき、逐次表示間隔の0は自動送りを、timeoutの0は時間制限を無効にします。
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より大きい値にします。
393
409
 
394
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`に揃えます。
395
411
 
@@ -37,6 +37,29 @@
37
37
  "blockType": "COMMAND",
38
38
  "arguments": []
39
39
  },
40
+ {
41
+ "opcode": "defineBubbleClosePolicy",
42
+ "blockType": "COMMAND",
43
+ "arguments": [
44
+ {
45
+ "id": "CONDITION",
46
+ "type": "STRING"
47
+ },
48
+ {
49
+ "id": "POLICY",
50
+ "type": "STRING"
51
+ },
52
+ {
53
+ "id": "TIMEOUT",
54
+ "type": "NUMBER"
55
+ },
56
+ {
57
+ "id": "TRIGGER",
58
+ "type": "STRING",
59
+ "menu": "closePolicyTrigger"
60
+ }
61
+ ]
62
+ },
40
63
  {
41
64
  "opcode": "defineBubbleStyle",
42
65
  "blockType": "COMMAND",
@@ -474,6 +497,16 @@
474
497
  }
475
498
  ]
476
499
  },
500
+ {
501
+ "opcode": "waitAndCloseBubbleWithPolicy",
502
+ "blockType": "COMMAND",
503
+ "arguments": [
504
+ {
505
+ "id": "POLICY",
506
+ "type": "STRING"
507
+ }
508
+ ]
509
+ },
477
510
  {
478
511
  "opcode": "waitForBubbleContinue",
479
512
  "blockType": "COMMAND",
@@ -498,6 +531,10 @@
498
531
  "id": "boolean",
499
532
  "acceptReporters": true
500
533
  },
534
+ {
535
+ "id": "closePolicyTrigger",
536
+ "acceptReporters": true
537
+ },
501
538
  {
502
539
  "id": "ease",
503
540
  "acceptReporters": true
@@ -59,6 +59,31 @@
59
59
  }
60
60
  }
61
61
  },
62
+ {
63
+ "opcode": "defineBubbleClosePolicy",
64
+ "blockType": "COMMAND",
65
+ "text": "define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds",
66
+ "description": "Defines or replaces a named close policy. The trigger explicitly selects a condition, a timeout, or whichever happens first.",
67
+ "arguments": {
68
+ "POLICY": {
69
+ "type": "STRING",
70
+ "defaultValue": "advance-or-timeout"
71
+ },
72
+ "TRIGGER": {
73
+ "type": "STRING",
74
+ "defaultValue": "condition-or-timeout",
75
+ "menu": "closePolicyTrigger"
76
+ },
77
+ "CONDITION": {
78
+ "type": "STRING",
79
+ "defaultValue": "input == \"pressed\""
80
+ },
81
+ "TIMEOUT": {
82
+ "type": "NUMBER",
83
+ "defaultValue": 10
84
+ }
85
+ }
86
+ },
62
87
  {
63
88
  "opcode": "setBubblePlacement",
64
89
  "blockType": "COMMAND",
@@ -571,6 +596,16 @@
571
596
  }
572
597
  }
573
598
  },
599
+ {
600
+ "opcode": "waitAndCloseBubbleWithPolicy",
601
+ "blockType": "COMMAND",
602
+ "text": "wait and close this bubble using close policy [POLICY]",
603
+ "description": "Snapshots the named close policy, waits for its trigger, then closes this sprite's bubble and releases its resources.",
604
+ "arguments": { "POLICY": {
605
+ "type": "STRING",
606
+ "defaultValue": "advance-or-timeout"
607
+ } }
608
+ },
574
609
  {
575
610
  "opcode": "closeBubble",
576
611
  "blockType": "COMMAND",
@@ -587,6 +622,14 @@
587
622
  }
588
623
  ],
589
624
  menus: {
625
+ "closePolicyTrigger": {
626
+ "acceptReporters": true,
627
+ "items": [
628
+ "condition",
629
+ "timeout",
630
+ "condition-or-timeout"
631
+ ]
632
+ },
590
633
  "portraitPlacement": {
591
634
  "acceptReporters": true,
592
635
  "items": [
@@ -12468,6 +12511,11 @@
12468
12511
  "talking",
12469
12512
  "awaiting-continue"
12470
12513
  ]);
12514
+ var validClosePolicyTriggers = /* @__PURE__ */ new Set([
12515
+ "condition",
12516
+ "timeout",
12517
+ "condition-or-timeout"
12518
+ ]);
12471
12519
  var validRevealUnits = /* @__PURE__ */ new Set([
12472
12520
  "CHARACTER",
12473
12521
  "WORD",
@@ -12507,7 +12555,7 @@
12507
12555
  textStyle: "default"
12508
12556
  })]);
12509
12557
  var EXTENSION_DOCS_URI = "https://kubohiroya.github.io/turbowarp-bubble/";
12510
- var EXTENSION_VERSION = "0.9.0";
12558
+ var EXTENSION_VERSION = "0.10.0";
12511
12559
  var BLOCK_ICON_URI = `data:image/svg+xml,${encodeURIComponent("<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\"><path fill=\"none\" stroke=\"#fff\" stroke-width=\"5\" stroke-linecap=\"round\" stroke-linejoin=\"round\" d=\"M12 13h40a5 5 0 0 1 5 5v23a5 5 0 0 1-5 5H30L17 55v-9h-5a5 5 0 0 1-5-5V18a5 5 0 0 1 5-5Z\"/><g fill=\"#fff\"><circle cx=\"23\" cy=\"30\" r=\"3\"/><circle cx=\"32\" cy=\"30\" r=\"3\"/><circle cx=\"41\" cy=\"30\" r=\"3\"/></g></svg>")}`;
12512
12560
  function extensionError(message) {
12513
12561
  const error = /* @__PURE__ */ new Error(`[Bubble] ${message}`);
@@ -12519,6 +12567,7 @@
12519
12567
  _defineProperty(this, "runtime", void 0);
12520
12568
  _defineProperty(this, "options", void 0);
12521
12569
  _defineProperty(this, "styles", new Map(builtInBubbleStyles.map((style) => [style.name, style])));
12570
+ _defineProperty(this, "closePolicies", /* @__PURE__ */ new Map());
12522
12571
  _defineProperty(this, "handles", /* @__PURE__ */ new Map());
12523
12572
  _defineProperty(this, "waits", /* @__PURE__ */ new Map());
12524
12573
  _defineProperty(this, "waitScheduler", void 0);
@@ -12565,6 +12614,23 @@
12565
12614
  });
12566
12615
  this.installStyle(style);
12567
12616
  }
12617
+ defineBubbleClosePolicy(args) {
12618
+ const name = this.requireName(args.POLICY, "close policy");
12619
+ const trigger = this.toString(args.TRIGGER).trim().toLowerCase();
12620
+ if (!validClosePolicyTriggers.has(trigger)) throw extensionError("close policy trigger must be condition, timeout, or condition-or-timeout.");
12621
+ const usesCondition = trigger !== "timeout";
12622
+ const usesTimeout = trigger !== "condition";
12623
+ const condition = usesCondition ? this.toString(args.CONDITION).trim() : void 0;
12624
+ if (usesCondition && !condition) throw extensionError("close policy condition is empty.");
12625
+ const timeoutSeconds = usesTimeout ? Scratch.Cast.toNumber(args.TIMEOUT) : void 0;
12626
+ if (usesTimeout && (!Number.isFinite(timeoutSeconds) || Number(timeoutSeconds) <= 0)) throw extensionError("close policy timeout must be greater than zero when enabled.");
12627
+ this.closePolicies.set(name, Object.freeze({
12628
+ name,
12629
+ trigger,
12630
+ ...condition === void 0 ? {} : { condition },
12631
+ ...timeoutSeconds === void 0 ? {} : { timeoutSeconds: Number(timeoutSeconds) }
12632
+ }));
12633
+ }
12568
12634
  setPortraitBase(args) {
12569
12635
  const style = this.requireStyle(args.STYLE);
12570
12636
  const base = this.toString(args.ASSET).trim();
@@ -12869,43 +12935,33 @@
12869
12935
  if (!condition) throw extensionError("wait condition is empty.");
12870
12936
  const timeoutSeconds = Scratch.Cast.toNumber(args.TIMEOUT);
12871
12937
  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 0) throw extensionError("wait timeout must be zero or greater.");
12872
- if (!this.isRecord(this.runtime.ext_kubohiroyaasyncinput)) throw extensionError("Bubble wait requires Async Input. Load @kubohiroya/turbowarp-async-input before using this block.");
12873
- const runtimeExpression = this.runtime.ext_kubohiroyaruntimeexpression;
12874
- if (!this.isRecord(runtimeExpression) || typeof runtimeExpression.runtimeCondition !== "function") throw extensionError("Bubble wait requires Runtime Expression. Load @kubohiroya/turbowarp-runtime-expression before using this block.");
12875
- if (typeof this.runtime.on !== "function" || typeof this.runtime.off !== "function") throw extensionError("TurboWarp runtime events are unavailable.");
12876
- this.cancelWait(target.id, "Bubble wait was replaced.");
12877
- await handle.setAnimationMode("awaiting-continue");
12878
- await new Promise((resolve, reject) => {
12879
- let settled = false;
12880
- let timeoutHandle;
12881
- const cleanup = () => {
12882
- this.runtime.off?.("BEFORE_EXECUTE", checkCondition);
12883
- if (timeoutHandle !== void 0) this.waitScheduler.clearTimeout(timeoutHandle);
12884
- if (this.waits.get(target.id) === pending) this.waits.delete(target.id);
12885
- };
12886
- const finish = (error) => {
12887
- if (settled) return;
12888
- settled = true;
12889
- cleanup();
12890
- if (error) {
12891
- reject(error);
12892
- return;
12893
- }
12894
- handle.setAnimationMode("idle").then(resolve, reject);
12895
- };
12896
- const checkCondition = () => {
12897
- try {
12898
- if (runtimeExpression.runtimeCondition({ EXPRESSION: condition })) finish();
12899
- } catch (error) {
12900
- finish(error instanceof Error ? error : extensionError("wait condition evaluation failed."));
12901
- }
12902
- };
12903
- const pending = Object.freeze({ cancel: finish });
12904
- this.waits.set(target.id, pending);
12905
- this.runtime.on?.("BEFORE_EXECUTE", checkCondition);
12906
- if (timeoutSeconds > 0) timeoutHandle = this.waitScheduler.setTimeout(() => finish(), timeoutSeconds * 1e3);
12907
- checkCondition();
12938
+ await this.waitForBubbleTrigger({
12939
+ targetId: target.id,
12940
+ handle,
12941
+ condition,
12942
+ ...timeoutSeconds === 0 ? {} : { timeoutSeconds },
12943
+ setAwaitingContinue: true,
12944
+ restoreIdle: true,
12945
+ requireAsyncInput: true
12946
+ });
12947
+ }
12948
+ async waitAndCloseBubbleWithPolicy(args, util) {
12949
+ const target = this.requireTarget(util);
12950
+ const handle = this.handles.get(target.id);
12951
+ if (!handle) throw extensionError("this target does not have an active bubble.");
12952
+ const policy = this.requireClosePolicy(args.POLICY);
12953
+ const usesCondition = policy.condition !== void 0;
12954
+ await this.waitForBubbleTrigger({
12955
+ targetId: target.id,
12956
+ handle,
12957
+ ...policy.condition === void 0 ? {} : { condition: policy.condition },
12958
+ ...policy.timeoutSeconds === void 0 ? {} : { timeoutSeconds: policy.timeoutSeconds },
12959
+ setAwaitingContinue: usesCondition,
12960
+ restoreIdle: false,
12961
+ requireAsyncInput: usesCondition
12908
12962
  });
12963
+ if (this.handles.get(target.id) !== handle) throw this.abortError("Bubble was replaced before it could close.");
12964
+ await this.releaseOwnedTarget(target.id);
12909
12965
  }
12910
12966
  async finishBubbleReveal(args, util) {
12911
12967
  const handle = this.requireHandle(util);
@@ -12943,6 +12999,56 @@
12943
12999
  if (this.composition) await this.composition.dispose();
12944
13000
  this.handles.clear();
12945
13001
  this.styles.clear();
13002
+ this.closePolicies.clear();
13003
+ }
13004
+ async waitForBubbleTrigger(input) {
13005
+ let runtimeExpression;
13006
+ if (input.condition !== void 0) {
13007
+ if (input.requireAsyncInput && !this.isRecord(this.runtime.ext_kubohiroyaasyncinput)) throw extensionError("Bubble wait requires Async Input. Load @kubohiroya/turbowarp-async-input before using this block.");
13008
+ const candidate = this.runtime.ext_kubohiroyaruntimeexpression;
13009
+ if (!this.isRecord(candidate) || typeof candidate.runtimeCondition !== "function") throw extensionError("Bubble wait requires Runtime Expression. Load @kubohiroya/turbowarp-runtime-expression before using this block.");
13010
+ if (typeof this.runtime.on !== "function" || typeof this.runtime.off !== "function") throw extensionError("TurboWarp runtime events are unavailable.");
13011
+ runtimeExpression = candidate;
13012
+ }
13013
+ if (input.condition === void 0 && input.timeoutSeconds === void 0) throw extensionError("Bubble wait does not have an enabled trigger.");
13014
+ this.cancelWait(input.targetId, "Bubble wait was replaced.");
13015
+ if (input.setAwaitingContinue) await input.handle.setAnimationMode("awaiting-continue");
13016
+ await new Promise((resolve, reject) => {
13017
+ let settled = false;
13018
+ let timeoutHandle;
13019
+ const checkCondition = () => {
13020
+ if (input.condition === void 0 || runtimeExpression === void 0) return;
13021
+ try {
13022
+ if (runtimeExpression.runtimeCondition({ EXPRESSION: input.condition })) finish();
13023
+ } catch (error) {
13024
+ finish(error instanceof Error ? error : extensionError("wait condition evaluation failed."));
13025
+ }
13026
+ };
13027
+ const cleanup = () => {
13028
+ if (input.condition !== void 0) this.runtime.off?.("BEFORE_EXECUTE", checkCondition);
13029
+ if (timeoutHandle !== void 0) this.waitScheduler.clearTimeout(timeoutHandle);
13030
+ if (this.waits.get(input.targetId) === pending) this.waits.delete(input.targetId);
13031
+ };
13032
+ const finish = (error) => {
13033
+ if (settled) return;
13034
+ settled = true;
13035
+ cleanup();
13036
+ if (error) {
13037
+ reject(error);
13038
+ return;
13039
+ }
13040
+ if (!input.restoreIdle) {
13041
+ resolve();
13042
+ return;
13043
+ }
13044
+ input.handle.setAnimationMode("idle").then(resolve, reject);
13045
+ };
13046
+ const pending = Object.freeze({ cancel: finish });
13047
+ this.waits.set(input.targetId, pending);
13048
+ if (input.condition !== void 0) this.runtime.on?.("BEFORE_EXECUTE", checkCondition);
13049
+ if (input.timeoutSeconds !== void 0) timeoutHandle = this.waitScheduler.setTimeout(() => finish(), input.timeoutSeconds * 1e3);
13050
+ checkCondition();
13051
+ });
12946
13052
  }
12947
13053
  toScratchBlock(block) {
12948
13054
  return {
@@ -12985,6 +13091,12 @@
12985
13091
  if (!style) throw extensionError(`bubble style is not defined: ${name}`);
12986
13092
  return style;
12987
13093
  }
13094
+ requireClosePolicy(value) {
13095
+ const name = this.requireName(value, "close policy");
13096
+ const policy = this.closePolicies.get(name);
13097
+ if (!policy) throw extensionError(`bubble close policy is not defined: ${name}`);
13098
+ return policy;
13099
+ }
12988
13100
  normalizeTransformNumber(value, normalize) {
12989
13101
  try {
12990
13102
  return normalize(Scratch.Cast.toNumber(value));
@@ -8,7 +8,7 @@
8
8
 
9
9
  ## 1. 必要な拡張機能
10
10
 
11
- 入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.1のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。
11
+ 入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.1のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime Expressionはconditionを使うBubble待機またはclose policyで必要です。timeoutだけのclose policyにはどちらも不要です。
12
12
 
13
13
  | 順番 | 拡張機能 | 読み込み先 |
14
14
  | ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
@@ -16,9 +16,9 @@
16
16
  | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
17
17
  | 3 | Runtime Expression 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js` |
18
18
  | 4 | Asset Manager 0.12.1 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js` |
19
- | 5 | Bubble 0.9.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js` |
19
+ | 5 | Bubble 0.10.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js` |
20
20
 
21
- 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、待機開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。
21
+ 開発中のBubbleを試す場合は、このリポジトリの`dist/turbowarp-bubble.js`をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、condition待機の開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。
22
22
 
23
23
  参考:
24
24
 
@@ -221,6 +221,16 @@ close this bubble
221
221
 
222
222
  次の待機に入る前に`input`を空文字へ戻してください。前回の`pressed`が残っていると、次の条件が直ちに成立します。別のBubble表示、close、対象targetの停止、projectの開始・停止、runtime破棄では、targetが所有する待機とlistener、timerをキャンセルして解放します。
223
223
 
224
+ 同じ終了規則を再利用する場合は、名前付きBubble close policyを使います。triggerは`condition`、`timeout`、`condition-or-timeout`から明示的に選びます。policyの適用は定義をsnapshotし、成立まで待ち、Bubbleのhide animationと解放までを1つの待機commandとして実行します。
225
+
226
+ ```text
227
+ define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == "pressed"] timeout [10] seconds
228
+ show [海へ出発!] with bubble style [hero-dialogue]
229
+ wait and close this bubble using close policy [advance-or-timeout]
230
+ ```
231
+
232
+ timeoutだけのpolicyは現在のanimation modeを変えず、入力用拡張を必要としません。conditionを含むpolicyは`awaiting-continue`へ移り、既存の統合待機と同じAsync Input/Runtime Expression設定を使います。待機中に同じ名前を再定義しても、変更は次回の適用から有効です。Bubbleの置換やlifecycle cleanupは待機中policyをcancelし、置換後のBubbleを閉じません。
233
+
224
234
  音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点で`awaiting-continue`へ切り替えます。
225
235
 
226
236
  ![sayで口パクし、awaiting-continueでcontinue framesを動かし、入力成立後にBubbleを閉じるアニメーション](./assets/bubble-lifecycle.gif)
@@ -281,6 +291,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、over
281
291
  | ブロック | 説明 |
282
292
  | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
283
293
  | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Bubble styleを定義または再定義する |
294
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | 名前付きの終了条件を定義または置換する |
284
295
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Actor相対方向・角度、または背景相対領域を設定する |
285
296
  | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Actor boundsからtail先端までの距離を設定する |
286
297
  | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | 不可分なSVG本体+tail/trailの組を10種類から設定する |
@@ -307,6 +318,7 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、over
307
318
  | `show [MESSAGE] with bubble style [STYLE]` | styleが持つ本体+tail/trailの一組を表示する |
308
319
  | `set this bubble animation mode [MODE]` | `talking`、`awaiting-continue`、`idle`からmodeを選ぶ |
309
320
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Runtime Expressionの条件成立またはtimeoutまで待つ |
321
+ | `wait and close this bubble using close policy [POLICY]` | policyをsnapshotし、成立を待ってBubbleを閉じる |
310
322
  | `close this bubble` | 自分のBubbleと所有resourceを解放する |
311
323
  | `Bubble version` | Bubble実装versionを返す |
312
324
 
@@ -314,20 +326,21 @@ cloneが停止・削除された場合は、そのtargetに属するtimer、over
314
326
 
315
327
  ## 12. よくあるエラー
316
328
 
317
- | 状況 | 原因と対処 |
318
- | ---------------------------------- | ------------------------------------------------------------------------ |
319
- | Asset Managerを要求するエラー | 画像・メディアアセットを使う前にAsset Manager 0.12.xを読み込む |
320
- | SVG overlay backendのエラー | `renderer.addOverlay()`対応hostを使うか`scratch-render`を明示する |
321
- | Async Inputを要求するエラー | Bubble待機より前にAsync Input 0.3.xをサンドボックスなしで読み込む |
322
- | Runtime Expressionを要求するエラー | Bubble待機より前にRuntime Expression 0.3.xをサンドボックスなしで読み込む |
323
- | `bubble style is not defined` | 組み込みの短いsay/thinkを使うか、named custom styleを先に定義する |
324
- | image assetが未登録 | `register resource ... as asset ...`の完了後にBubbleを表示する |
325
- | assetが画像ではない | `MIME type of asset [NAME]`で`image/*`か確認する |
326
- | continue framesが1枚 | 2枚以上にするか、空にしてcontinue表示を解除する |
327
- | frame intervalエラー | `SECONDS`を0より大きい有限値にする |
328
- | StageからActor相対表示した | placementを`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`にする |
329
- | placementが不正 | 16方向、alias、0〜360度、背景相対3値のいずれかを指定する |
330
- | 目や口がずれる | ベースと全差分のcanvasサイズ、中心、透明領域を揃える |
329
+ | 状況 | 原因と対処 |
330
+ | ------------------------------------ | ------------------------------------------------------------------------ |
331
+ | Asset Managerを要求するエラー | 画像・メディアアセットを使う前にAsset Manager 0.12.xを読み込む |
332
+ | SVG overlay backendのエラー | `renderer.addOverlay()`対応hostを使うか`scratch-render`を明示する |
333
+ | Async Inputを要求するエラー | Bubble待機より前にAsync Input 0.3.xをサンドボックスなしで読み込む |
334
+ | Runtime Expressionを要求するエラー | Bubble待機より前にRuntime Expression 0.3.xをサンドボックスなしで読み込む |
335
+ | `bubble style is not defined` | 組み込みの短いsay/thinkを使うか、named custom styleを先に定義する |
336
+ | `bubble close policy is not defined` | 名前付きclose policyを適用前に定義する |
337
+ | image assetが未登録 | `register resource ... as asset ...`の完了後にBubbleを表示する |
338
+ | assetが画像ではない | `MIME type of asset [NAME]`で`image/*`か確認する |
339
+ | continue framesが1枚 | 2枚以上にするか、空にしてcontinue表示を解除する |
340
+ | frame intervalエラー | `SECONDS`を0より大きい有限値にする |
341
+ | StageからActor相対表示した | placementを`HEADER_LIKE`、`CENTER`、`FOOTER_LIKE`にする |
342
+ | placementが不正 | 16方向、alias、0〜360度、背景相対3値のいずれかを指定する |
343
+ | 目や口がずれる | ベースと全差分のcanvasサイズ、中心、透明領域を揃える |
331
344
 
332
345
  ## 13. 自動解放されるタイミング
333
346
 
@@ -8,7 +8,7 @@ This manual explains how to use `turbowarp-bubble` as an unsandboxed TurboWarp c
8
8
 
9
9
  ## 1. Load the required extensions
10
10
 
11
- The complete input-wait example uses five extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. Bubble bundles the host-neutral SVG Text 0.8.1 layout provider and creates no text skin on its default SVG overlay. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.
11
+ The complete input-wait example uses five extensions. Add Temporary Variables from TurboWarp's extension library, then load the custom extensions needed by the selected features with **Run without sandbox** enabled. Bubble bundles the host-neutral SVG Text 0.8.1 layout provider and creates no text skin on its default SVG overlay. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only for condition-based Bubble waits and close policies; a timeout-only close policy needs neither.
12
12
 
13
13
  | Order | Extension | URL |
14
14
  | ----: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
@@ -16,9 +16,9 @@ The complete input-wait example uses five extensions. Add Temporary Variables fr
16
16
  | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
17
17
  | 3 | Runtime Expression 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-runtime-expression@0.4.0/dist/runtime-expression.js` |
18
18
  | 4 | Asset Manager 0.12.1 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js` |
19
- | 5 | Bubble 0.9.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js` |
19
+ | 5 | Bubble 0.10.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js` |
20
20
 
21
- To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if the renderer lacks the default SVG overlay APIs, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait. The lower-level Composition API can inject another text capability.
21
+ To try a development build, load this repository's `dist/turbowarp-bubble.js` as a local custom extension. Bubble reports an explicit error if the renderer lacks the default SVG overlay APIs, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a condition-based Bubble wait. The lower-level Composition API can inject another text capability.
22
22
 
23
23
  See also:
24
24
 
@@ -221,6 +221,16 @@ Initialize `input` with Temporary Variables before registering the Async Input l
221
221
 
222
222
  Reset `input` to an empty string before each later wait; otherwise the previous `pressed` value makes the next condition succeed immediately. Starting another Bubble, closing it, stopping its target, restarting or stopping the project, and disposing the runtime all cancel the target-owned wait and release its listener and timer.
223
223
 
224
+ Use a named Bubble close policy when the same closing rule is reused. The trigger is explicit: `condition`, `timeout`, or `condition-or-timeout`. Applying a policy snapshots its definition, waits, runs the Bubble's hide animation, and releases the Bubble in one blocking command.
225
+
226
+ ```text
227
+ define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == "pressed"] timeout [10] seconds
228
+ show [Let's head for the sea!] with bubble style [hero-dialogue]
229
+ wait and close this bubble using close policy [advance-or-timeout]
230
+ ```
231
+
232
+ A timeout-only policy leaves the current animation mode unchanged and needs no input extension. A policy containing a condition enters `awaiting-continue` and uses the same Async Input and Runtime Expression setup as the integrated wait. Redefining the same name during a pending wait affects only later applications. Bubble replacement or lifecycle cleanup cancels the pending policy and does not close the replacement Bubble.
233
+
224
234
  When combining Bubble with audio or a separate text-reveal system, switch to `awaiting-continue` when that process completes.
225
235
 
226
236
  ![A say Bubble lip-syncs, shows continue frames while awaiting continue, then closes after input](./assets/bubble-lifecycle.gif)
@@ -281,6 +291,7 @@ When a clone stops or is deleted, its timers, overlay DOM, and image leases are
281
291
  | Block | Description |
282
292
  | -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
283
293
  | `define bubble style [STYLE] using text style [TEXT_STYLE]` | Define or redefine a Bubble style |
294
+ | `define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds` | Define or replace a named closing condition |
284
295
  | `set bubble placement [PLACEMENT] for bubble style [STYLE]` | Set an actor direction/angle or a stage-relative region |
285
296
  | `set bubble distance [DISTANCE] for bubble style [STYLE]` | Set the distance from actor bounds to the tail tip |
286
297
  | `set bubble visual style [VISUAL_STYLE] for bubble style [STYLE]` | Select one of ten inseparable SVG body + tail/trail pairs |
@@ -307,6 +318,7 @@ When a clone stops or is deleted, its timers, overlay DOM, and image leases are
307
318
  | `show [MESSAGE] with bubble style [STYLE]` | Show the complete body and tail/trail pair owned by a style |
308
319
  | `set this bubble animation mode [MODE]` | Select `talking`, `awaiting-continue`, or `idle` for this Bubble |
309
320
  | `wait with this bubble until condition [CONDITION] or timeout after [TIMEOUT] seconds` | Await a Runtime Expression condition or optional timeout |
321
+ | `wait and close this bubble using close policy [POLICY]` | Snapshot a policy, wait for it, and close the Bubble |
310
322
  | `close this bubble` | Release this target's Bubble and owned resources |
311
323
  | `Bubble version` | Report the Bubble implementation version |
312
324
 
@@ -321,6 +333,7 @@ Saved projects using the former `say/think [MESSAGE] with bubble style [STYLE]`
321
333
  | Async Input required error | Load Async Input 0.3.x without sandbox before using the Bubble wait |
322
334
  | Runtime Expression required error | Load Runtime Expression 0.3.x without sandbox before using the Bubble wait |
323
335
  | `bubble style is not defined` | Use the built-in short say/think blocks, or define the named custom style first |
336
+ | `bubble close policy is not defined` | Define the named close policy before applying it |
324
337
  | Image asset is not registered | Wait for `register resource ... as asset ...` before showing the Bubble |
325
338
  | Asset is not an image | Confirm `MIME type of asset [NAME]` is `image/*` |
326
339
  | Only one continue frame | Supply at least two frames, or clear the setting |
package/docs/index.html CHANGED
@@ -74,7 +74,7 @@
74
74
  </blockquote>
75
75
  <p><img src="./assets/block-quick-start.svg" alt="A quick-start block sequence that registers Next1 and Next2 separately, prepares input listeners, then uses Bubble&#39;s integrated wait"></p>
76
76
  <h2 id="requirements">1. Load the required extensions</h2>
77
- <p>The complete input-wait example uses five extensions. Add Temporary Variables from TurboWarp&#39;s extension library, then load the custom extensions needed by the selected features with <strong>Run without sandbox</strong> enabled. Bubble bundles the host-neutral SVG Text 0.8.1 layout provider and creates no text skin on its default SVG overlay. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only before using a Bubble wait.</p>
77
+ <p>The complete input-wait example uses five extensions. Add Temporary Variables from TurboWarp&#39;s extension library, then load the custom extensions needed by the selected features with <strong>Run without sandbox</strong> enabled. Bubble bundles the host-neutral SVG Text 0.8.1 layout provider and creates no text skin on its default SVG overlay. Asset Manager is required for portrait, lip-sync, continue indicator, voice, and display-sound assets. Async Input and Runtime Expression are required only for condition-based Bubble waits and close policies; a timeout-only close policy needs neither.</p>
78
78
  <table>
79
79
  <thead>
80
80
  <tr>
@@ -105,11 +105,11 @@
105
105
  </tr>
106
106
  <tr>
107
107
  <td align="right">5</td>
108
- <td>Bubble 0.9.0</td>
109
- <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js</code></td>
108
+ <td>Bubble 0.10.0</td>
109
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js</code></td>
110
110
  </tr>
111
111
  </tbody></table>
112
- <p>To try a development build, load this repository&#39;s <code>dist/turbowarp-bubble.js</code> as a local custom extension. Bubble reports an explicit error if the renderer lacks the default SVG overlay APIs, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a Bubble wait. The lower-level Composition API can inject another text capability.</p>
112
+ <p>To try a development build, load this repository&#39;s <code>dist/turbowarp-bubble.js</code> as a local custom extension. Bubble reports an explicit error if the renderer lacks the default SVG overlay APIs, if an image/media feature is used without Asset Manager, or if Async Input or Runtime Expression is missing when it starts a condition-based Bubble wait. The lower-level Composition API can inject another text capability.</p>
113
113
  <p>See also:</p>
114
114
  <ul>
115
115
  <li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/">Asset Manager guide</a></li>
@@ -296,6 +296,12 @@ close this bubble
296
296
  </code></pre>
297
297
  <p>Initialize <code>input</code> with Temporary Variables before registering the Async Input listeners. The listeners update that runtime variable when Space is pressed or the sprite is tapped. The Bubble wait delegates <code>input == &quot;pressed&quot;</code> to Runtime Expression immediately and once per VM frame. While waiting it automatically enters <code>awaiting-continue</code>, stops lip-sync, and loops the images configured by <code>set continue frames</code>. When the condition becomes true or the timeout expires, it enters <code>idle</code> and continues to <code>close this bubble</code>. Set the timeout to <code>0</code> to wait without a timeout.</p>
298
298
  <p>Reset <code>input</code> to an empty string before each later wait; otherwise the previous <code>pressed</code> value makes the next condition succeed immediately. Starting another Bubble, closing it, stopping its target, restarting or stopping the project, and disposing the runtime all cancel the target-owned wait and release its listener and timer.</p>
299
+ <p>Use a named Bubble close policy when the same closing rule is reused. The trigger is explicit: <code>condition</code>, <code>timeout</code>, or <code>condition-or-timeout</code>. Applying a policy snapshots its definition, waits, runs the Bubble&#39;s hide animation, and releases the Bubble in one blocking command.</p>
300
+ <pre><code class="language-text">define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == &quot;pressed&quot;] timeout [10] seconds
301
+ show [Let&#39;s head for the sea!] with bubble style [hero-dialogue]
302
+ wait and close this bubble using close policy [advance-or-timeout]
303
+ </code></pre>
304
+ <p>A timeout-only policy leaves the current animation mode unchanged and needs no input extension. A policy containing a condition enters <code>awaiting-continue</code> and uses the same Async Input and Runtime Expression setup as the integrated wait. Redefining the same name during a pending wait affects only later applications. Bubble replacement or lifecycle cleanup cancels the pending policy and does not close the replacement Bubble.</p>
299
305
  <p>When combining Bubble with audio or a separate text-reveal system, switch to <code>awaiting-continue</code> when that process completes.</p>
300
306
  <p><img src="./assets/bubble-lifecycle.gif" alt="A say Bubble lip-syncs, shows continue frames while awaiting continue, then closes after input"></p>
301
307
  <p>If animated GIF playback is unavailable, use this static animation-mode comparison:</p>
@@ -371,6 +377,10 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
371
377
  <td>Define or redefine a Bubble style</td>
372
378
  </tr>
373
379
  <tr>
380
+ <td><code>define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds</code></td>
381
+ <td>Define or replace a named closing condition</td>
382
+ </tr>
383
+ <tr>
374
384
  <td><code>set bubble placement [PLACEMENT] for bubble style [STYLE]</code></td>
375
385
  <td>Set an actor direction/angle or a stage-relative region</td>
376
386
  </tr>
@@ -475,6 +485,10 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
475
485
  <td>Await a Runtime Expression condition or optional timeout</td>
476
486
  </tr>
477
487
  <tr>
488
+ <td><code>wait and close this bubble using close policy [POLICY]</code></td>
489
+ <td>Snapshot a policy, wait for it, and close the Bubble</td>
490
+ </tr>
491
+ <tr>
478
492
  <td><code>close this bubble</code></td>
479
493
  <td>Release this target&#39;s Bubble and owned resources</td>
480
494
  </tr>
@@ -513,6 +527,10 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
513
527
  <td>Use the built-in short say/think blocks, or define the named custom style first</td>
514
528
  </tr>
515
529
  <tr>
530
+ <td><code>bubble close policy is not defined</code></td>
531
+ <td>Define the named close policy before applying it</td>
532
+ </tr>
533
+ <tr>
516
534
  <td>Image asset is not registered</td>
517
535
  <td>Wait for <code>register resource ... as asset ...</code> before showing the Bubble</td>
518
536
  </tr>
@@ -74,7 +74,7 @@
74
74
  </blockquote>
75
75
  <p><img src="../assets/block-quick-start.svg" alt="Next1とNext2を個別登録し、入力listenerを準備してBubble内蔵待機を使うブロック例"></p>
76
76
  <h2 id="requirements">1. 必要な拡張機能</h2>
77
- <p>入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.1のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime ExpressionはBubble待機を使う場合だけ必要です。</p>
77
+ <p>入力待ちを含む完全な例では5つの拡張機能を使います。TurboWarpの拡張機能ライブラリからTemporary Variablesを追加し、選択した機能に必要なカスタム拡張機能を「サンドボックスなしで実行」を許可して読み込みます。BubbleはSVG Text 0.8.1のhost-neutral layout providerをbundle内に持ち、既定のSVG overlayではskinを作りません。portrait、lip-sync、continue indicator、フルボイス、表示効果音などのメディアアセットにはAsset Managerが必要です。Async InputとRuntime Expressionはconditionを使うBubble待機またはclose policyで必要です。timeoutだけのclose policyにはどちらも不要です。</p>
78
78
  <table>
79
79
  <thead>
80
80
  <tr>
@@ -105,11 +105,11 @@
105
105
  </tr>
106
106
  <tr>
107
107
  <td align="right">5</td>
108
- <td>Bubble 0.9.0</td>
109
- <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.9.0/dist/turbowarp-bubble.js</code></td>
108
+ <td>Bubble 0.10.0</td>
109
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.10.0/dist/turbowarp-bubble.js</code></td>
110
110
  </tr>
111
111
  </tbody></table>
112
- <p>開発中のBubbleを試す場合は、このリポジトリの<code>dist/turbowarp-bubble.js</code>をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、待機開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。</p>
112
+ <p>開発中のBubbleを試す場合は、このリポジトリの<code>dist/turbowarp-bubble.js</code>をローカルカスタム拡張機能として読み込みます。既定SVG overlayに必要なrenderer APIがない場合、画像・メディア機能の使用時にAsset Managerがない場合、condition待機の開始時にAsync InputかRuntime Expressionがない場合は、Bubbleが明示的なエラーを返します。低レベルComposition APIでは別のtext capabilityを注入できます。</p>
113
113
  <p>参考:</p>
114
114
  <ul>
115
115
  <li><a href="https://kubohiroya.github.io/turbowarp-asset-manager/ja/">Asset Manager 日本語ガイド</a></li>
@@ -296,6 +296,12 @@ close this bubble
296
296
  </code></pre>
297
297
  <p>まずTemporary Variablesで<code>input</code>を初期化してから、Async Inputのキー入力とタップのlistenerを登録します。Bubbleの待機ブロックは、<code>input == &quot;pressed&quot;</code>をRuntime Expressionへ委譲し、開始直後とVMの各フレームで評価します。待機中は自動的に<code>awaiting-continue</code>となり、口パクを停止して<code>set continue frames</code>の画像をループします。条件成立またはtimeout後は<code>idle</code>へ移り、次の<code>close this bubble</code>へ進みます。timeoutを<code>0</code>にすると時間制限なしです。</p>
298
298
  <p>次の待機に入る前に<code>input</code>を空文字へ戻してください。前回の<code>pressed</code>が残っていると、次の条件が直ちに成立します。別のBubble表示、close、対象targetの停止、projectの開始・停止、runtime破棄では、targetが所有する待機とlistener、timerをキャンセルして解放します。</p>
299
+ <p>同じ終了規則を再利用する場合は、名前付きBubble close policyを使います。triggerは<code>condition</code>、<code>timeout</code>、<code>condition-or-timeout</code>から明示的に選びます。policyの適用は定義をsnapshotし、成立まで待ち、Bubbleのhide animationと解放までを1つの待機commandとして実行します。</p>
300
+ <pre><code class="language-text">define bubble close policy [advance-or-timeout] trigger [condition-or-timeout] condition [input == &quot;pressed&quot;] timeout [10] seconds
301
+ show [海へ出発!] with bubble style [hero-dialogue]
302
+ wait and close this bubble using close policy [advance-or-timeout]
303
+ </code></pre>
304
+ <p>timeoutだけのpolicyは現在のanimation modeを変えず、入力用拡張を必要としません。conditionを含むpolicyは<code>awaiting-continue</code>へ移り、既存の統合待機と同じAsync Input/Runtime Expression設定を使います。待機中に同じ名前を再定義しても、変更は次回の適用から有効です。Bubbleの置換やlifecycle cleanupは待機中policyをcancelし、置換後のBubbleを閉じません。</p>
299
305
  <p>音声再生や別の文字送り処理と組み合わせる場合は、それらが完了した時点で<code>awaiting-continue</code>へ切り替えます。</p>
300
306
  <p><img src="../assets/bubble-lifecycle.gif" alt="sayで口パクし、awaiting-continueでcontinue framesを動かし、入力成立後にBubbleを閉じるアニメーション"></p>
301
307
  <p>アニメーションGIFを再生できない環境では、次の比較図で各animation modeを確認できます。</p>
@@ -371,6 +377,10 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
371
377
  <td>Bubble styleを定義または再定義する</td>
372
378
  </tr>
373
379
  <tr>
380
+ <td><code>define bubble close policy [POLICY] trigger [TRIGGER] condition [CONDITION] timeout [TIMEOUT] seconds</code></td>
381
+ <td>名前付きの終了条件を定義または置換する</td>
382
+ </tr>
383
+ <tr>
374
384
  <td><code>set bubble placement [PLACEMENT] for bubble style [STYLE]</code></td>
375
385
  <td>Actor相対方向・角度、または背景相対領域を設定する</td>
376
386
  </tr>
@@ -475,6 +485,10 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
475
485
  <td>Runtime Expressionの条件成立またはtimeoutまで待つ</td>
476
486
  </tr>
477
487
  <tr>
488
+ <td><code>wait and close this bubble using close policy [POLICY]</code></td>
489
+ <td>policyをsnapshotし、成立を待ってBubbleを閉じる</td>
490
+ </tr>
491
+ <tr>
478
492
  <td><code>close this bubble</code></td>
479
493
  <td>自分のBubbleと所有resourceを解放する</td>
480
494
  </tr>
@@ -513,6 +527,10 @@ animate bubble shape to [WAVY] speed [1] for [0.5] seconds
513
527
  <td>組み込みの短いsay/thinkを使うか、named custom styleを先に定義する</td>
514
528
  </tr>
515
529
  <tr>
530
+ <td><code>bubble close policy is not defined</code></td>
531
+ <td>名前付きclose policyを適用前に定義する</td>
532
+ </tr>
533
+ <tr>
516
534
  <td>image assetが未登録</td>
517
535
  <td><code>register resource ... as asset ...</code>の完了後にBubbleを表示する</td>
518
536
  </tr>
@@ -0,0 +1,50 @@
1
+ # 0.10.0: 名前付きBubble close policy
2
+
3
+ ## 概要
4
+
5
+ Bubble 0.10.0では、吹き出しを閉じる条件を再利用可能な名前付きpolicyとして定義し、表示後に名前で適用できる。
6
+
7
+ - `condition`、`timeout`、`condition-or-timeout`の3つのtriggerを明示的に選べる。
8
+ - `wait and close this bubble using close policy [POLICY]`は定義をsnapshotし、成立まで待ち、hide animationとresource解放までを実行する。
9
+ - timeoutだけのpolicyはAsync InputやRuntime Expressionを必要としない。
10
+ - conditionを含むpolicyは既存の統合待機と同じcapabilityを使い、待機中は`awaiting-continue` modeになる。
11
+ - Bubbleの置換、target/projectの停止、runtime破棄では待機をcancelし、置換後のBubbleを閉じない。
12
+
13
+ ## 追加ブロック
14
+
15
+ ```text
16
+ define bubble close policy [three-seconds] trigger [timeout] condition [] timeout [3] seconds
17
+ say [3秒後に閉じます。]
18
+ wait and close this bubble using close policy [three-seconds]
19
+ ```
20
+
21
+ キー入力やspriteへのタッチをRuntime Expressionのconditionとして登録した場合は、時間制限なしの`condition`、またはtimeoutとの先着になる`condition-or-timeout`を使える。
22
+
23
+ ```text
24
+ define bubble close policy [advance] trigger [condition] condition [input == "pressed"] timeout [0] seconds
25
+ say [キーを押すかspriteをタッチしてください。]
26
+ wait and close this bubble using close policy [advance]
27
+ ```
28
+
29
+ Bubble close policyは制御フローの設定であり、吹き出しの形やtail/trailを選ぶBubble styleとは別のregistryである。
30
+
31
+ ## 互換性
32
+
33
+ - 既存の`say`、`think`、`show ... with bubble style ...`、`wait with this bubble ...`、`close this bubble`の契約は維持する。
34
+ - 保存済みstyled say/thinkブロック向けの非表示opcodeも維持する。
35
+ - standalone manifestは33定義を持ち、paletteには31ブロックを表示する。
36
+ - Composition APIとTurboWarp adapterの既存entry pointに破壊的変更はない。
37
+
38
+ ## 検証
39
+
40
+ - `pnpm check`
41
+ - `pnpm release:check`
42
+ - TypeScript declarationとComposition API consumerのcompile成功。
43
+ - lifecycle cancel、定義snapshot、timeout、condition、先着triggerを自動testで検証。
44
+ - ドキュメントsource、Pages生成HTML、extension manifest、配布bundle、npm tarballを一括検証。
45
+
46
+ ## 更新とロールバック
47
+
48
+ extension URLまたはnpm dependencyを0.9.0から0.10.0へ更新する。名前付きclose policyを使わない既存projectは変更不要である。
49
+
50
+ 回帰が見つかった場合はextension URLまたはnpm dependencyを0.9.0へpinし、修正版0.10.x patchを公開する。公開済み0.10.0 packageをunpublishしたり、対応するGit tag/GitHub Releaseを削除したりしない。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kubohiroya/turbowarp-bubble",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Composable say and think bubbles with portrait layers and animated continue indicators for TurboWarp.",
5
5
  "author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
6
6
  "type": "module",