S&box Wiki

Home / Custom Asset Types

Custom Asset Types

Custom assets are things you can define yourself. They give you a nice inspector window and they're hotloaded in-game, which means you can whip things up pretty quickly if you're using them.

You can find plenty of examples of assets throughout s&box, here's a snippet from the clothing asset:

[GameResource("Clothing Definition", "clothing", "Describes an item of clothing and implicitly which other items it can be worn with.")] public partial class Clothing : GameResource { public string Title { get; set; } [ResourceType( "vmdl" )] public string Model { get; set; } [HideInEditor] public int Amount { get; set; } // ... }

It is important to note, you should ensure that your filetype is all lowercase, otherwise it will fail to register.

  • [GameResource("Clothing Definition", "clothing", "..." )] defines the title (Clothing Definition), file extension (.clothing), and a description of the asset type
  • Properties that should not be editable via the inspector in your asset should be marked with [HideInEditor]
  • You can mark properties with specific categories using [Category("Example Category")]
  • You should ensure that your filetype is all lowercase, otherwise it will fail to register/save.

How to use [ResourceType]

ResourceType supports specifying the file extension of a resource you want to use, which will add a navigator to the inspector.

Examples:

  • [ResourceType( "png" )]
  • [ResourceType( "vmdl" )].

In addition, it also supports asset files, including custom ones. e.g. [ResourceType( "sound" )] or [ResourceType( "clothing" )].

Using the inspector

Now that you have everything set up, you can use the inspector tool to create assets of your custom type.

  1. Go to the "Assets Browser" tab in the s&box editor.

  2. Right click a folder in your addon and click "New <Your Asset Name>". Typically you'd want to put these in some sort of data folder.

image.png
  1. Enter a name for your asset
image.png

  1. Go to the "Inspector" tab and set your asset up how you want it.

  2. Click the save button (looks like a floppy disk) to save your asset.

Accessing assets

All assets are loaded when you first start the game, there are several ways you can access them:

ResourceLibrary.Get<T>

When assets are loaded they are stored in a dictionary with their path, you can access these with ResourceLibrary.Get<T>.

// Property allows for hot-loading public Clothing Clothing { get; set; } // ... // Load the resource from a path // If the asset isn't found, this returns null Clothing = ResourceLibrary.Get<Clothing>( "config/tshirt.clothing" );

ResourceLibrary.TryGet<T>

TryGet<T> serves a similar purpose to Get<T> but returns a bool indicating whether the resource could be found. If the resource was found, the method provides it through an out parameter. This is just a slightly cleaner way to handle missing assets.

if ( ResourceLibrary.TryGet<Clothing>( "config/tshirt.clothing", out var loadedClothing ) ) { Clothing = loadedClothing; } else { // Resource couldn't be found, handle that here... }

PostLoad

When assets are loaded they call their PostLoad method, you can use this to store a list of your assets for later use.

public partial class Clothing : GameResource { // Access these statically with Clothing.All public static IReadOnlyList<Clothing> All => _all; internal static List<Clothing> _all = new(); protected override void PostLoad() { base.PostLoad(); if ( !_all.Contains( this ) ) _all.Add( this ); } }

Account Management

Special Pages

Wiki List