Reference and Developer Appendix
Performance and frequent updates
Frequently changing TextMeshPro counters, labels, documents, chat text, and UI Toolkit labels can coalesce replacements until the next update. Request an immediate update only when same-call visibility is required. For temporary text, prewarm the emitter during a loading or setup moment and size inactive retention separately from Maximum Active. The emitter uses one Unity object pool per complete host prefab, keeps returned hosts hidden so renderer state can stay warm, and releases every retained instance when the emitter is disabled or destroyed. Feature-free persistent text still uses a direct backend path, animated TextMeshPro can reuse the freshly generated source mesh, compatible whole-text and multi-effect stacks avoid duplicate glyph work, and stepped effects refresh only when their visible state changes.
Preview export
Preview export can produce 960 by 540 MP4 at 60 frames per second on Windows and macOS, or transparent GIF at 50 frames per second. Linux supports GIF but not MP4. Export can use flat text or the installed renderer, including lit perspective 3D. Frame planning distinguishes the last visible glyph, reveal completion after its trailing wait, and the point when appearance effects settle, with Reveal Speed scaling applied to each milestone.
Runtime control
For scripted experiences, keep the public surface small: set text, start or skip reveal, play hide, choose a profile, and listen for waits, markers, and completion. IsWaitingForAction reports whether a timed or input action currently owns the wait, and SkipCurrentWait() cancels that wait without confusing it with an ordinary pause. Detailed class and extension contracts are documented in the package API comments and custom-effects guide.
Temporary text uses the same small surface. EmitValue and EmitText return a generation-safe TextStudioEmissionHandle. A live handle can update text or value and request dismissal; after release or pool reuse, the same calls safely return false.
TextStudioEmissionHandle score = emitter.EmitValue(scorePreset, 1250, target);
score.SetValue(1500);
score.SetText("NEW HIGH SCORE");
score.Dismiss();
Custom effects and channels
Create a custom Code Effect only when built-in effects and Composed channel layers cannot express the algorithm. Use an asset-backed Code Effect for serialized typed defaults, ranges, aliases, and catalog identity; use a runtime factory when the effect depends on scene objects, services, or live game state. Code Effects own behavior and isolated invocation state. Composed Effects own lifecycle, playback, curves, timing, sequence, scope, and reusable authoring. Declare channels, supported renderer spaces, motion behavior, determinism, and flash characteristics so the editor can give accurate compatibility guidance.
Support
When requesting support, include the Unity version, Text Studio version, render pipeline, a minimal sample, the Health Check result, and the exact source text that reproduces the issue.
Essential scripting API
TextStudioText is the authoritative component facade. TextStudioApi is the task-oriented convenience layer for common setup and playback. Both accept normal Unity lifecycle rules and must be called from the main thread when they touch components or Unity objects. TextStudioApi treats a missing hub as a safe no-op.
using TextStudio;
public void ShowReward(TextStudioText label, string itemName)
{
TextStudioApi.ConfigureReveal(label, RevealMode.ByGlyph, 1.25f);
TextStudioApi.ShowText(label,
$"You found a <shimmer>{itemName}</shimmer>!");
}
SetText changes the authored source. StartReveal restarts from the beginning. ContinueReveal continues current progress. SkipReveal completes the line. PauseReveal and ResumeReveal use a balanced pause depth. SkipCurrentWait requests cooperative cancellation for a timed, input, or audio wait. AdvanceOrSkip returns true only when the caller may request the next line.
if (text.IsWaitingForAction)
text.SkipCurrentWait();
else if (text.IsRevealing)
text.SkipReveal();
else
RequestNextLine();
SetRevealSpeed clamps the multiplier to at least 0.01. SetRevealProgress and DriveRevealProgress accept normalized progress. SetGlyphVisibility, SetWordVisibility, and SetTextVisibility override visibility without changing typewriter progress and report invalid requests with false. ClearVisibilityOverrides returns ownership to reveal.
Drive effects from external time
Use External Effect Driver when another system owns time. Add it beside a Text Studio host, assign one built-in, custom, or Composed Effect, then provide exact Progress and Intensity values. Choose All Text or an inclusive Glyph Range. The component does not create another clock, reveal lifecycle, or animation stack.
This makes Animator states, Timeline clips, tween systems, gameplay variables, audio analysis, and editor scrubbing responsible for time while Text Studio remains responsible for semantic glyphs and renderer-safe evaluation. Multiple enabled drivers may contribute ordered layers. Ordinary authored effects evaluate first; accepted external submissions evaluate afterward in stable submission order. When layers write the same channel, their order can affect the blend, so keep the driver stack deliberate and verify it in Live Preview.
External Effect Driver exposes exact, clock-free control for animation systems that already own time.
Drive the same path from code
ApplyExternalEffect submits one renderer-neutral layer for the current evaluated frame. Resubmit while the layer should remain active. Progress and intensity are clamped. Omitted glyph bounds address all visible glyphs, explicit bounds are inclusive, invalid requests return false, and accepted layers keep the same post-effect ordering as component drivers.
void Update()
{
float progress = Mathf.Repeat(Time.time, 1f);
text.ApplyExternalEffect(effect, progress, 1f);
}
UI Toolkit essentials
Use UI Builder's Add Binding command to add TextStudioBinding, a UI Toolkit CustomBinding extension, to the text property of an ordinary Label. In code, call AttachTextStudio on an existing TextElement. Automatic mode owns one scheduled item, advances at most once per Unity frame, sleeps when no time-dependent feature is active, and stops on panel detach. Manual mode is for deterministic host clocks, tests, or custom scheduling.
TextStudioBinding binding = label.AttachTextStudio(profile);
binding.SetTextDeferred("Score <pulse>1250</pulse>");
// In Manual mode only:
binding.UpdateFromHost(deltaTime);
Registration and extension essentials
Register custom effects, actions, curves, playbacks, timings, expansion sheets, extension tags, renderers, text sources, and placement providers only through their documented interfaces. Use stable namespaced IDs. Parameter parsing belongs at bind time, not inside per-glyph Evaluate calls. Transient plan and frame views must not be retained beyond their callback.
TextStudioApi.RegisterEffect(new OrbitEffect());
TextStudioApi.RegisterAction(customAction);
TextStudioApi.RegisterCurve("studio.ease", curve);
Inspector and asset reference
- TextStudioText inspector: persistent preview plus Content, Typewriter, Placement, Events, and Debug tabs.
- Content authoring: Raw and Live Source, + Tag browser, caret-aware help, active backend, Behavior Profile, default effects, and diagnostics.
- TextStudioBehaviorProfile: independent Default Effects and Typewriter domains with retained local fallback behavior.
- TextStudioTypewriterPreset and Motion Preset: reusable pacing, lifecycle, motion, skip, wait, and hide behavior.
- CharacterTimings and WordTimings: context-aware delay, punctuation, boundary, and final-wait rules.
- TextStudioComposedEffectAsset: ordered layers, phases, curves, playback, semantic Area, spatial fields, surface masks, sharing, and preview.
- Spatial Effect Target: one shared scene target, consumer status, filtered creation and browsing, and a scene radius handle.
- External Effect Driver: one exact externally clocked effect with Progress, Intensity, and All Text or inclusive Glyph Range targeting.
- Markup Syntax and Tag Expansion Sheet: authoring grammar, escaping, and reviewed project vocabulary.
- Audio Set, Audio Player, actions, relays, Dialogue Source, Page Navigator, and Auto Scroll Follower: production sound and flow helpers.
- Project Settings, Health Check, Migration, Gallery, Recipes, Examples, and Effect Code: project-wide authoring, learning, sharing, and diagnostics.
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudioText main inspector | Persistent preview plus Content, Typewriter, Placement, Events, and Debug tabs. | First result; runtime model; reveal; placement; actions; troubleshooting |
Persistent preview controls | Raw or Live, Reveal or Active or Hide, Play or Pause, speed, Active duration range, repeat, scrub, restart, skip, and hide. | Authoring modes; runtime model; Read the Inspector as a Workflow; preview and export |
Content tab | Source, + Tag, caret-aware help, Behavior Profile, default effects, backend state, and diagnostics. | Markup; effects; Behavior Profiles; backends |
Typewriter tab | None, Built-In, Custom, or Inline source; unit, timings, clocks, motion, start, loop, skip, waits, and hide. | Build Reveals and Typewriter Experiences |
Placement tab | Built-in placement modes, orientation, extension providers, and Shared Spatial Target with consumer status and scene radius. | Place and Influence Text |
Events tab | Reveal lifecycle, markers, relays, payloads, and dialogue handoff. | Sound, Input, Events, and Interaction |
Debug tab | Resolved source, parsed ranges, active bindings, renderer channels, waits, and ownership. | Diagnose Problems |
TextStudioDefaultSettings | Project-wide built-in defaults and fallback behavior. | Project Settings and Behavior Ownership |
CharacterTimings | Character categories, punctuation delay, whitespace behavior, and overrides. | Character and Word Timings |
WordTimings | Word pacing, punctuation-aware pauses, and readable rhythm. | Character and Word Timings |
Inspector coverage, part 2 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudioTypewriterPreset | Complete reusable reveal and hide recipe. | Reveal Units and Settings Sources; Behavior Profiles |
TextStudioTypewriterMotionPreset | Reusable reveal or hide motion without changing timing. | Reveal and Hide Motion |
TextStudioBehaviorProfile | Independent Default Effects and Typewriter domains, with complete local behavior retained behind supplied domains. | Reuse Your Work; Behavior Profiles |
TextStudioProjectSettings | Catalogs, syntax, expansion sheets, defaults, motion policy, capability discovery, and validation. | Project Settings and Behavior Ownership |
TextStudioMarkupSyntax | Delimiter pair, native angle-tag acceptance, and literal escaping. | Custom Delimiters and Syntax Assets |
TextStudioTagExpansionSheet | Short project vocabulary expanded into reviewed markup stacks. | Tag Expansion Sheets |
TextStudioCodeEffectAsset | Programmable leaf effect identity, one typed default parameter set, metadata, catalog state, and renderer compatibility. | Custom Effects; Reference and Developer Appendix |
TextStudioComposedEffectAsset | Layer order, channels, phases, targeting, blends, influence, sharing, and diagnostics. | Create Composed Effects |
EffectCurveAsset | Reusable normalized progress shape and custom curve. | Phases, Curves, Playback, and Phase Shift |
EffectPlaybackAsset | Once, loop, ping-pong, persistence, duration, delay, and phase behavior. | Phases, Curves, Playback, and Phase Shift |
Inspector coverage, part 3 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudioAudioSet | Glyph clips, marker cues, source choice, pitch, volume, and cooldown policy. | Audio Sets and Audio Player |
TextStudioAudioPlayer | Runtime clip selection, overlap, interruption, marker routing, and ownership. | Audio Sets and Audio Player |
Play Sound asset and component | Authored one-shot sound, optional wait for completion, and scene-local ownership. | Built-in action tags; Audio Sets and Audio Player |
Custom action asset and component | Reusable or scene-local authored action with cooperative wait and skip behavior. | Actions Inside the Line; Developer Appendix |
InputSystemWaitInputAction | Named InputActionReference mapping, enable policy, timeout, and fallback. | Input System integration |
TextStudioDialogueSource | Stable content bridge for dialogue, quest, subtitle, or cutscene systems. | Dialogue Source and Long Text |
TextStudioMarkerEventRouter | Marker-name routing to UnityEvents or code. | Events, Markers, and Relays |
TextStudioTypewriterEventRelay | Reveal and wait lifecycle forwarded without a custom subscriber. | Events, Markers, and Relays |
TextStudioPageNavigator | Visible-page navigation without recompiling the complete document. | Long Text, Codex Pages, and Credits |
TextStudioAutoScrollFollower | Keeps the newest revealed content visible in a ScrollRect. | Long Text, Codex Pages, and Credits |
Inspector coverage, part 4 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudioSingleEventSystemGuard | Avoids duplicate EventSystems in additive-scene samples. | Samples; Diagnose Problems |
TMP setup inspectors | Add Text Studio while preserving source, font, layout, material, and renderer role. | Adopt an Existing TextMeshPro Object |
Gallery | Search effects and inspect real rendered starting points. | Learn Through the Samples; Effect Gallery |
Recipes | Focused copyable setups for dialogue, HUD, long text, audio, markers, and integrations. | Common Game Scenarios |
Examples | Numbered learning path and sample map. | Learn Through the Samples |
Welcome | First-run navigation and package verification. | Requirements, Installation, and Verification |
Health Check | Project setup, missing resources, renderers, event systems, integrations, and clickable asset or scene-object results. | Start with Health Check |
Migration | Reviewed conversion report and staged Text Animator project migration. | Move an Existing Project to Text Studio |
Effect Code | Portable treatment payload, dependencies, conflict handling, and import safety. | Effect Code |
Preview export | Real renderer, camera, quality, motion, and platform format behavior. | Preview Export |
Inspector coverage, part 5 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
UI Toolkit adapters | AnimatedLabel, binding, automatic or manual scheduling, and panel lifecycle. | UI Toolkit |
Runtime public API | Text, reveal, waits, visibility, external effects, registration, and transient views. | Essential Scripting API |
External Effect Driver | One exact effect, Progress, Intensity, All Text or inclusive Glyph Range, and ordered clock-free submission. | Drive Effects from External Time |