Skip to content

t1k:unity:rendering:sprite-text

FieldValue
Modulerendering
Version5.39.1
Effortlow
Tools—

Keywords: arcade font, bitmap font, sprite font, sprite text, sprite-sheet text, SpriteFontAsset, SpriteTextRenderer

/t1k:unity:rendering:sprite-text

Sprite-sheet bitmap text: a ScriptableObject glyph table (SpriteFontAsset) driving a pooled SpriteRenderer-per-character MonoBehaviour (SpriteTextRenderer). No third-party deps. Source lives in The1Studio/Mike.UnityCommon SpriteText/ — full annotated source: references/source.md.

Use SpriteText when the “font” IS hand-drawn sprite art with no glyph-per-glyph kerning table a font importer could generate — arcade-style digit strips, stylized damage-number sprites, pixel-art score counters. It is not a TMP replacement for body text, localized UI copy, or anything needing rich-text tags, ligatures, or RTL — TMP (t1k-unity-base-text-config) owns that.

  1. Create a SpriteFontAsset (Assets → Create → Sprite Text → Sprite Font Asset), fill glyphs (one GlyphEntry per drawable character), set lineHeight/spaceWidth, optionally a fallbackSprite.
  2. Add SpriteTextRenderer to a GameObject, assign the font, set text.
  3. Drive it at runtime via SetText/SetColor/SetTextSize — never write to the private text/color fields directly from other scripts (they’re [SerializeField] private, no public property backing them).
  4. For a counter/label that must fit a fixed UI slot, enable autoSizeToBounds + targetBoundsSize, and drag the cyan Scene-view handle (the custom editor only draws it while that toggle is on) to eyeball the box.
  • SetColor does NOT rebuild — it recolors already-placed glyphs in place. SetText/SetFont/SetTextSize all call RequestRebuild(), which is synchronous in edit mode but coalesced to next-LateUpdate in play mode (rebuildQueued flag) — don’t assume a rebuild is visible the same frame you call SetText in Play mode; use RefreshImmediate() if you need it synchronous.
  • The glyph pool is static, keyed only by component type — shared across every SpriteTextRenderer in the scene, not IObjectPoolManager-based. This predates rules/mono-pool-spawn-unity.md’s pooling mandate; if you use this code in a project bound by that rule, treat the static pool as a documented, deliberate exception (already-pooled, just not through the kit’s pool manager) rather than a violation to “fix” — rewriting it to route through IObjectPoolManager would need to preserve the deferred-release-queue behavior below or it will reparent-then-reacquire mid-frame.
  • Glyph release is deferred by up to one frame. ReleaseGlyph doesn’t move a freed SpriteRenderer into the pool synchronously — it queues it, and a SharedPoolPump.LateUpdate() on a lazily-spawned DontDestroyOnLoad root object ("__SpriteTextSharedPool") drains the queue. A rebuild that shrinks text (fewer glyphs) then immediately re-grows it (more glyphs) in the same call can legitimately spawn a fresh GameObject rather than reuse the one it just freed — that’s by design, not a leak.
  • font.Revision polling, not an event. SpriteTextRenderer.LateUpdate only rebuilds when font.Revision != observedFontRevision, checked once per frame in Play mode only. Editing a SpriteFontAsset glyph list at edit time updates every renderer immediately via OnValidate → Rebuild(), but a runtime mutation to the font asset (e.g. via a script) needs SpriteFontAsset to bump Revision itself — direct field writes bypassing OnValidate won’t be picked up until the asset’s own OnEnable/OnValidate fires.
  • Space characters and unmapped characters never allocate a SpriteRenderer. They only advance x by (font.SpaceWidth + characterSpacing) * renderSize (space) or the same fallback-width calc (unmapped char with no fallbackSprite). If you’re debugging “why is my glyph count lower than my string length”, this is why — count characters that actually resolved a GlyphEntry or fallback sprite.
  • Alignment costs a second full pass per line. GetLineAlignmentOffset walks the whole line before BuildLayout’s placement pass touches a single glyph, to compute minX/maxX for Center/Right alignment. For very long per-frame-changing strings (e.g. a live-updating debug counter) this is O(2n) per rebuild, not O(n) — usually negligible, but worth knowing before blaming glyph instantiation for a profiler spike.
  • [ExecuteAlways] means Awake/OnEnable/OnValidate all run in edit mode too — a SpriteTextRenderer dropped into a scene renders its placeholder text immediately in the Editor, before Play mode. Its editor-mode glyph objects are plain new GameObject + DestroyImmediate, NOT routed through the shared runtime pool (GetOrCreateSharedPoolRoot() throws outside Play mode) — this is correct, not a second inconsistent pooling path to fix.
  • WorldBounds transforms the actual glyph-derived localBounds, not targetBoundsSize. If you need the authored fit box in world space (e.g. to draw your own UI frame around it), read targetBoundsSize + transform, not WorldBounds.

references/source.md — every field, the layout algorithm, the pooling state machine, and the custom Scene-view editor, annotated against the actual Mike.UnityCommon source.

Reference-only: this skill documents third-party repo code for reuse/porting decisions. It does not ship the .cs files into this project — copy SpriteFontAsset.cs/SpriteTextRenderer.cs/SpriteTextRendererEditor.cs from the source repo (respecting its own license/versioning) when you actually integrate it, and get the accompanying .asmdefs right (SpriteText.Runtime, SpriteText.Editor) so the editor script isn’t pulled into player builds.

A visible change made with this skill (UI, sprites, 3D, shaders, VFX, animation, lighting, scene layout; audio excluded) follows core rule visual-change-discord-notice:

  • Capture OLD before the first edit and NEW after the last (screen: ScreenCapture in Play mode per t1k-unity-editor-cli, windowed or Xvfb only because rendering is needed; 3D, shader, VFX: same-scene frame grab; 2D asset: the file).
  • Return the paths and a draft Discord post to the orchestrator, which posts; the PR links the post or carries visual-notice-waiver: <reason>. Logic only: “no visible change”. No capture: “screenshots pending: ”, never a fake image.