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 effect only when built-in tags and Composed Effects cannot express the result. Declare its channels, phases, 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.
External effects
ApplyExternalEffect submits one renderer-neutral layer for the current evaluated frame. Submit it every frame while active. Progress and intensity are clamped. Omitted glyph bounds address all visible glyphs, explicit bounds are inclusive, invalid requests return false, and accepted layers run in submission order after ordinary effects.
void Update()
{
float progress = Mathf.Repeat(Time.time, 1f);
text.ApplyExternalEffect(effect, progress, 1f);
}
UI Toolkit essentials
Use TextStudioAnimatedLabel in UXML or TextStudioUITKBinding for 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.
TextStudioUITKBinding 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: Content, Typewriter, Placement, Events, Debug, and Preview.
- TextStudioProfile: default effects, typewriter recipe, source ownership policy, and reusable object defaults.
- TextStudioTypewriterPreset and Motion Preset: reusable pacing, lifecycle, motion, skip, wait, and hide behavior.
- CharacterTimings and WordTimings: delay and punctuation rules.
- TextStudioComposedEffectAsset: ordered layers, phases, curves, playback, scope, influence, sharing, and preview.
- Effect Curve and Effect Playback: reusable progress and time envelopes.
- TextStudioMarkupSyntax and Tag Expansion Sheet: authoring grammar and project vocabulary.
- TextStudioAudioSet, Audio Player, Play Sound assets and components: glyph, marker, and authored sound behavior.
- Marker Event Router, Typewriter Event Relay, Dialogue Source, Page Navigator, and Auto Scroll Follower: production flow helpers.
- Project Settings, Health Check, Migration, Gallery, Recipes, Tag Browser, and Effect Code: project-wide authoring and diagnostics.
Inspector coverage, part 1 of 5
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, phase selection, speed, repeat, scrub, skip, hide, waits, and renderer preview. | Authoring modes; runtime model; preview and export |
Content tab | Source, profile, default effects, markup help, backend state, and diagnostics. | Markup; effects; profiles; backends |
Typewriter tab | Reveal 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 Spatial Effect Target. | 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 and Shared Settings |
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; Profiles |
TextStudioTypewriterMotionPreset | Reusable reveal or hide motion without changing timing. | Reveal and Hide Motion |
TextStudioProfile | Default effects, typewriter recipe, source ownership, and restored local overrides. | Reuse Your Work |
TextStudioProjectSettings | Catalogs, syntax, expansion sheets, defaults, motion policy, and validation. | Project and Shared Settings |
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 |
TextStudioEffectAsset | Reusable effect parameters and renderer compatibility. | 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, and integration health. | 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 |