@combos-fun/plugin-renderer-text

@combos-fun/plugin-renderer-text — part of the Combos Fun engine monorepo.

Keywords: text, label, font, string, 2d.

Documentation

• Per-package agent / developer notes: agent-skill.md
• Machine-readable manifest: combos-plugin.json (validated against schemas/combos-plugin.schema.json in the repo root)
• Entry skill (single source of truth for AI agents working with this monorepo): skills/combos-engine-development/SKILL.md

When consumed from npm, the manifest and agent notes are exposed as stable subpaths:

import manifest from '@combos-fun/plugin-renderer-text/plugin-manifest';
// or fetch the markdown directly:
// require.resolve('@combos-fun/plugin-renderer-text/agent-skill')

Host-driven i18n

Configure the source locale on the text system. Locale names use BCP 47 tags.

const textSystem = new TextSystem({
  sourceLocale: 'zh-CN',
  sourceTexts: [
    '{player} 获得了 {score} 分',
    '开始游戏',
    '下一屏文案',
  ],
});

Text uses its source template as the translation lookup key. Named replacements keep dynamic values independent from translated word order.

new Text({
  text: '{player} 获得了 {score} 分',
  replacements: {
    player: 'Alice',
    score: 100,
  },
});

The host injects window.combos into the game HTML head. The first requestI18n runs in beforeReady and holds combos-game:ready / start until the host replies. Labels stay empty until that reply so source copy does not paint first. Put every later-screen template in sourceTexts so those screens reuse the startup catalog instead of flashing source text. The system keeps one growing session catalog of source templates and translations; later requestI18n calls only send templates still missing from that catalog. If the host returns needed: true but a template is missing from translations, the system sends only the still-untranslated texts and waits for one more requestI18n before showing that label. After ready, the next render of a template that still has no translation requests it again. The same visible label does not request every frame; hiding it and showing it does. Returning to copy that is already in translations does not call requestI18n again. needed: false keeps source text and does not cancel later requests after needed: true. Translation is applied only when the result is needed: true:

if (typeof window.combos?.requestI18n !== 'function') return;

// First call (beforeReady): await, then start / ready
const result = await window.combos.requestI18n({
  sourceLocale: 'zh-CN',
  sourceTexts: [
    '{player} 获得了 {score} 分',
    '开始游戏',
  ],
});
// { needed: false } → keep source text
// { needed: true, locale, translations } → replace, then enter the game

Missing replacements fall back to the unchanged placeholder. Without the injected SDK, the game stays on the source text.

License

Internal workspace package, part of the Combos Fun engine monorepo.