@combos-fun/plugin-renderer-3d-text 0.1.15 → 0.1.16

package/agent-skill.md

@@ -1,104 +1,34 @@
 # `@combos-fun/plugin-renderer-3d-text` — Agent notes
 
-In-world text backed by `troika-three-text`, suitable for labels, dialogue, signs, and scoreboards.
-
-Prerequisite: follow the parent `@combos-fun/plugin-renderer-3d` skill for system order, pose seeding, hierarchy, and rendering lifecycle.
-
-## Public API
-
-```ts
-import { Text3D, Text3DSystem, type Text3DParams } from '@combos-fun/plugin-renderer-3d-text';
-```
-
-`componentName = 'Text3D'`; `systemName = 'Text3DSystem'`.
-
-For dynamic, translatable text, keep values in named `replacements`; do not
-concatenate them into `text` and do not invent translation IDs:
+In-world text. Parent setup: `plugin-renderer-3d`.
 
 ```ts
-score.addComponent(new Text3D({
-  text: '{player} scored {score} points',
-  replacements: { player: 'Alice', score: 100 },
-  fontSize: 0.4,
-}));
+import { Text3D, Text3DSystem } from '@combos-fun/plugin-renderer-3d-text';
 ```
 
-**MUST** set `Text3DSystem` `sourceLocale` to the game's written language as a
-BCP 47 tag (`en`, `en-US`, `zh-CN`, `ja-JP`, …). Match the `Text3D` literals,
-not the player device locale. Omitting it disables host i18n.
+`componentName = 'Text3D'`. `systemName = 'Text3DSystem'`.
 
-```ts
-new Text3DSystem({
-  sourceLocale: 'zh-CN',
-  sourceTexts: ['开始游戏', '下一关已解锁'],
-});
-```
+| Field | Default |
+| --- | --- |
+| `text` | `''` |
+| `replacements` | `{}` |
+| `fontSize` | `0.5` |
+| `color` | `0xffffff` |
+| `anchorX` / `anchorY` | `'center'` / `'middle'` |
+| `maxWidth` | `0` (applied only when `> 0`) |
+| `font` | `''` — URL/path, not a resource name |
+| `positionX/Y/Z`, `rotationX/Y/Z` | `0` |
 
-Pass **every** later-screen template in `sourceTexts` so the first
-`requestI18n` translates the full catalog before `ready`. The system keeps one
-growing session catalog of source templates and translations: new labels are
-added to it, and going back to earlier copy looks up that catalog instead of
-rebuilding from the current screen. You can also call
-`textSystem.declareSourceTexts([...])` during `onSystemsBootstrapComplete`.
+No scale fields; size is `fontSize`. Glyph layout is async. `maxWidth: 0` and `font: ''` do not undo a previous value.
 
-The source template itself is the translation lookup key. After labels exist,
-the system checks that `window.combos.requestI18n` exists. The first
-`requestI18n({ sourceLocale, sourceTexts })` runs in `beforeReady` and holds
-game `ready` / `start` until the host replies. Labels stay empty until that
-first reply so the source language does not flash on the canvas. Apply the
-result only when `needed: true`. If that reply is `needed: true` but a current template is
-missing from `translations`, send only the still-untranslated templates and
-`requestI18n` once more before `ready`. After ready, a new label whose
-translation is still missing stays empty, sends only those missing templates,
-waits for one more `requestI18n`, then renders. Already-translated templates
-are omitted from later `requestI18n` payloads and do not trigger another call
-when the same labels go back to earlier copy.
-`needed: false` keeps source text and does not hold later labels. Do not post `i18n-ready` / `set-i18n` from
-this plugin. If no source locale or method is present, placeholder replacement
-still works and source text stays as-is.
+**MUST** `new Text3DSystem({ sourceLocale, sourceTexts })`. `sourceLocale` is the written language (`en`, `zh-CN`, `ja-JP`), not the device locale. `sourceTexts` lists every template. `declareSourceTexts([...])` during `onSystemsBootstrapComplete` also works. Omitting `sourceLocale` disables host i18n.
 
-## Parameters
-
-| Field | Type | Default |
-|-------|------|---------|
-| `text` | `string` | `''` |
-| `replacements` | `Record<string, string \| number>` | `{}` |
-| `fontSize` | `number` | `0.5` |
-| `color` | `number` | `0xffffff` |
-| `anchorX` | `string` | `'center'` |
-| `anchorY` | `string` | `'middle'` |
-| `maxWidth` | `number` | `0`; applied only when `> 0` |
-| `font` | `string` | `''`; Troika URL/path, not an engine resource name |
-| `positionX/Y/Z` | `number` | `0` |
-| `rotationX/Y/Z` | `number` | `0` radians |
-
-There are no scale fields; use `fontSize` for size.
-
-## Runtime and lifecycle
-
-- ADD creates and attaches a `TroikaText`, then calls its asynchronous `sync()`. Property changes copy values and call `sync()` again.
-- Font loading and glyph layout complete asynchronously inside Troika. Do not assume final geometry or metrics immediately after ADD.
-- Removal detaches and disposes the Troika object; there is no engine named-resource lifecycle for `font`.
-- Pose synchronizes per frame.
-
-## Package-specific pitfalls
-
-- `font` must be a browser-reachable URL/path.
-- Setting `maxWidth` back to `0` does not clear a previously applied positive width in the current implementation; likewise, setting `font` back to `''` does not restore the prior/default font.
-- Empty text or a background-matching color can look like a render failure.
-
-## Minimal example
+`text` is the translation key. Values go in `replacements`. `requestI18n` runs in `beforeReady` and holds `ready` when `window.combos.requestI18n` exists. Labels stay empty until that reply. Apply only when `needed: true`. A missing template is requested once more; after `ready` it stays empty until that reply. One session catalog: new labels are added, earlier screens are looked up, and already translated templates are not sent again. `needed: false` keeps source text. Do not post `i18n-ready` / `set-i18n`. With no `sourceLocale` or `requestI18n`, replacements still run and source text stays.
 
 ```ts
-const sign = new GameObject('sign');
 sign.addComponent(new Text3D({
-  text: 'Welcome',
-  fontSize: 0.6,
-  color: 0xffffff,
-  positionY: 1.5,
+  text: '{player} 得分 {score}',
+  replacements: { player: 'Alice', score: 100 },
+  fontSize: 0.4,
 }));
 ```
-
-## Verification
-
-`pnpm --filter @combos-fun/plugin-renderer-3d-text run build`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combos-fun/plugin-renderer-3d-text",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "3D text rendering, backed by troika-three-text",
   "main": "index.js",
   "module": "dist/plugin-renderer-3d-text.esm.js",
@@ -28,9 +28,9 @@
   "dependencies": {
     "three": "^0.172.0",
     "troika-three-text": "^0.52.3",
-    "@combos-fun/inspector-decorator": "0.1.15",
-    "@combos-fun/plugin-renderer-3d": "0.1.15",
-    "@combos-fun/engine": "0.1.15"
+    "@combos-fun/plugin-renderer-3d": "0.1.16",
+    "@combos-fun/inspector-decorator": "0.1.16",
+    "@combos-fun/engine": "0.1.16"
   },
   "devDependencies": {
     "tsx": "^4.20.3"