<cat>UI.Intro</cat> <title>UI Basics</title> # Basics UI entities are implemented using HTML and/or C#. Entities can be styled using SCSS, a preprocessor scripting language that is interpreted/compiled into Cascading Style Sheets (CSS). This is done out of the box. # Simple Static UI For static UIs where nothing is dynamically changed (static banner, simple non-changing crosshair, etc.), HTML UI might be sufficient. You can still reference C# classes within the HTML using regular HTML-Tags. The referenced C# classes can still react dynamically to the game loop. ## Example: Static crosshair w/ dynamic C# chatbox ```html <link rel="stylesheet" href="minimalhud.scss"> <div> <text class="title">My Minimal Game</text> <!-- A crosshair in just css --> <div style="position: absolute; left: 50%; top: 50%; background-color: white; border-radius: 10px; width: 4px; height: 4px; transform: translate( -50% -50% );"></div> <chatbox></chatbox> </div> ``` # Hybrid UI A hybrid UI will give you the readability of HTML and CSS whilst allowing you to also leverage the power of C#. If you wanted to interact with the above template in C#, you might save it as MinimalHUD.html, and then create another file called MinimalHUD.cs. Add the UseTemplate attribute to the file and it will automatically pair itself with the .html file. ```cs [UseTemplate] public class MinimalHUD : RootPanel { // Do stuff. } ``` To reference stuff from C#, use the ref attribute: ```html <Label @ref="MyTimerLabel">0</Label> ``` ```cs public Label MyTimerLabel { get; set; } // This must be a property. [Event.Tick] public override void Tick() { MyTimerLabel.SetText( Sandbox.Time.Now.ToString() ); } ``` S&Box supports some GUI elements in both HTML mark-up and C#. For example: ```html <Panel class="my-panel"> <Image src="/materials/ui/cool_image.jpg"></Image> <Label>This is my cool image</Label> </Panel> ``` # Dynamic UI # Creating UI ⤶ To create a UI all you need to do is create an instance of your UI class on the clientside.⤶ ⤶ ```cs⤶ ⤶ [ClientRpc]⤶ public void CreateUI() {⤶ var ui = new ExampleUserInterface();⤶ }⤶ ⤶ ```⤶ ⤶ ⤶ # Dynamic UI⤶ For more complex scenarios where you want to dynamically change elements, use of C# will be necessary. A pure C# UI is also quicker to prototype. However, it can quickly become spaghetti code if abused. UI components can be implemented using the abstract class `Panel`. This abstract class has a method `override void Tick()` so you can access the game loop. UI components can either be mounted directly or through other UI Components using `RootPanel.AddChild<E>();`. Usually done in the constructor of the class. To add (S)CSS to the components, simply use `RootPanel.StyleSheet.Load( "/ui/PATH_TO_SCSS.scss" );` in the constructor. ## Example: HUD w/ health display Down below you can see an example from the sandbox gamemode. `SandboxHud` implements the `HudEntity<RootPanel>` class and loads a stylesheet and all other UI components. The `Health` class implements `Panel` and adds a bunch of stuff to the UI within its constructor. It also has access to the local player's health within the `Tick`-override, so the UI can be updated accordingly. ```cs using Sandbox; using Sandbox.UI; [Library] public partial class SandboxHud : HudEntity<RootPanel> { public SandboxHud() { if ( !IsClient ) return; RootPanel.StyleSheet.Load( "/ui/SandboxHud.scss" ); RootPanel.AddChild<NameTags>(); RootPanel.AddChild<CrosshairCanvas>(); RootPanel.AddChild<ChatBox>(); RootPanel.AddChild<VoiceList>(); RootPanel.AddChild<KillFeed>(); RootPanel.AddChild<Scoreboard<ScoreboardEntry>>(); RootPanel.AddChild<Health>(); RootPanel.AddChild<InventoryBar>(); RootPanel.AddChild<CurrentTool>(); RootPanel.AddChild<SpawnMenu>(); } } ``` Source: [sandbox - SandboxHud.cs](https://github.com/Facepunch/sandbox/blob/0ae8ada7fae4b3876fd3d82d0385fa72dbacbf6f/code/ui/SandboxHud.cs) ```cs using Sandbox; using Sandbox.UI; using Sandbox.UI.Construct; public class Health : Panel { public Label Label; public Health() { Label = Add.Label( "100", "value" ); } public override void Tick() { var player = Local.Pawn; if ( player == null ) return; Label.Text = $"{player.Health.CeilToInt()}"; } } ``` Source: [sandbox - Health.cs](https://github.com/Facepunch/sandbox/blob/69b8565a78b646520c47463a33ee2fa85d726762/code/ui/Health.cs) # Troubleshooting Panels If a panel is not behaving as expected you can troubleshoot it using the Panel Inspector. First, in the S&box editor, make sure the Panel Inspector is enabled by ticking View->Panels. <upload src="b0cef/8da8cf24eac2629.png" size="13513" name="image.png" /> If you run the game in the editor you will then be able to inspect panels in real-time. <upload src="b0cef/8da8cf2a67adf22.png" size="363249" name="image.png" /> <upload src="b0cef/8da8cf2a67adf22.png" size="363249" name="image.png" />