S&box Wiki

Revision Difference

Custom_Asset_Types#548073

<cat>Code.Misc</cat> <cat>Code.Editor</cat> <title>Custom Asset Types</title> 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. <upload src="aa125/8da3ac2bed7fc93.png" size="26483" name="image.png" /> 3. Enter a name for your asset <upload src="aa125/8da3ac1fd392295.png" size="6257" name="image.png" /> 4. Go to the "Inspector" tab and set your asset up how you want it. 5. 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. ```csharp 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 ); } } ```