t1k:unity:rendering:sprite-text
| Field | Value |
|---|---|
| Module | rendering |
| Version | 5.39.1 |
| Effort | low |
| Tools | — |
Keywords: arcade font, bitmap font, sprite font, sprite text, sprite-sheet text, SpriteFontAsset, SpriteTextRenderer
How to invoke
Section titled “How to invoke”/t1k:unity:rendering:sprite-textSpriteText
Section titled “SpriteText”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.
When to reach for this vs TextMeshPro
Section titled “When to reach for this vs TextMeshPro”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.
Quick usage
Section titled “Quick usage”- Create a
SpriteFontAsset(Assets → Create → Sprite Text → Sprite Font Asset), fillglyphs(oneGlyphEntryper drawable character), setlineHeight/spaceWidth, optionally afallbackSprite. - Add
SpriteTextRendererto a GameObject, assign the font, settext. - Drive it at runtime via
SetText/SetColor/SetTextSize— never write to the privatetext/colorfields directly from other scripts (they’re[SerializeField] private, no public property backing them). - 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.
Hard rules
Section titled “Hard rules”SetColordoes NOT rebuild — it recolors already-placed glyphs in place.SetText/SetFont/SetTextSizeall callRequestRebuild(), which is synchronous in edit mode but coalesced to next-LateUpdatein play mode (rebuildQueuedflag) — don’t assume a rebuild is visible the same frame you callSetTextin Play mode; useRefreshImmediate()if you need it synchronous.- The glyph pool is
static, keyed only by component type — shared across everySpriteTextRendererin the scene, notIObjectPoolManager-based. This predatesrules/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 throughIObjectPoolManagerwould 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.
ReleaseGlyphdoesn’t move a freedSpriteRendererinto the pool synchronously — it queues it, and aSharedPoolPump.LateUpdate()on a lazily-spawnedDontDestroyOnLoadroot 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 freshGameObjectrather than reuse the one it just freed — that’s by design, not a leak. font.Revisionpolling, not an event.SpriteTextRenderer.LateUpdateonly rebuilds whenfont.Revision != observedFontRevision, checked once per frame in Play mode only. Editing aSpriteFontAssetglyph list at edit time updates every renderer immediately viaOnValidate→Rebuild(), but a runtime mutation to the font asset (e.g. via a script) needsSpriteFontAssetto bumpRevisionitself — direct field writes bypassingOnValidatewon’t be picked up until the asset’s ownOnEnable/OnValidatefires.- Space characters and unmapped characters never allocate a
SpriteRenderer. They only advancexby(font.SpaceWidth + characterSpacing) * renderSize(space) or the same fallback-width calc (unmapped char with nofallbackSprite). If you’re debugging “why is my glyph count lower than my string length”, this is why — count characters that actually resolved aGlyphEntryor fallback sprite. - Alignment costs a second full pass per line.
GetLineAlignmentOffsetwalks the whole line beforeBuildLayout’s placement pass touches a single glyph, to computeminX/maxXforCenter/Rightalignment. 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]meansAwake/OnEnable/OnValidateall run in edit mode too — aSpriteTextRendererdropped into a scene renders its placeholder text immediately in the Editor, before Play mode. Its editor-mode glyph objects are plainnew 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.WorldBoundstransforms the actual glyph-derivedlocalBounds, nottargetBoundsSize. If you need the authored fit box in world space (e.g. to draw your own UI frame around it), readtargetBoundsSize+transform, notWorldBounds.
Full source + line-by-line reference
Section titled “Full source + line-by-line reference”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.
Visual change notice
Section titled “Visual change notice”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:
ScreenCapturein Play mode pert1k-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.