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 Prefab Spawners, Outgoing Glyph Motion, and Module Inputs.
Customer-facing windows include 3D Gallery, Style Browser, Style Compare, Material Set Browser, Live 3D Preview, 3D Authoring Glossary, and Build Preparation. Build Readiness 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.AutomaticLOD = true;
sign.RebuildGeometry();
}
Prewarm and pool
PrewarmGlyphs warms reusable geometry without changing the visible mesh and reports whether the current configuration is renderer-specific. 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.
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.
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.
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, Build Readiness, 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, Build Readiness, and Build Preparation: authoritative typography, technical outlines, exact coverage, runtime policy, and reusable geometry.
- 3D Modules: ordered Layout Transform, Deformer Stack, Glyph Prefab Spawner, Outgoing Glyph Motion, 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 DeepSignal: 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, Build Readiness, 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 |
Build 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 Prefab Spawner | Pooled prefab per rendered glyph, lifecycle trigger, semantic or named socket, Trigger 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; 80-Style Gallery |
Material Set Browser | Browse reusable looks and inspect region assignments before applying. | Material Sets; Learn From the Shipped Samples |
Outgoing Glyph Motion | Bounded Batched or Rigidbody motion for retained glyphs during Overlap Handoff, with one motion driver per host. | 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, and world-space ray input. | 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 |