menu_bookDocumentation

TextRenderer: 3D World Text, TextScope, Localization via # Prefix, Scale vs FontSize, and JsonUpgrader Pattern

calendar_today May 4, 2026 schedule ~1 min read person patrickjr verified 50

TextRenderer: 3D World Text with Localization Support

TextRenderer renders text in 3D world space using TextRendering.Scope for font configuration.

Basic Usage

CSHARP
var tr = AddComponent<TextRenderer>();
tr.Text = "Hello World";
tr.Color = Color.White;
tr.FontSize = 32f;
tr.FontFamily = "Poppins";
tr.FontWeight = 400;
tr.Scale = 1.0f;  // world-space scale multiplier

TextScope

The TextScope property controls all text appearance:

CSHARP
tr.TextScope = new TextRendering.Scope( "Hello!", Color.White, 32.0f, "Poppins", 400 );

Alignment

CSHARP
tr.HorizontalAlignment = TextRenderer.HAlignment.Center;  // Left, Center, Right
tr.VerticalAlignment = TextRenderer.VAlignment.Center;    // Top, Center, Bottom

Rendering Options

CSHARP
tr.BlendMode = BlendMode.Normal;  // or Additive, etc.
tr.FogStrength = 1.0f;            // [0..1] fog blending

Localization

If the text starts with #, it's treated as a localization key:

CSHARP
tr.Text = "#ui.score";  // looks up Game.Language.GetPhrase( "ui.score" )

Scale vs FontSize

  • FontSize controls the resolution of the rendered text (higher = sharper at close range)
  • Scale controls the physical size in world units
For crisp text at a distance, use a larger FontSize and smaller Scale.

JsonUpgrader

TextRenderer has two version upgraders (v1, v2) that migrate old serialized data. The [JsonUpgrader] attribute is the s&box mechanism for migrating component data across versions:
CSHARP
[Expose, JsonUpgrader( typeof( TextRenderer ), 1 )]
static void Upgrader_v1( JsonObject obj )
{
    // migrate old properties to new TextScope format
}

This pattern is used throughout the engine for backwards-compatible component serialization.

Was this helpful?