Troubleshooting and Reference
Nothing Appears
Read Setup Status first. Confirm the base Text Studio component exists, the active text backend has a font with usable TTF or OTF outlines, at least one layer is enabled, the front face is closed when a visible cap is expected, and the current render pipeline has valid materials.
Geometry Looks Wrong
Use Live Preview diagnostics for material regions, normals, contour direction, bounds, wireframe, and sockets. Temporarily disable depth sweep, deformers, contour programs, and decorations until the responsible stage is clear.
Animation Is Expensive
Begin with the Realtime or Massive Text profile. Prefer combined or chunked output. Lower rebuild-heavy Contour Bloom and Bevel Pulse frequency before reducing ordinary transform effects. Use Runtime Statistics only while diagnosing.
Asset and Window Reference
Customer-facing assets include 3D Themes, Project Theme Settings, Control Themes, 3D Styles, technical Font3D data, Bevel Profiles, extrusion paths, contour assets, generated contours, contour programs, tube profiles, Material Sets, spatial placements, Layout Transform modules, Deformer Stacks, Glyph Decorations, Module Inputs, and Shader Contracts.
Customer-facing windows include 3D Gallery, 3D Render Studio, Style Browser, Style Compare, Material Set Browser, Live 3D Preview, 3D Authoring Glossary, and Runtime Preparation. Runtime Preparation in the main inspector connects the selected object directly to the preparation workflow.
Support
Include the Unity version, render pipeline, Text Studio and Text Studio 3D versions, active backend and font, style or layer asset, performance profile, a screenshot of Setup Status, and a minimal scene when requesting support.
Essential Scripting API
TextStudio3DText is the primary runtime facade. Use property setters for normal configuration, ApplyPreset or ApplyPerformanceProfile for a starting point, RebuildGeometry after in-place asset edits, and ScheduleGeometryBuild when several topology edits should coalesce. Unity object and mesh operations are main-thread work.
using TextStudio.ThreeD;
void ConfigureSign(TextStudio3DText sign)
{
sign.ApplyPreset(BuiltInExtrudeStyles.Preset.Bevelled);
sign.ApplyPerformanceProfile(TextStudio3DPerformanceProfile.Realtime);
sign.ChunkGlyphEntries = 24;
sign.RebuildGeometry();
}
Prewarm and Pool
PrewarmCharacters warms reusable geometry without changing the visible mesh and reports whether the current configuration is renderer-specific; PrewarmCurrentOutput warms exactly the glyphs the active backend currently shows. TextStudioEmitter owns complete temporary 3D hosts, prewarms registered presets, and returns each host only after its normal Hide lifecycle. Use TextStudio3DControlPool only for repeating interactive control prefabs.
emitter.Prewarm();
TextStudioEmissionHandle hit =
emitter.EmitValue(damagePreset, amount, target);
// Optional runtime update or manual dismissal:
hit.SetValue(updatedAmount);
hit.Dismiss();
Runtime Overrides and Topology
Visibility, tint, compatible material changes, and supported visual channels can update without rebuilding topology. Changes to text, outline source, contours, bevels, body, sweep, decorations, grouped geometry, or topology modules require a build. ScheduleGeometryBuild returns one coalesced request whose state can be queried or canceled before dispatch.
Glyph Handles, Ranges, Raycasts, and Materials
TryGetGlyphHandle resolves by visible Text Studio glyph identity and optionally authored layer. A handle becomes stale after topology changes. Use current handles or TextStudio3DGlyphRange for tint, material, and socket commands. EnsureMeshCollider after topology changes before RaycastGlyph.
renderer.EnsureMeshCollider();
if (renderer.RaycastGlyph(ray, 50f, out TextStudio3DGlyphHandle handle,
out MaterialRegion region, out RaycastHit hit))
{
renderer.SetGlyphColorTint(handle, new Color32(255, 180, 40, 255));
}
SetGlyphMaterial works on Per Letter and Physical outputs because those modes own independent renderers. Region-targeted overloads can address Front Face, bevels, sides, back, trim, or Decorations. For Combined output use color tint or material-channel effects unless the complete mesh material assignment is being changed.
For exact hits without a MeshCollider, use surface queries. AcquireSurfaceAccess returns a TextStudio3DSurfaceAccess that keeps the queried geometry available. RaycastSurface tests the geometry currently on screen, including physical letters and supported deformation, and returns a TextStudio3DSurfaceHit with the glyph, layer, material region, pose, and a surface reference; hits use the submitted geometry, so transparency and alpha clipping are not considered. Pass the reference to TryCreateSurfaceAttachment to keep a point that follows the letter, or to TryEvaluateSurface for its current pose. Dispose the access and any attachments when finished. A real topology change, such as new text, invalidates stored references, and while access is held, Automatic Quality keeps the authored mesh.
Physical Letters and Sockets
ReleasePhysicalLetters and ResetPhysicalLetters act only on explicitly selected Physical Letters output. TryGetPhysicalBody resolves one logical Rigidbody per visible glyph. Named sockets provide stable attachment points without exposing generated hierarchy details.
GetOutputRenderers fills a list you provide with the renderers the current output mode generated, and GetLetterAnchors fills one with the Hybrid letter anchors; both return the count.
Authoring Assets and Extension Points
Supported authoring contracts include Font3D, Extrude3DStyle, TextStudio3DLayer and its nine specifications, BevelProfile, contour assets and programs, tube profiles, Material Sets, extrusion path assets, module interfaces, style compilation, and explicit geometry validation. Internal generators, caches, renderer bookkeeping, pooled chunks, and the embedded polygon library are not customer APIs.
A custom text backend can call HasPublishedShapedGeometry with its backend and canonical text to learn when 3D geometry for its current shaped revision has been published, including when shaping finishes asynchronously.
Inspector and Asset Reference
- TextStudio3DText inspector: Setup Status, 3D Style, Mesh Detail, Live 3D Preview, Depth Extrusion Sweep, Mesh Output, Performance, Physical Letters, Glyph Sockets, 3D Modules, Runtime Statistics, Runtime Preparation, and Static Output.
- 3D Style and Layer inspector: nine specifications, layer ordering, selection, scope, Stack or Overlay, and validation.
- Style Compare: isolated current and candidate viewports, Prev or Next and dropdown navigation, Keep Materials, effort summary, and explicit Apply.
- Material Set and surface mapping: semantic regions, render-pipeline material families, and coordinate projection.
- Spatial Placement, spatial fields, and Extrusion Path assets: glyph baseline, per-glyph effect strength, and front-to-back sweep as distinct systems.
- Font Source, Font3D, Runtime Preparation, and Runtime Preparation: authoritative typography, technical outlines, exact coverage, runtime policy, and reusable geometry.
- 3D Modules: ordered Layout Transform, Deformer Stack, Glyph Decoration, Module Inputs, and custom extension metadata.
- Spatial UI: Panel, Spatial Menu, controls, Spatial Keyboard, Reposition Handle, themes, navigation, layouts, option presentation, pools, and optional input adapters.
- Gallery, browsers, Live 3D Preview, 3D Authoring Glossary, Examples, and 3D Render Studio: customer authoring, learning, diagnostics, and production reference.
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudio3DText main inspector | Setup, style, geometry, output, quality, Physical Letters, 3D Modules, statistics, Runtime Preparation, actions, and static output. | First 3D result; geometry model; animation; modules; build preparation; output |
Extrude3DStyle | Shared layer stack, local detachment, order, Stack or Overlay, selection, Solo, and reset. | Geometry model; Build a Style Layer by Layer |
TextStudio3DMaterialSet | Assignments for the nine semantic regions without changing geometry or mapping. | Design Materials and Surfaces |
BevelProfile | Profile graph, anchors, tangents, samples, smoothing, snapping, mirroring, and handles. | Bevel Profiles and Bevel Profile Assets |
QuadraticBezierExtrusionPathAsset | Start, control, end, sampling, banking, roll, taper, and closed state. | Placement Versus Extrusion Sweep |
SplineExtrusionPathProvider | Container, curve index, seed up, banking, roll, scale, samples, refresh, and snapshot. | Unity Splines Extrusion; 3D Integrations |
TextStudio3DContourAsset | Validated custom vector loops and contour identity. | Choose a Contour Source; SVG Import |
TextStudio3DGeneratedContourAsset | Rounded rectangle, pill, plate, shield, badge, banner, and frame generation. | Generated Contours |
TextStudio3DContourProgram | Input source plus ordered union, subtraction, intersection, and clipping operations. | Build a Contour Program |
TextStudio3DContourTubeProfile | Reusable validated closed section for contour tubes. | Contour Tubes |
Inspector coverage, part 2 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudio3DSpatialPlacement | Helix, cylinder, sphere band, tunnel, staircase, spatial grid, orientation, and presets. | Arrange Text in Space |
Physical Letters | One logical Rigidbody per visible glyph, child layer meshes and colliders, explicit release and reset, and scripting body access. | Animate 3D Text and Use Physical Letters |
Font3D | Hidden technical outline identity, coverage, fallbacks, and generated runtime data matching the authoritative Text Object or explicit Theme font. | Prepare Fonts, Glyphs, and Builds |
Runtime Preparation | Generate if missing or Prepared only policy, Selected text or Project coverage, shaped-glyph readiness, font data, and reusable geometry. | Prepare Fonts, Glyphs, and Builds |
Layout Transform Module | Curve-weighted position, rotation, and scale after base placement, in Per Glyph or Whole Text scope, with optional Float input. | Use 3D Modules |
Deformer Module | Ordered topology-preserving Bend, Arc, Shear, Pinch, Flare, Spherize, Wrap, Wave, Noise, and Twist with spaces, bounds, and falloff. | Use 3D Modules |
Glyph Decoration | Pooled prefab per rendered glyph, semantic or named socket, Topology Pose or Follow Glyph, delay, lifetime, and bounds. | Use 3D Modules |
Module Inputs | Case-insensitive named values with exact Float, Integer, Boolean, String, Color, Vector, Curve, Gradient, or Object types. | Use 3D Modules |
3D Gallery and Style Compare | Search, compare, apply, duplicate, detach, and validate real style recipes. | Learn From the Shipped Samples; Built-In Style Reference |
Material Set Browser | Browse reusable looks and inspect region assignments before applying. | Material Sets; Learn From the Shipped Samples |
Outgoing Letter Reactions | Text Changed Reactions on Changed Outgoing Units that move retained glyphs with Tween Retained Motion or Ballistic Retained Motion during Overlap Handoff. | Use 3D Modules |
Inspector coverage, part 3 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
Freeze and Frozen Snapshot | Persistent static output, ownership, validation, unfreeze consequences, and player stripping. | Freeze a Finished Title |
Runtime Statistics | Glyph, entry, vertex, triangle, mesh, renderer, material, cache, and rebuild state. | Runtime Statistics |
Glyph Sockets | Center, front, back, top, bottom, and contour-fraction attachment poses. | Named Glyph Sockets |
Module3DBase | Typed roles, stages, priority, channels, cache and geometry impact, bounds, lifecycle, outgoing participation, and material-region registration. | Use 3D Modules; Developer Reference |
Mesh export | Output ownership, real generated mesh, materials, pipeline family, and validation. | Strict Freeze; Output and Performance |
TextStudio3DButton | Click behavior plus Normal, Hover, Focused, Pressed, Selected, Disabled, Error, validation, and accessibility states. | Build Spatial Interfaces |
TextStudio3DToggle | Boolean value, state visuals, callbacks, and navigation. | Buttons, Toggles, Sliders, Lists, and Selectors |
TextStudio3DSlider | Range, value, step, visual fill, callbacks, and pointer or navigation input. | Buttons, Toggles, Sliders, Lists, and Selectors |
TextStudio3DList | Items, selection, navigation, events, and pooled presentation. | Buttons, Toggles, Sliders, Lists, and Selectors |
TextStudio3DInputField | Value, placeholder, length, validation, focus, caret, and optional keyboard path. | Input Field |
Inspector coverage, part 4 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
TextStudio3DSelector | Option value, previous or next input, display, and change events. | Build Spatial Interfaces |
TextStudio3DPointerRaycaster | Camera, layers, distance, hover, press, selection, world-space ray input, and optional exact label geometry. | Build Spatial Interfaces |
TextStudio3DNavigationGroup | Ordered focus traversal and independent selected value. | Build Spatial Interfaces |
TextStudio3DControlLayout | Linear, grid, circular, spline, or volume placement with shared spacing and orientation. | Build Spatial Interfaces |
TextStudio3DControlTheme | Shared label, surface, depth, scale, and interaction-state treatment. | Build Spatial Interfaces |
TextStudio3DControlPool | Bounded prefab reuse with restored value, validation, focus, events, and framing. | Build Spatial Interfaces |
TextStudioEmitter | Shared temporary host emission with profiles, values, stacking, following, prewarming, lifecycle events, and bounded pooling. | Prewarming and Bounded Caches |
3D Authoring Glossary | Product vocabulary for layers, contours, surfaces, paths, output, caches, and modules. | Troubleshooting and Reference |
Input System integration | Action-reference mappings for pointer, navigation, submit, and text entry. | 3D Integrations |
XR Interaction Toolkit integration | XR hover, select, ray, and lifecycle bridge for world-space controls. | 3D Integrations |
Inspector coverage, part 5 of 5
Inspector or surface | Controls and ownership | Primary manual coverage |
|---|---|---|
UniText 3D sample | Shaped mixed-script text converted into matching 3D outlines with durable glyph identity. | Prepare Fonts, Glyphs, and Builds; Optional Integrations |
Unity Splines integration | Base spatial placement plus guarded depth-extrusion provider. | Placement Versus Extrusion Sweep; 3D Integrations |
Runtime public API | Presets, output, rebuild, prewarm, pools, overrides, handles, raycasts, regions, and sockets. | Essential Scripting API |