Advanced Structure Skins

Advanced Structure Skins allows users to create custom shaders for structures, providing creators with extreme flexibility, albeit also introducing additional complexity and potential incompatibilities.

This mod may remove game functionality, including but not limited to visible grounded effects, grounded vertex offsets and on-collision structure shaking, depending which shaders are used (as these features are implemented in the shader and must be rebuilt by skin creators.)

Don't forget to install AdvancedStructureSkins.Shared.dll in /RUMBLE/UserLibs!

You can watch a video tutorial for User setup and for getting started as a developer here: https://youtu.be/igGSTZQgDr0

For Users

Installing Skins

To find skins, head to the Rumble Modding Discord's #skin-share forum. Find a .bundle (v1.0.0 - v1.3.3) or .asb (v2.0.0+) file for a skin you like the look of and place it in /RUMBLE/UserData/Skins/. You may have to create this folder. Once you launch the game, your skin will be available to select in the UIFramework menu for Advanced Structure Skins.

There are two types of skins:

• Shaders, which have their visuals generated by code
• Textures, which are images placed on your structures

Some Shaders can sample Textures, allowing you to use a texture skin with a unique shader. .bundle files will only ever contain Shaders, but .asb files may contain either a Shader, a Texture Set, or both. In fact, .asb files can contain as many different Texture Sets as a developer wants.

Shaders are selectable in the Shaders tab in Advanced Structure Skins' UIFramework menu. Likewise, Textures are selectable in the Textures tab.

Manually Installing Texture Sets

Texture Sets may also be installed without using .asb files. Each Texture Set supports 4 images, Main.png, Normal.png, Mat.png and Grounded.png. Main images are typically a fairly normal looking image, a flat colour which contributes the majority of the texture's appearance. Normal, despite the name, is not a normal map any more due to changes in RUMBLE's art pipeline. Instead, it is typically a red and yellow image, which applies highlights and shadows to a structure's surface.

Installing Texture Sets manually is fairly straightforward. Here's the folder structure you'll want to create:

RUMBLE
| - UserData
|   | - Skins
|   |   | - StructureName
|   |   |   | - Mat.png
|   |   |   | - Main.png
|   |   |   | - Normal.png
|   |   |   | - Grounded.png

Valid structure names are Disc, Pillar, Ball, Cube, Wall, SmallRock and LargeRock.

If you want to use multiple textures, add your textures to a subfolder under the StructureName, and the game will automatically load the textures on launch. Textures can then be selected from the Textures tab.

If you want to prevent a skin from loading without deleting the skin permanently, just add an Underscore (_) to the beginning of the folder name and the game will ignore it.

Example folder structure:

RUMBLE
| - UserData
|   | - Skins
|   |   | - StructureName
|   |   |   | - SkinName (can be anything)
|   |   |   |   | - Main.png
|   |   |   |   | - Normal.png
|   |   |   |   | - Mat.png
|   |   |   |   | - Grounded.png
|   |   |   | - SkinName2
|   |   |   |   | - Main.png
|   |   |   |   | - Normal.png
|   |   |   |   | - Mat.png
|   |   |   |   | - Grounded.png

If you want to use multiple textures of the same type for a single skin (like if you wanted a playing card which changed the Main texture randomly, but kept the same Normal, simply add a folder for that type of texture to your SkinName folder. Example:

RUMBLE
| - UserData
|   | - Skins
|   |   | - StructureName
|   |   |   | - Main
|   |   |   |   | - tex1.png (can be anything)
|   |   |   |   | - tex2.png (can be anything)
|   |   |   |   | - tex3.png (can be anything)
|   |   |   | - Normal.png
|   |   |   | - Mat.png
|   |   |   | - Grounded.png

You can combine this with the previous example too - placing the skin files in a SkinName folder will load multiple skins with multiple textures.

For Developers

Creating Skins

There's a bunch of useful tools and example shaders in the SDK available on GitHub. The most important of which is the Shader Asset Bundle Builder, which you can access via the Tools tab at the top of the window. It should be relatively straightforward to use if you already know your way around unity.

Next, creating shaders. Advanced Structure Skins supports loading shaders made in either raw HLSL or through Unity's Shader Graph. To make them compatible with the game, you'll need to ensure some of your property names match the game's existing shaders. You can read the list of Supported Shader Properties here.

The grounded effect is probably the most important part to implement in a shader, since it has some pretty solid gameplay consequences, so I've included a couple helper functions to make life easier when implementing it.

You can include these functions in your HLSL shaders by adding #include "Assets/ExampleShaders/Shaders/AdditionalFunctions/GroundMask.hlsl" to your includes, or in your Shader Graphs by adding a Custom Function node and selecting the GroundMask.hlsl file from the AdditionalFunctions folder. Your Custom Function node will require a Vector3 input taking in the Worldspace Position, 3 float inputs taking in the _FloorHeight, _Stable and a Floor Height Offset, as well as 1 float output, returning white for any surface above the floor. You can name the function either GroundMask or GroundMaskGradient depending on which format suits your needs.

For vert offsets (such as shaking during hitstop or merging with the ground when grounded), you can implement the StructureVertOffsets(float3 worldPos, float floorHeight, float stable, float offset, float floorBlendAmount, float shake, float shakeAmount, float shakeFrequency) function by adding #include "Assets/ExampleShaders/Shaders/AdditionalFunctions/StructureVertOffsets.hlsl" to your includes, or in your Shader Graphs by adding a Custom Function node and selecting the StructureVertOffsets.hlsl file from the AdditionalFunctions folder. An example of implementation of this function is available in the Shaders folder.

There's also a couple other simple shader examples in the SDK project which should help give some idea on how other shader properties are implemented - it's up to you how you use the tools provided.

You can also add multiple materials to a single structure, creating multipass skins. Unfortunately, due to RUMBLE's base functionality, the properties _FloorHeight, _Stable, _shake, _shakeAmount and _shakeFrequency are not always updated reliably on all materials. Because of this, it's important that Element 0 of your Skin Manifest's Shaders is the material that makes up the majority of your skins's visual composition. This material will always receive reliable property values from the game.

All other material properties will be updated consistently on additional materials, so you can safely use them on other passes.

Creating Expansion Mods

You can now create your own expansions to Advanced Structure Skins, adding custom ShaderFeature classes to the mod. These allow you to use code to easily manage properties on a shader on a per-structure or global level.

To create a ShaderFeature, first add Advanced Structure Skins as a reference. Then, override either ShaderFeature or TimedShaderFeature, depending on your use case. Your ShaderFeature will require a constructor. It'll want three parameters, AdvancedSkin target ShaderPropertyType type, string propertyName and object defaultValue. Your ShaderFeature's constructor shouldn't require a type, propertyName or defaultValue input, and instead should set them explicitly in the base class's underlying constructor.

It's important that the value you assign in the base class's constructor is a valid input for your property's type, otherwise it will throw an error in OnEnable(). TimedShaderFeatures don't have to assign a default value, and will default to 999f. You can still provide a different default value if you want though.

public class CurrentVelocity : ShaderFeature
{
    private Structure Structure => target.structure;
    
    public CurrentVelocity(AdvancedSkin target) : base(target, ShaderPropertyType.Vector, "_currentVelocity", Vector3.zero) { }

    protected override void OnUpdate()
    {
        base.OnUpdate();
        SetProperty(Structure.CurrentVelocity);
    }
}

Once you've made your ShaderFeature class, register it with the Advanced Structure Skins API in your mod's LateInitializeMelon() function by calling AssAPI.RegisterShaderFeature<[ShaderFeature]>().

After which, you'll need to add functionality to your ShaderFeature yourself. If your ShaderFeature reacts to game events, you'll need to harmony patch your target event to patch in your feature's response. You'll need to be able to access a reference to an AdvancedSkin component on your target structure, at which point you can call AdvancedSkin.GetShaderFeature<[ShaderFeature]>(); to get a reference to that structure's instance of your ShaderFeature and interact with it accordingly.

ShaderFeature Functions

You can override SetProperty() to add extra functionality before or after the base function, but it is recommended you include base.ShaderProperty(value) in your override to ensure the properties are set correctly.

TimedShaderFeature Functions

• As TimedShaderFeature is an inheritor of ShaderFeature, it also has access to all previously listed functions.

PauseTimer() and ResumeTimer() are functionally the same thing (with inverted default parameters), but can be overridden separately in inheriting classes, so you're able to add unique functionality to each of them if you wish.

ShaderFeatures are automatically enabled and disabled when new materials are applied to a structure, depending on whether or not the material's property list contains the ShaderFeature's propertyName, so ShaderFeatures which are heavy on performance won't be running unless they have to be.