@kubohiroya/turbowarp-bubble 0.9.0 → 0.11.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.
@@ -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": [
@@ -10541,7 +10584,7 @@
10541
10584
  return typeof value === "object" && value !== null && !Array.isArray(value);
10542
10585
  }
10543
10586
  function validateExtension(value) {
10544
- if (!isRecord$3(value) || typeof value.setText !== "function" || typeof value.releaseTextActor !== "function") throw new TypeError("TurboWarp SVG Text adapter requires setText and releaseTextActor.");
10587
+ if (!isRecord$3(value) || typeof value.setText !== "function" || typeof value.releaseTextActor !== "function") throw new TypeError("TurboWarp-SVG-Text adapter requires setText and releaseTextActor.");
10545
10588
  return value;
10546
10589
  }
10547
10590
  function validateComposition(value) {
@@ -10587,7 +10630,7 @@
10587
10630
  });
10588
10631
  }
10589
10632
  /**
10590
- * Adapt the TurboWarp SVG Text extension to Bubble's host-neutral text
10633
+ * Adapt the TurboWarp-SVG-Text extension to Bubble's host-neutral text
10591
10634
  * capability contract.
10592
10635
  */
10593
10636
  function createTurboWarpSvgTextCapability(extensionInput) {
@@ -10603,7 +10646,7 @@
10603
10646
  extension.releaseTextActor(target);
10604
10647
  },
10605
10648
  measureText({ styleName, text }) {
10606
- if (typeof extension.measureText !== "function") throw new Error("TurboWarp SVG Text does not provide text measurement.");
10649
+ if (typeof extension.measureText !== "function") throw new Error("TurboWarp-SVG-Text does not provide text measurement.");
10607
10650
  return extension.measureText(styleName, text);
10608
10651
  }
10609
10652
  });
@@ -10660,7 +10703,7 @@
10660
10703
  * Adapts the stock SVG Text extension's shared named-style layout registry.
10661
10704
  */
10662
10705
  function createTurboWarpSvgTextOverlayTextCapability(extensionInput) {
10663
- if (!isRecord$3(extensionInput) || typeof extensionInput.getLayoutCapability !== "function") throw new TypeError("TurboWarp SVG Text overlay adapter requires SVG Text 0.8.1 getLayoutCapability().");
10706
+ if (!isRecord$3(extensionInput) || typeof extensionInput.getLayoutCapability !== "function") throw new TypeError("TurboWarp-SVG-Text overlay adapter requires SVG Text 0.8.1 getLayoutCapability().");
10664
10707
  return createSvgTextOverlayTextCapability(extensionInput.getLayoutCapability());
10665
10708
  }
10666
10709
  //#endregion
@@ -12442,7 +12485,7 @@
12442
12485
  async playSound(name, playOptions = {}) {
12443
12486
  const extension = getAssetExtension();
12444
12487
  const method = playOptions.untilDone ? extension?.playSoundUntilDone : extension?.playSound;
12445
- if (typeof method !== "function") throw new BubbleRuntimeAdapterError("BUBBLE-RUNTIME-002", "TurboWarp Asset Manager does not provide audio playback.");
12488
+ if (typeof method !== "function") throw new BubbleRuntimeAdapterError("BUBBLE-RUNTIME-002", "TurboWarp-Asset-Manager does not provide audio playback.");
12446
12489
  await method.call(extension, { NAME: name });
12447
12490
  }
12448
12491
  };
@@ -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.11.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));
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Opaque host-owned target used by a text capability.
3
3
  *
4
- * The capability may be implemented by TurboWarp SVG Text or by another
4
+ * The capability may be implemented by TurboWarp-SVG-Text or by another
5
5
  * renderer in a different host environment.
6
6
  */
7
7
  export type BubbleTextTarget = object;
@@ -40,7 +40,7 @@ export interface SvgTextLayoutCompositionLike {
40
40
  }>): SvgTextLayoutLike;
41
41
  }
42
42
  /**
43
- * Adapt the TurboWarp SVG Text extension to Bubble's host-neutral text
43
+ * Adapt the TurboWarp-SVG-Text extension to Bubble's host-neutral text
44
44
  * capability contract.
45
45
  */
46
46
  export declare function createTurboWarpSvgTextCapability(extensionInput: unknown): BubbleTextCapability;
@@ -8,17 +8,17 @@
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
  | ---: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
15
15
  | 1 | Temporary Variables | TurboWarpの拡張機能ライブラリから追加 |
16
- | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
16
+ | 2 | Async Input 0.5.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.5.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
- | 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` |
18
+ | 4 | Asset Manager 0.13.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js` |
19
+ | 5 | Bubble 0.11.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.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
 
@@ -1,4 +1,4 @@
1
- # TurboWarp Bubble Block Manual
1
+ # TurboWarp-Bubble Block Manual
2
2
 
3
3
  This manual explains how to use `turbowarp-bubble` as an unsandboxed TurboWarp custom extension. A Bubble combines an SVG body, text, a character portrait, blinking and lip-sync layers, and an animated continue indicator.
4
4
 
@@ -8,17 +8,17 @@ 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
  | ----: | ------------------------ | -------------------------------------------------------------------------------------------------------- |
15
15
  | 1 | Temporary Variables | Add from the TurboWarp extension library |
16
- | 2 | Async Input 0.4.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js` |
16
+ | 2 | Async Input 0.5.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.5.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
- | 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` |
18
+ | 4 | Asset Manager 0.13.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js` |
19
+ | 5 | Bubble 0.11.0 | `https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.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
@@ -4,7 +4,7 @@
4
4
  <meta charset="utf-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
6
  <meta name="description" content="Block manual for TurboWarp Bubble, including shapes, placement, portraits, blinking, lip-sync, and the animated continue indicator.">
7
- <title>TurboWarp Bubble Block Manual</title>
7
+ <title>TurboWarp-Bubble Block Manual</title>
8
8
  <style>
9
9
  :root { color-scheme: light dark; --ink: #25283a; --muted: #667085; --accent: #d94b68; --accent-strong: #b83255; --accent-soft: #fff0f4; --line: #d9deea; --panel: #fff; --page: #f2f4f8; --code: #25283a; }
10
10
  @media (prefers-color-scheme: dark) { :root { --ink: #f7edf1; --muted: #c8bcc2; --accent: #ff8ca3; --accent-strong: #ffb2c1; --accent-soft: #48252f; --line: #50434a; --panel: #211c20; --page: #151215; --code: #100d10; } }
@@ -67,14 +67,14 @@
67
67
  </div>
68
68
  </header>
69
69
  <main id="manual" class="manual">
70
- <h1>TurboWarp Bubble Block Manual</h1>
70
+ <h1>TurboWarp-Bubble Block Manual</h1>
71
71
  <p>This manual explains how to use <code>turbowarp-bubble</code> as an unsandboxed TurboWarp custom extension. A Bubble combines an SVG body, text, a character portrait, blinking and lip-sync layers, and an animated continue indicator.</p>
72
72
  <blockquote>
73
73
  <p><strong>Kamishibai DSL 4.0 bundle:</strong> In the combined runtime palette, click the documentation button directly below the <strong>Bubble</strong> member heading to open this manual. The bundled blocks keep the styles, placement, portrait, reveal, audio, wait, animation, clone, and cleanup behavior documented here; their member namespace and Bubble icon identify their origin.</p>
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>
@@ -90,8 +90,8 @@
90
90
  </tr>
91
91
  <tr>
92
92
  <td align="right">2</td>
93
- <td>Async Input 0.4.0</td>
94
- <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.4.0/dist/async-input.js</code></td>
93
+ <td>Async Input 0.5.0</td>
94
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-async-input@0.5.0/dist/async-input.js</code></td>
95
95
  </tr>
96
96
  <tr>
97
97
  <td align="right">3</td>
@@ -100,16 +100,16 @@
100
100
  </tr>
101
101
  <tr>
102
102
  <td align="right">4</td>
103
- <td>Asset Manager 0.12.1</td>
104
- <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.12.1/dist/asset-manager.js</code></td>
103
+ <td>Asset Manager 0.13.0</td>
104
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-asset-manager@0.13.0/dist/asset-manager.js</code></td>
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.11.0</td>
109
+ <td><code>https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-bubble@0.11.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>