S&box

https://sbox.game/dev/doc/
Admin
S&box is a game development engine built on Source 2 that uses C# for coding games and addons,...
Tokens:112,094
Snippets:1,608
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start server on Linux

Source: https://sbox.game/dev/doc/networking/dedicated-servers

Create a shell script to launch the server; requires the .NET runtime installed.

```bash
#!/bin/bash
./sbox-server.exe +game facepunch.sandbox facepunch.flatgrass +hostname "My Dedicated Server"
```

--------------------------------

### Create and Start Recording

Source: https://sbox.game/dev/doc/movie-maker/recording-api

Create a MovieRecorder with default options and start capturing the scene every fixed update.

```csharp
var recorder = new MovieRecorder( Scene );

recorder.Start();
```

--------------------------------

### Use and Configure Panels

Source: https://sbox.game/dev/doc/ui/razor-panels

Examples of instantiating a custom panel and passing properties to it.

```csharp
<MyChildPanel />
```

```csharp
<MyChildPanel Health=@(30) Armor=@(75) />
```

--------------------------------

### Storage.QueryItem.Install

Source: https://sbox.game/dev/doc/assets/storage-ugc

Downloads and installs a specific workshop item to the local machine.

```APIDOC
## Storage.QueryItem.Install()

### Description
Downloads the workshop item associated with the QueryItem and returns a local Storage.Entry. The resulting entry is read-only.

### Returns
- **Storage.Entry** - The installed entry, or null if the installation failed.
```

--------------------------------

### Start server on Windows

Source: https://sbox.game/dev/doc/networking/dedicated-servers

Create a .bat file to launch the server with specific game, map, and hostname parameters.

```batch
echo off
sbox-server.exe +game facepunch.sandbox facepunch.flatgrass +hostname My Dedicated Server
```

--------------------------------

### Installing Workshop Items

Source: https://sbox.game/dev/doc/assets/storage-ugc

Downloads and accesses a workshop item locally. Note that installed workshop entries are read-only.

```csharp
// From a query result
var query = new Storage.Query { TagsRequired = { "save" } };
Storage.QueryResult result = await query.Run();
Storage.QueryItem chosenItem = result.Items.First();

// Install the workshop item
Storage.Entry entry = await chosenItem.Install();
if ( entry == null ) throw new Exception( "Failed to install the chosen item." );
		
// The entry is now available locally
Log.Info( $"Installed: {entry.Type} - {entry.Id}" );

// Read its metadata
var playerName = entry.GetMeta<string>( "playerName" );

// Access its files (read-only)
if ( entry.Files.FileExists( "player.json" ) )
{
	var data = entry.Files.ReadAllText( "player.json" );
	// Load the save...
}

// Workshop entries are read-only
if ( entry.Files.IsReadOnly )
{
	Log.Info( "This is a workshop item (read-only)" );
}
```

--------------------------------

### Establish WebSocket Connection and Send Messages

Source: https://sbox.game/dev/doc/networking/websockets

Implement a component to manage WebSocket connections. Ensure the connection is initiated on game start and handle incoming messages by logging them. This snippet demonstrates basic connection setup and message sending.

```csharp
public sealed class Server : Component
{
	// Example: wss://host.example:443/ws
	[Property] public string ConnectionUri { get; set; }
	public WebSocket Socket { get; set; }

	protected override void OnStart()
	{
		Socket = new WebSocket();
		Socket.OnMessageReceived += HandleMessageReceived;
		_ = Connect();
	}

	// Connect to the server and send a message
	private async Task Connect()
	{
		await Socket.Connect( ConnectionUri );
		await SendMessage( "Hello!" );
	}

	private async Task SendMessage( string message )
	{
		await Socket.Send( message );
	}

	// Log our received messages
	private void HandleMessageReceived( string message )
	{
		Log.Info( message );
	}
}
```

--------------------------------

### Implementing ISceneStartup in a GameObjectSystem

Source: https://sbox.game/dev/doc/scene/components/events/iscenestartup

Example of implementing ISceneStartup within a GameObjectSystem to handle scene loading and lobby creation during host initialization.

```csharp
public sealed class MyGameManager : GameObjectSystem<MyGameManager>, ISceneStartup
{
	public MyGameManager( Scene scene ) : base( scene )
	{
	}

	void ISceneStartup.OnHostInitialize()
	{
		//
		// We don't have a menu, but if we did we could put something in the menu
		// scenes that we'd now be able to detect, and skip doing the stuff below.
		//

		//
		// Spawn the engine scene.
		// This scene is sent to clients when they join.
		//
		var slo = new SceneLoadOptions();
		slo.IsAdditive = true;
		slo.SetScene( "scenes/engine.scene" );
		Scene.Load( slo );

		// If we're not hosting a lobby, start hosting one
		// so that people can join this game.
		Networking.CreateLobby();
	}
}
```

--------------------------------

### Retrieving Components

Source: https://sbox.game/dev/doc/scene/scenes

Use GetAll to iterate over all components of a specific type or Get to retrieve a singleton instance.

```csharp
// Tint all models a random colour
foreach ( var model in Scene.GetAll<ModelRenderer>() )
{
	model.Tint = Color.Random;
}

// Grab your singleton
var game = Scene.Get<GameManager>();
```

--------------------------------

### Implement BaseGameMount for a New Game

Source: https://sbox.game/dev/doc/game-mounts/creating-mounts

Extend `BaseGameMount` to detect a game's installation via Steam and register its resources. Implement `Initialize` for detection and `Mount` for scanning and adding resources.

```csharp
public class MyGameMount : BaseGameMount
{
    public override string Ident => "rust";
    public override string Title => "Rust";

    private string GameDir;

    protected override void Initialize( InitializeContext context )
    {
        // Check if the game is installed via Steam
        if ( !context.IsAppInstalled( 252490 ) )
            return;

        GameDir = context.GetAppDirectory( 252490 );
        IsInstalled = true;
    }

    protected override Task Mount( MountContext context )
    {
        // Scan game files and register each resource
        foreach ( var file in Directory.GetFiles( GameDir, "*.mymodel", SearchOption.AllDirectories ) )
        {
            var relative = Path.GetRelativePath( GameDir, file );
            context.Add( ResourceType.Model, relative, new MyModelLoader( this, file ) );
        }

        IsMounted = true;
        return Task.CompletedTask;
    }
}
```

--------------------------------

### Basic Recording

Source: https://sbox.game/dev/doc/movie-maker/recording-api

Demonstrates how to create a MovieRecorder with default settings, start recording, stop recording, and convert the recording to a MovieClip.

```APIDOC
## Basic Recording

### Description
This snippet shows the fundamental usage of the `MovieRecorder` class for capturing scene data.

### Code
```csharp
// Create a recorder using the default capturing options
var recorder = new MovieRecorder( Scene );

// Start capturing
recorder.Start();

// ... recording happens ...

// Stop capturing
recorder.Stop();

// Convert the recording to a MovieClip
var clip = recorder.ToClip();

// Play the clip!
GetComponent<MoviePlayer>().Play( clip );

// Save it to a .movie
FileSystem.Data.WriteJson( $"movies/example.movie", clip.ToResource() );
```
```

--------------------------------

### Install or update s&box server via SteamCMD

Source: https://sbox.game/dev/doc/networking/dedicated-servers

Run this command from the SteamCMD directory to download or update the dedicated server files.

```bash
./steamcmd +login anonymous +app_update 1892930 validate +quit
```

--------------------------------

### Custom Toon Shading Model Example

Source: https://sbox.game/dev/doc/rendering/shaders/shading-model

An example of a custom toon shading model, demonstrating the segmentation of direct/indirect and specular/diffuse lighting calculations. This is useful for achieving unique art styles.

```csharp
class ShadingModelToon
{
    static float4 Shade( Material m )
    {
        float4 color = 0;
        
        // Direct Lighting
        for( int i=0; i < DynamicLight::Count(); i++ )
        {
            Light l = DynamicLight::From( ScreenPosition, WorldPosition, i );
            ...
            
            float3 diffuse = /* */
            float3 specular = /* */
            
            color += diffuse + specular;
        }
        
        // Indirect Lighting
        {
            float3 diffuse = 0;
            {
                diffuse = /* ambient light */
                diffuse *= min( m.AmbientOcclusion, ScreenSpaceAmbientOcclusion::Sample( m.ScreenPosition );
            }
            
            float3 specular = 0;
            {
                specular = /* envmap */
                specular += /* toon fresnel */
            }
            
            color += diffuse + specular;
        }
        
        if( DepthNormal::WantsDepthNormal() )
            return DepthNormal::Output( m );

        if( ToolVis::WantsToolVis() )
            return ToolVis::Output( color, m );

        // Composite atmospherics after lighting
        color.xyz = Fog::Apply( m.WorldPosition, m.ScreenPosition.xy, color );
        
        return color;
    }
}
```

--------------------------------

### Screen Space Tracing Usage Example

Source: https://sbox.game/dev/doc/rendering/shaders/classes/screen-space-tracing

Demonstrates how to use ScreenSpace::Trace to find a hit and apply a reflection color based on the hit confidence. Requires a copy of the framebuffer and a material.

```csharp
Texture2D FrameBufferCopy = /* .. */
Material m = /* .. */

float3 origin = /* world-space origin */;
float3 direction = /* world-space direction */;
float2 screenPos = /* screen-space position */;

TraceResult result = ScreenSpace::Trace(origin, direction, screenPos);

if (result.ValidHit)
{
    float3 vReflectionColor = FrameBufferCopy[ trace.HitClipSpace.xy ].rgb;
    m.Emission = lerp( m.Emission, vReflectionColor, result.Confidence );
}
```

--------------------------------

### Leaderboard API Example Request and Response

Source: https://sbox.game/dev/doc/services/leaderboards/web-api

A sample request URL and the corresponding JSON response structure for a leaderboard query.

```none
https://public.facepunch.com/sbox/package/facepunch.ss1/leaderboard/zombies_killed/
```

```json
{
  "Stat": "zombies_killed",
  "TotalEntries": 2588,
  "Entries":
  [
    {
      "Rank": 1,
      "Value": 645806,
      "SteamId": 76561198043785940,
      "CountryCode": "us",
      "DisplayName": "puxorb",
      "Timestamp": "2024-08-23T03:44:17.0174014+00:00"
    },
    {
      "Rank": 2,
      "Value": 310250,
      "SteamId": 76561198053736750,
      "CountryCode": "au",
      "DisplayName": "Rin",
      "Timestamp": "2024-08-19T18:28:10.6930596+00:00"
    }
  ]
}
```

--------------------------------

### AssetSystem Event Listener Methods

Source: https://sbox.game/dev/doc/editor/editor-events

These are example method signatures for the AssetSystem.IEventListener interface, used to react to changes within the asset system.

```csharp
/// <summary>
/// An asset has been modified
/// </summary>
void OnAssetChanged( Asset asset ) { }

/// <summary>
/// The thumbnail for an asset has been updated
/// </summary>
void OnAssetThumbGenerated( Asset asset ) { }

/// <summary>
/// Changes have been detected in the asset system. We won't tell you what, but
/// you probably need to update the asset list or something.
/// </summary>
void OnAssetSystemChanges() { }

/// <summary>
/// Called when a new tag has been added to the asset system.
/// </summary>
void OnAssetTagsChanged() { }
```

--------------------------------

### Spawn Game Manager on Scene Startup

Source: https://sbox.game/dev/doc/getting-started/project-types/game-project

Implement ISceneStartup to spawn essential game elements like UI and managers when a map is loaded. This example shows how to load an additive scene containing engine components.

```csharp
public sealed class MyGameManager : GameObjectSystem<MyGameManager>, ISceneStartup
{
	public MyGameManager( Scene scene ) : base( scene )
	{
	}

	void ISceneStartup.OnHostInitialize()
	{
		var slo = new SceneLoadOptions();
		slo.IsAdditive = true;
		slo.SetScene( "scenes/engine.scene" );
		Scene.Load( slo );
	}
}
```

--------------------------------

### Test Camera Component

Source: https://sbox.game/dev/doc/code/advanced-topics/unit-tests

An example of testing a `CameraComponent` within a scene. This test verifies that the camera is correctly set up and removed.

```csharp
using Sandbox;

[TestClass]
public class Camera
{
	[TestMethod]
	public void MainCamera()
	{
		var scene = new Scene();
		using var sceneScope = scene.Push();

		Assert.IsNull( scene.Camera );

		var go = scene.CreateObject();
		var cam = go.Components.Create<CameraComponent>();

		Assert.IsNotNull( scene.Camera );

		go.Destroy();
		scene.ProcessDeletes();

		Assert.IsNull( scene.Camera );
	}
}
```

--------------------------------

### ResourceLibrary Event Listener Methods

Source: https://sbox.game/dev/doc/editor/editor-events

These are example method signatures for the ResourceLibrary.IEventListener interface, used to react to resource registration and modification events.

```csharp
/// <summary>
/// Called when a new resource has been registered
/// </summary>
void OnRegister( GameResource resource ) { }

/// <summary>
/// Called when a previously known resource has been unregistered
/// </summary>
void OnUnregister( GameResource resource ) { }

/// <summary>
/// Called when the source file of a known resource has been externally modified on disk
/// </summary>
void OnExternalChanges( GameResource resource ) { }

/// <summary>
/// Called when the source file of a known resource has been externally modified on disk
/// and after it has been fully loaded (after post load is called)
/// </summary>
void OnExternalChangesPostLoad( GameResource resource ) { }
```

--------------------------------

### Box Trace with Hitboxes

Source: https://sbox.game/dev/doc/physics/tracing

Perform a trace using a specified bounding box size and enable hitting of hitboxes. Ensure `start` and `end` are defined.

```csharp
var tr = Scene.Trace
	.Ray( start, end )
	.Size( new BBox( -5, 5 ) ) // size of the aabb
	.UseHitboxes( true ) // hit hitboxes too!
	.Run();
```

--------------------------------

### Implement OnLoad for asynchronous initialization

Source: https://sbox.game/dev/doc/scene/components/component-methods

Use this method for tasks that must complete before the game starts, such as procedural generation or asset loading. It executes even if the component is inactive, so check Component.Active if necessary.

```csharp
protected override async Task OnLoad()
{
	LoadingScreen.Title = "Loading Something..";
	await Task.DelayRealtimeSeconds( 1.0f );
}
```

--------------------------------

### Measuring Elapsed Time with Time.Now

Source: https://sbox.game/dev/doc/code/code-basics/time

Use Time.Now to get the total seconds since the scene started. This is useful for scheduling events or measuring durations. Time.Now is synchronized across the network.

```csharp
float startTime = Time.Now;

// later...
float elapsed = Time.Now - startTime;
Log.Info( $"It has been {elapsed} seconds" );
```

--------------------------------

### Initialize and play video with VideoPlayer

Source: https://sbox.game/dev/doc/media/video

Demonstrates creating a VideoPlayer instance, handling the load event, and playing a local video file.

```csharp
var player = new VideoPlayer();
player.OnLoaded += () => Log.Info( $"Loaded {player.Width}x{player.Height}" );
player.Play( FileSystem.Mounted, "videos/intro.webm" );
```

--------------------------------

### Get or Add Component

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Get a component if it exists, otherwise add it to the GameObject.

```C#
var c = go.GetOrAddComponent<ModelRenderer>();
```

--------------------------------

### Finding GameObject by Guid

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Find a GameObject in the scene using its unique identifier (Guid).

```C#
Scene.Directory.FindByGuid( guid );
```

--------------------------------

### Finding Objects by GUID

Source: https://sbox.game/dev/doc/scene/scenes

Access the scene directory to perform fast lookups of GameObjects using their unique GUID.

```csharp
var obj = Scene.Directory.FindByGuid( guid );
```

--------------------------------

### Configure Steam client DLLs on Windows

Source: https://sbox.game/dev/doc/networking/dedicated-servers

Add these registry commands to your startup script to point the server to the required SteamCMD client DLLs.

```powershell
New-Item -Path "HKCU:\SOFTWARE\Valve\Steam\ActiveProcess" -Force | Out-Null
Set-ItemProperty -Path "HKCU:\SOFTWARE\Valve\Steam\ActiveProcess" -Name "SteamClientDll64" -Value "$dir\steamclient64.dll" -Type String
Set-ItemProperty -Path "HKCU:\SOFTWARE\Valve\Steam\ActiveProcess" -Name "SteamClientDll" -Value "$dir\steamclient.dll" -Type String
```

--------------------------------

### Get Single Frame UVs for Texture Sheet

Source: https://sbox.game/dev/doc/rendering/shaders/classes/texture-sheets

Use Sheet::Single in the vertex shader to get updated UV coordinates for a specific frame in a texture sheet sequence. Pass the sheet data, sequence ID, and time to this function.

```csharp
float4 g_SheetData < Attribute( "BaseTextureSheet" ); >;

// ...

o.uv = Sheet::Single( g_SheetData, sequenceId, g_flTime, i.uv );
```

--------------------------------

### Play and Configure a Sound

Source: https://sbox.game/dev/doc/sound/playing-sounds

Use Sound.Play to initiate a sound and store the SoundHandle to modify properties like volume and pitch.

```csharp
SoundHandle _engineLoop;

void StartEngine()
{
    _engineLoop = Sound.Play( EngineLoopSound, WorldPosition );
    _engineLoop.Volume = 0.8f;
    _engineLoop.Pitch = 1.2f;
}
```

--------------------------------

### Getting the GameObject of a Component

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Retrieve the GameObject to which a component is attached.

```C#
var go = c.GameObject;
```

--------------------------------

### Configure Recorder with Options

Source: https://sbox.game/dev/doc/movie-maker/recording-api

Create a MovieRecorder with custom options to specify sample rate, filter GameObjects, and add capture actions.

```csharp
var options = new MovieRecorderOptions( SampleRate: 60 )
    .WithCaptureAll<Player>()
    .WithComponentCapturer<PlayerCapturer>()
    .WithCaptureAction( x => x
        .GetTrackRecorder( scoreManager )
        .Property( "Score" )
        .Capture() );
    
var recorder = new MovieRecorder( Scene, options );
```

--------------------------------

### Perform filesystem operations on an entry

Source: https://sbox.game/dev/doc/assets/storage-ugc

Demonstrates reading, writing, querying files, and managing directories within a storage entry's filesystem.

```csharp
// Write operations
entry.Files.WriteAllText( "notes.txt", "Player notes..." );
entry.Files.WriteAllBytes( "screenshot.png", imageBytes );
entry.Files.WriteJson( "data.json", myObject );

// Read operations
string notes = entry.Files.ReadAllText( "notes.txt" );
byte[] screenshot = entry.Files.ReadAllBytes( "screenshot.png" ).ToArray();
MyData data = entry.Files.ReadJson<MyData>( "data.json" );

// File queries
bool exists = entry.Files.FileExists( "notes.txt" );
var allFiles = entry.Files.FindFile( "/", "*", recursive: true );

// Directories
entry.Files.CreateDirectory( "levels" );
entry.Files.WriteAllText( "levels/level1.json", levelData );
```

--------------------------------

### GET https://public.facepunch.com/sbox/achievement/list

Source: https://sbox.game/dev/doc/services/achievements

Retrieve a list of achievements for a specific package.

```APIDOC
## GET https://public.facepunch.com/sbox/achievement/list

### Description
Access the list of achievements for a given package from outside the game.

### Method
GET

### Endpoint
https://public.facepunch.com/sbox/achievement/list

### Parameters
#### Query Parameters
- **package** (string) - Required - The unique identifier of the package to retrieve achievements for.
```

--------------------------------

### Initialize Engine for Game Tests

Source: https://sbox.game/dev/doc/code/advanced-topics/unit-tests

Set up the engine for tests that require engine functionality, such as testing components. This code initializes and cleans up the `AppSystem`.

```csharp
global using Microsoft.VisualStudio.TestTools.UnitTesting;

[TestClass]
public class TestInit
{
	public static Sandbox.AppSystem TestAppSystem;

	[AssemblyInitialize]
	public static void AssemblyInitialize( TestContext context )
	{
		TestAppSystem = new TestAppSystem();
		TestAppSystem.Init();
	}

	[AssemblyCleanup]
	public static void AssemblyCleanup()
	{
		TestAppSystem.Shutdown();
	}
}
```

--------------------------------

### Getting GameObject World Position

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Retrieve the world-space position of a GameObject.

```C#
var p = go.WorldPosition;
```

--------------------------------

### Getting a Component from a GameObject

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Retrieve a component of a specific type attached to a GameObject.

```C#
var c = go.GetComponent<ModelRenderer>();
```

--------------------------------

### Write Your First Unit Test

Source: https://sbox.game/dev/doc/code/advanced-topics/unit-tests

A basic unit test to verify simple assertions. Ensure the `Microsoft.VisualStudio.TestTools.UnitTesting` namespace is included.

```csharp
using Microsoft.VisualStudio.TestTools.UnitTesting;

[TestClass]
public class MyFirstTest
{
	[TestMethod]
	public void Simple()
	{
		Assert.AreEqual( 4, 2 + 2 );
	}
}
```

--------------------------------

### Instantiate Widgets

Source: https://sbox.game/dev/doc/editor/editor-widgets

Widgets can be initialized as top-level windows by passing null as the parent, or as children of existing widgets.

```csharp
// Creates the Widget as a new Window since it has no parent
var windowExample = new ExampleWidget(null);
windowExample.Show()

// Creates the Widget as the child of another Widget, then adds it to that Widget's Layout
var childExample = new ExampleWidget(parentWidget);
parentWidget.Layout.Add(childExample);
```

--------------------------------

### GET /sbox/package/{ident}/leaderboard/{stat}/

Source: https://sbox.game/dev/doc/services/leaderboards/web-api

Retrieves a leaderboard for a specific package and statistic.

```APIDOC
## GET /sbox/package/{ident}/leaderboard/{stat}/

### Description
Retrieves leaderboard entries for a given package identifier and statistic name. Results can be filtered, sorted, and aggregated using query parameters.

### Method
GET

### Endpoint
https://public.facepunch.com/sbox/package/{ident}/leaderboard/{stat}/

### Parameters
#### Path Parameters
- **ident** (string) - Required - The package identifier of the game (e.g., facepunch.ss1).
- **stat** (string) - Required - The name of the stat to base the leaderboard on.

#### Query Parameters
- **count** (integer) - Optional - The amount of results to return (default 10).
- **offset** (integer) - Optional - The starting index for results (default 0). Negative values start from the bottom.
- **aggregation** (string) - Optional - How to aggregate stats: sum, max, min, avg, last (default sum).
- **sort** (string) - Optional - Sorting order: desc, asc (default desc).
- **datefilter** (string) - Optional - Time period filter: none, year, month, week, day (default none).
- **date** (string) - Optional - Specific date to query for the datefilter (default now).
- **centersteamid** (integer) - Optional - Center results on a specific SteamId (default 0).
- **country** (string) - Optional - Limit results to a specific country code (default none).
- **friends** (boolean) - Optional - Limit results to the current user's friends (default false).
- **include[]** (array) - Optional - List of steamids to always show on the leaderboard.

### Response
#### Success Response (200)
- **Stat** (string) - The name of the statistic.
- **TotalEntries** (integer) - Total number of entries found.
- **Entries** (array) - List of leaderboard entries.

#### Response Example
{
  "Stat": "zombies_killed",
  "TotalEntries": 2588,
  "Entries": [
    {
      "Rank": 1,
      "Value": 645806,
      "SteamId": 76561198043785940,
      "CountryCode": "us",
      "DisplayName": "puxorb",
      "Timestamp": "2024-08-23T03:44:17.0174014+00:00"
    }
  ]
}
```

--------------------------------

### Getting All Active Components of a Type

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Iterate through all active components of a specific type in the scene.

```C#
foreach ( var c in Scene.GetAll<CameraComponent>() )
```

--------------------------------

### Getting GameObject Local Position

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Retrieve the local position of a GameObject relative to its parent.

```C#
var p = go.LocalPosition;
```

--------------------------------

### Advanced Broadcasting Patterns

Source: https://sbox.game/dev/doc/scene/components/events

Examples of broadcasting to specific types, modifying values, and collecting data.

```csharp
// tint all skinnedmodelrenderer's to red
Scene.RunEvent<SkinnedModelRenderer>( x => x.Tint = Color.Red );

// allow all listeners to change a value
float damage = 100.0f;
Scene.RunEvent<IPlayerDamageMesser>( x => x.ModifyDamage( player, damageinfo, ref damage ) );

// collect values
List<Vector3> damagePoints = new ();
Scene.RunEvent<IDamageProvider>( x => x.GetDamagePoint( damagePoints ) );
```

--------------------------------

### Play music from file

Source: https://sbox.game/dev/doc/media/audio

Initializes and plays a music track from the mounted file system with volume and repeat settings.

```csharp
var music = MusicPlayer.Play( FileSystem.Mounted, "music/theme.ogg" );
music.Volume = 0.8f;
music.Repeat = true;
```

--------------------------------

### Download and Mount Cloud Asset at Runtime

Source: https://sbox.game/dev/doc/assets/resources/cloud-assets

Dynamically download and mount Cloud Assets at runtime using Package.Fetch and package.MountAsync. This is useful for features like spawnable props or procedural generation.

```csharp
static async Task<Model> DownloadModel( string packageIdent )
{
  var package = await Package.Fetch( packageIdent, false );
  if( package == null || package.Revision == null )
  {
    // Package not found
    return;
  }
  // If the package was found, mount it (download the content)
  await package.MountAsync();
  
  // Get the path to the primary asset (vmdl for Model, vsnd for Sound, ect.)
  var primaryAsset = package.GetMeta( "PrimaryAsset", "" );
  return Model.Load( primaryAsset );
}
```

--------------------------------

### Implement ICollisionListener interface

Source: https://sbox.game/dev/doc/scene/components/component-interfaces

Enables a component to receive callbacks for collision start, update, and stop events.

```csharp
public sealed class CollisionListenerSample : Component, Component.ICollisionListener
{
	public void OnCollisionStart( Collision other )
	{
		Log.Error( "Collision started with: " + other.Other.GameObject );
	}

	public void OnCollisionUpdate( Collision other )
	{
		Log.Error( "Collision continued with: " + other.Other.GameObject );
	}

	public void OnCollisionStop( CollisionStop other )
	{
		Log.Error( "Collision stopped with: " + other.Other.GameObject );
	}
}
```

--------------------------------

### Boolean Console Variable

Source: https://sbox.game/dev/doc/code/code-basics/console-variables

Declare a boolean console variable that can be toggled. This example initializes `debug_bullets` to `false`.

```csharp
	[ConVar]
	public static bool debug_bullets{ get; set; } = false;
```

--------------------------------

### Standard Shading Model Implementation

Source: https://sbox.game/dev/doc/rendering/shaders/shading-model

This snippet shows the typical entry point for the default Source 2 Shading Model, consuming material properties and returning the shaded output.

```csharp
float4 MainPs(PixelInput i)  : SV_Target0
{
   Material m = Material::From( i );
   return ShadingModelStandard::Shade( m );
}
```

--------------------------------

### Get Object-World Matrix in Vertex Shader

Source: https://sbox.game/dev/doc/rendering/shaders/gpu-instancing

Use this function in your vertex shader to retrieve the Object→World matrix for instanced rendering.

```cpp
float3x4 CalculateInstancingObjectToWorldMatrix( const VS_INPUT i );
```

--------------------------------

### Attach Command List to Camera

Source: https://sbox.game/dev/doc/rendering/shaders/command-lists

Initialize a command list and register it to a specific rendering stage on the camera.

```csharp
	protected override void OnEnabled()
	{
		commands = new Rendering.CommandList( "AmbientOcclusion" );
  
        // Build your commands here eg
        commands.Set("Foo", 1.0f );
        
		Camera.AddCommandList( commands, Rendering.Stage.AfterDepthPrepass );
	}
```

--------------------------------

### EnvMap::From

Source: https://sbox.game/dev/doc/rendering/shaders/classes/envmap

Samples environment probes based on world position, screen position, normals, and roughness.

```APIDOC
## float3 From( float3 WorldPosition, float4 PositionSs, float3 WorldNormal, float2 Roughness = 0.0f )

### Description
Allows sampling environment probes present in the scene with appropriate mip level and clustered culling.

### Parameters
- **WorldPosition** (float3) - World-space pixel position.
- **PositionSs** (float4) - Screen position.
- **WorldNormal** (float3) - World-space geometry normals.
- **Roughness** (float2) - Surface roughness, where 0 is the highest mip level and 1 is the lowest.
```

--------------------------------

### Perform HTTP GET and POST requests

Source: https://sbox.game/dev/doc/networking/http-requests

Use RequestStringAsync for retrieving string responses and RequestAsync for sending JSON payloads.

```csharp
// GET request that returns the response as a string
string response = await Http.RequestStringAsync( "https://google.com" );

// POST request of JSON content ignoring any response
await Http.RequestAsync( "https://api.facepunch.com/my/method", "POST", Http.CreateJsonContent( playerData ) );
```

--------------------------------

### Create a reference track

Source: https://sbox.game/dev/doc/movie-maker/playback-api

Initializes a reference track that binds to a GameObject named "Camera".

```csharp
using Sandbox.MovieMaker;

var objectTrack = MovieClip.RootGameObject( "Camera" );
```

--------------------------------

### Run Local Project as Game

Source: https://sbox.game/dev/doc/networking/dedicated-servers/running-local-projects

Use this command to specify a local project directory as the game for a dedicated server. Assets are fetched from the cloud, and missing items are sent directly from the server to clients.

```bash
+game c:/git/sbox-mygame/.sbproj
```

--------------------------------

### PlayerController.IEvents

Source: https://sbox.game/dev/doc/scene/components/reference/player-controller

An interface that can be implemented on a sibling component to listen to and react to events triggered by the PlayerController, such as movement, camera setup, and interaction.

```APIDOC
## interface PlayerController.IEvents

### Description
Implement this interface on a sibling component to receive callbacks from the PlayerController.

### Methods
- **OnEyeAngles(ref Angles angles)** - Called when eye angles change; allows modification of sensitivity or input.
- **PostCameraSetup(CameraComponent cam)** - Called after the camera has been configured.
- **OnJumped()** - Triggered when the player jumps.
- **OnLanded(float distance, Vector3 impactVelocity)** - Triggered when the player lands on the ground.
- **GetUsableComponent(GameObject go)** - Determines if a component is interactable; returns the component or null.
- **StartPressing(Component target)** - Triggered when the player starts using an object.
- **StopPressing(Component target)** - Triggered when the player stops using an object.
- **FailPressing()** - Triggered when the use action is pressed but no interaction occurs.
```

--------------------------------

### Get Basic Leaderboard

Source: https://sbox.game/dev/doc/services/leaderboards

Retrieves a leaderboard for a given stat and refreshes its entries. Logs the rank, display name, and value for each entry.

```csharp
var board = Sandbox.Services.Leaderboards.GetFromStat( "facepunch.ss1", "zombies_killed" );
await board.Refresh();

foreach ( var entry in board.Entries )
{
	Log.Info( $"{entry.Rank} - {entry.DisplayName} - {entry.Value}" );
}
```

--------------------------------

### Get Extra Per-Instance Shader Data

Source: https://sbox.game/dev/doc/rendering/shaders/gpu-instancing

Access additional per-instance data, such as tint color, using this function in the vertex shader.

```cpp
ExtraShaderData_t GetExtraPerInstanceShaderData( const VS_INPUT i );
```

--------------------------------

### Simplest Trace

Source: https://sbox.game/dev/doc/physics/tracing

Perform a basic ray trace and log information if a hit occurs. Ensure `startPos` and `endPos` are defined.

```csharp
SceneTraceResult tr = Scene.Trace.Ray( startPos, endPos ).Run();

if ( tr.Hit )
{
	Log.Info( $"Hit: {tr.GameObject} at {tr.EndPosition}" );
}
```

--------------------------------

### Basic Console Command

Source: https://sbox.game/dev/doc/code/code-basics/console-variables

Define a simple console command that executes a static method. Running `hello` in the console will print `Hello There!`. Requires the `ConCmd` attribute.

```csharp
    [ConCmd("hello")]
    static void HelloCommand()
    {
        Log.Info( "Hello there!" );
    }
```

--------------------------------

### Console Command with Arguments

Source: https://sbox.game/dev/doc/code/code-basics/console-variables

Create a console command that accepts string arguments. The backend attempts to convert arguments to the specified type. Running `hello dave` will print `Hello there dave!`.

```csharp
    [ConCmd("hello")]
    static void HelloCommand( string name )
    {
        Log.Info( $"Hello there {name}!" );
    }
```

--------------------------------

### StartControl

Source: https://sbox.game/dev/doc/scene/components/events/igameobjectnetworkevents

Called when the current client becomes the controller of this GameObject, meaning it is no longer a proxy.

```APIDOC
## StartControl

### Description
We have become the controller of this object, we are no longer a proxy.

### Parameters
#### Path Parameters
- None

### Response
#### Success Response (200)
- **None**
```

--------------------------------

### Use multiple Binder instances

Source: https://sbox.game/dev/doc/movie-maker/playback-api

Demonstrates using custom Binder instances to control different objects with the same clip.

```csharp
var binder = new TrackBinder( Game.ActiveScene );

binder.Get( cameraTrack ).Bind( Game.ActiveScene.Camera );

// Using Binder.Default

cameraTrack.Update( time );

// Using our own Binder instance

cameraTrack.Update( time, binder );
```

--------------------------------

### Polling Colliders Inside a Trigger

Source: https://sbox.game/dev/doc/physics/triggers

Use the 'Touching' property to get a list of all colliders currently overlapping with a trigger collider. This is useful for continuous checks.

```csharp
[Property] public BoxCollider Box { get; set; }

protected override void OnUpdate()
{
    foreach ( var collider in Box.Touching )
    {
        Log.Info( $"{collider.GameObject.Name} is inside the box" );
    }
}
```

--------------------------------

### Fast Path Arrays and Lists

Source: https://sbox.game/dev/doc/code/advanced-topics/hotloading

Demonstrates array types that benefit from a fast hotload path when they contain only value types without reference fields.

```csharp
public record struct UserStruct( Vector3 Foo, int Bar );

public int[] UserStructArray;        // Fast
public string[] StringArray;         // Slow
public object[] ObjectArray;         // Slow
public Vector3[] VectorArray;        // Fast
public UserStruct[] UserStructArray; // Fast
```

--------------------------------

### Connect to a server

Source: https://sbox.game/dev/doc/networking/dedicated-servers

Use this command in the game client console to join a server using its lobby ID.

```text
connect <lobbyId>
```

```text
connect 1234567890
```

--------------------------------

### Manually Attach Sound to GameObject

Source: https://sbox.game/dev/doc/sound/playing-sounds

Manually configure a SoundHandle to follow a GameObject by setting the Parent and enabling FollowParent.

```csharp
var handle = Sound.Play( FootstepSound, WorldPosition );
handle.Parent = GameObject;
handle.FollowParent = true;
```

--------------------------------

### Procedural Instancing with SV_InstanceID

Source: https://sbox.game/dev/doc/rendering/shaders/gpu-instancing

In procedural instancing, derive transforms or positions from the SV_InstanceID in the vertex shader. This example offsets the position based on the instance ID.

```cpp
PixelInput MainVs( VertexInput i, uint instanceID : SV_InstanceID )
{
    float3 offsetPosition = float3( 0, 0, 64 * instanceID );
}
```

--------------------------------

### Define MCP tools in C#

Source: https://sbox.game/dev/doc/editor/mcp-server

Example of defining a toolset and tool using attributes. The XML documentation comments are automatically used as descriptions for the agent.

```csharp
namespace Editor.Mcp;

[McpToolset( "car", "Everything about the cars in the scene" )]
public static class CarTools
{
	/// <summary>
	/// Find cars by name. Returns each car's id, which you pass to get_car for details.
	/// </summary>
	/// <param name="query">Case insensitive substring of the car's name. Empty matches everything.</param>
	/// <param name="limit">How many results to return. Default 20, max 100.</param>
	[McpTool( "find_cars" )]
	public static object FindCars( string query = "", int limit = 20 )
	{
		// ...find the cars...
		return new { Total = total, Cars = cars };
	}
}
```

--------------------------------

### Configuring Recorder Options

Source: https://sbox.game/dev/doc/movie-maker/recording-api

Shows how to create and configure `MovieRecorderOptions` to specify capture behavior, including sample rate, GameObject filtering, and custom capture actions.

```APIDOC
## Configuring Recorder Options

### Description
This snippet demonstrates how to customize `MovieRecorderOptions` for selective recording.

### Code
```csharp
var options = new MovieRecorderOptions( SampleRate: 60 )
    .WithCaptureAll<Player>()
    .WithComponentCapturer<PlayerCapturer>()
    .WithCaptureAction( x => x
        .GetTrackRecorder( scoreManager )
        .Property( "Score" )
        .Capture() );
    
var recorder = new MovieRecorder( Scene, options );
```
```

--------------------------------

### Create a Model AssetPreview

Source: https://sbox.game/dev/doc/editor/asset-previews

Implements a custom preview for model resources, including rotation speed configuration and pixel evaluation for thumbnail generation.

```csharp
[AssetPreview( "mymdl" )]
public class PreviewMyModelResource : AssetPreview
{
	// The speed at which the model rotates. The length of a cycle in seconds is 1 / CycleSpeed
	public override float PreviewWidgetCycleSpeed => 0.2f;

	// This will evaluate a few frames and pick the one with the least alpha and most luminance for the thumbnail
	public override bool UsePixelEvaluatorForThumbs => true;

	public PreviewMyModelResource( Asset asset ) : base( asset )
	{
	}

	public override Task InitializeAsset()
	{
		// Get the resource from the asset
		var resource = Asset.LoadResource<MyModelResource>();

		// Get the Model from the resource
		var model = resource?.Model;
		if ( model is null )
		{
			return Task.CompletedTask;
		}

		// Make sure we are scoped to the preview scene
		using ( Scene.Push() )
		{
			// Create a new GameObject with a SkinnedModelRenderer component 
			PrimaryObject = new GameObject( true, "Model Preview" );
			PrimaryObject.WorldTransform = Transform.Zero;

			var modelRenderer = PrimaryObject.AddComponent<SkinnedModelRenderer>();
			modelRenderer.PlayAnimationsInEditorScene = true;
			modelRenderer.Model = model; // Set the model on the renderer

			// Center the scene around the model bounds, so the camera is positioned correctly
			SceneSize = model.Bounds.Size;
			SceneCenter = model.Bounds.Center;
		}

		return Task.CompletedTask;
	}
}
```

--------------------------------

### Implement PlayerController Events in C#

Source: https://sbox.game/dev/doc/scene/components/reference/player-controller

Implement the IEvents interface on a sibling component to handle player actions like jumping, landing, and camera setup.

```csharp
	/// <summary>
	/// Events from the PlayerController
	/// </summary>
	public interface IEvents : ISceneEvent<IEvents>
	{
		/// <summary>
		/// Our eye angles are changing. Allows you to change the sensitivity, or stomp all together.
		/// </summary>
		void OnEyeAngles( ref Angles angles ) { }

		/// <summary>
		/// Called after we've set the camera up
		/// </summary>
		void PostCameraSetup( CameraComponent cam ) { }

		/// <summary>
		/// The player has just jumped
		/// </summary>
		void OnJumped() { }

		/// <summary>
		/// The player has landed on the ground, after falling this distance.
		/// </summary>
		void OnLanded( float distance, Vector3 impactVelocity ) { }

		/// <summary>
		/// Used by the Using system to find components we can interact with.
		/// By default we can only interact with IPressable components.
		/// Return a component if we can use it, or else return null.
		/// </summary>
		Component GetUsableComponent( GameObject go ) { return default; }

		/// <summary>
		/// We have started using something (use was pressed)
		/// </summary>
		void StartPressing( Component target ) { }

		/// <summary>
		/// We have stopped using something
		/// </summary>
		void StopPressing( Component target ) { }

		/// <summary>
		/// We pressed USE but it did nothing
		/// </summary>
		void FailPressing() { }

	}
```

--------------------------------

### Debug Trace Visualization

Source: https://sbox.game/dev/doc/physics/tracing

Visualize a trace in the editor for debugging purposes. The trace and hit point will be drawn for a specified duration. Ensure `start` and `end` are defined.

```csharp
var tr = Scene.Trace
    .Ray( start, end )
    .Run();

DebugOverlay.Trace( tr, 5f ); // lasts for 5 seconds
```

--------------------------------

### Logging to Console

Source: https://sbox.game/dev/doc/code/code-basics/cheat-sheet

Use Log.Info for general information. Ensure the username variable is defined.

```C#
Log.Info( $"Hello {username}" );
```

--------------------------------

### Get Texture Methods in HLSL

Source: https://sbox.game/dev/doc/rendering/shaders/classes/bindless-api

These methods are used in HLSL shaders to retrieve different types of textures using an index. The GetTexture2D method has an optional sRGB parameter.

```cpp
Texture2D Bindless::GetTexture2D( int nIndex, bool srgb = false );
Texture3D Bindless::GetTexture3D( int nIndex );
TextureCube Bindless::GetTextureCube( int nIndex );
Texture2DArray Bindless::GetTexture2DArray( int nIndex );
TextureCubeArray Bindless::GetTextureCubeArray( int nIndex );
```

--------------------------------

### Custom Particle Controller with Callbacks

Source: https://sbox.game/dev/doc/rendering/effects/particle-effect/custom-particle-controller

Use `OnBeforeStep` and `OnAfterStep` for main-thread operations like instantiating prefabs based on particle conditions. `OnParticleStep` is thread-safe and should avoid direct manipulation of game objects or callbacks.

```csharp
public class MyParticleController : ParticleController
{
	Action callbacks;

	protected override void OnBeforeStep( float delta )
	{
		callbacks = null;
	}

	protected override void OnParticleStep( Particle particle, float delta )
	{
		if ( particle.Age > 10.0f )
		{
			lock ( this )
			{
				callbacks += () => SceneUtility.Instantiate( myPrefab, particle.Position );
			}
		}
	}

	protected override void OnAfterStep( float delta )
	{
		callbacks?.Invoke();
		callbacks = null;
	}
}
```

--------------------------------

### Using Task.ContinueWith for Results

Source: https://sbox.game/dev/doc/scene/components/async

This example shows how to handle the result of an asynchronous operation from synchronous code using `ContinueWith`. The provided action will be executed once the task completes successfully.

```csharp
protected override void OnEnabled()
{
    // Will run async and run this Action when the task finishes
    GetKanyeQuote().ContinueWith( task => Log.Info( $"Kanye: {task.Result}" ) );
}
```

--------------------------------

### Configure MoviePlayer

Source: https://sbox.game/dev/doc/movie-maker/playback-api

Sets up a MoviePlayer component with a clip, binder, and playback position.

```csharp
var moviePlayer = GameObject.AddComponent<MoviePlayer>();

moviePlayer.Clip = clip;
moviePlayer.Binder.Get( clip.GetReference<GameObject>( "Camera" ) ).Bind( Game.ActiveScene.Camera );

// Time in seconds

moviePlayer.Position = 0.75;
```

--------------------------------

### Implementing a Ladder Link

Source: https://sbox.game/dev/doc/gameplay/navigation/navmesh-links

A custom NavMeshLink implementation that divides ladder traversal into alignment, vertical climbing, and exiting phases.

```csharp
public sealed class LadderLink : NavMeshLink
{
    protected override void OnLinkEntered( NavMeshAgent agent )
    {
    	ClimbLadder( agent );
    }

    private async void ClimbLadder( NavMeshAgent agent )
    {
    	var initialPos = agent.CurrentLinkTraversal.Value.AgentInitialPosition;
    
    	var start = agent.CurrentLinkTraversal.Value.LinkEnterPosition;
    	var endVertical = start.WithZ( agent.CurrentLinkTraversal.Value.LinkExitPosition.z );
    	var end = agent.CurrentLinkTraversal.Value.LinkExitPosition;
    
    	var climbSpeed = 100f;
    
    	var startDuration = (start - initialPos).Length / climbSpeed;
    	var climbDuration = (endVertical - start).Length / climbSpeed;
    	var endDuration = (end - endVertical).Length / climbSpeed;
    
    	var totalLadderTime = startDuration + climbDuration + endDuration;
    
    	TimeSince timeSinceStart = 0;
    
    	while ( timeSinceStart < totalLadderTime )
    	{
    		Vector3 newPosition = start;
    
    		// 1. Make sure we are positioned at the link start
    		if ( timeSinceStart < startDuration )
    		{
    			newPosition = Vector3.Lerp( initialPos, start, timeSinceStart / startDuration );
    		}
    		// 2. Vertical Movement
    		else if ( timeSinceStart < startDuration + climbDuration )
    		{
    			newPosition = Vector3.Lerp( start, endVertical, (timeSinceStart - startDuration) / climbDuration );
    		}
    		// 3. Move off ladder to link end position
    		else
    		{
    			newPosition = Vector3.Lerp( endVertical, end, (timeSinceStart - startDuration - climbDuration) / endDuration );
    		}
    
    		agent.SetAgentPosition( newPosition );
    
    		await Task.Frame();
    	}
    
    	agent.SetAgentPosition( end );
    
    	agent.CompleteLinkTraversal();
    }
}
```
Tokens:
Raw