menu_bookDocumentation
ScreenPanel and WorldPanel: AutoScale Strategies, ZIndex, LookAtCamera, and Interaction Range
ScreenPanel and WorldPanel: UI Components in s&box Scenes
ScreenPanel
ScreenPanel is the root component for 2D screen-space UI. It renders attached PanelComponent children to the screen.CSHARP
// ScreenPanel properties
screenPanel.Opacity = 1.0f; // [0..1] overall opacity
screenPanel.Scale = 1.0f; // manual scale multiplier
screenPanel.AutoScreenScale = true; // auto-scale based on screen size
screenPanel.ScaleStrategy = ScreenPanel.AutoScale.ConsistentHeight; // or FollowDesktopScaling
screenPanel.ZIndex = 100; // render order (higher = on top)
screenPanel.TargetCamera = myCamera; // which camera to render to (null = main camera)AutoScale Strategies
- ConsistentHeight — scales so that 1080px height always looks the same size. Scale = screenHeight / 1080. This is the most common choice.
- FollowDesktopScaling — uses the OS desktop DPI scale. Respects Steam Deck's 1.333x scale and VR's 2.33x scale.
Rendering
ScreenPanel is rendered by the CameraComponent in OnCameraRenderUI. It renders all ScreenPanel components sorted by ZIndex. A ScreenPanel only renders to its TargetCamera (or the main camera if TargetCamera is null).WorldPanel
WorldPanel renders UI in 3D world space. It creates a Sandbox.UI.WorldPanel in the SceneWorld.CSHARP
worldPanel.PanelSize = new Vector2( 512, 256 ); // size in screen pixels
worldPanel.RenderScale = 1.0f; // scale of the panel in world space
worldPanel.LookAtCamera = true; // billboard toward camera
worldPanel.InteractionRange = 1000f; // max distance for mouse interaction
worldPanel.HorizontalAlign = WorldPanel.HAlignment.Center;
worldPanel.VerticalAlign = WorldPanel.VAlignment.Center;LookAtCamera
When LookAtCamera = true, the panel rotates to face the active camera each OnPreRender. The rotation uses the camera's Up vector to avoid tilting.
Interaction
WorldPanel supports mouse interaction up to InteractionRange units. Beyond that distance, mouse events are not processed.PanelComponent
Both ScreenPanel and WorldPanel host PanelComponent children. PanelComponent is the base class for Razor UI components in the scene hierarchy.
CSHARP
// Add a Razor component to a ScreenPanel
var go = new GameObject( true, "HUD" );
go.AddComponent<ScreenPanel>();
go.AddComponent<MyHudComponent>(); // extends PanelComponent
Was this helpful?