How to use skins
Last updated
Last updated
MSquared are no longer supporting this feature beyond Critical and Blocking bugs. This feature may eventually be fully deprecated, so it is advised that Widgets created using the skinning system are recreated without this dependency where possible. Further guidance will be given in due time.
The following should give information on what the skin system is, and how to use it. Any questions, please reach out to our support channel!
The goal of this system is to give all the power to the designers to be able to re-skin what they want without needing any assistance from programmers. Each plugin can have its own skin, and not require being added to a shared table that needs knowledge of each skin.
A skin is a list of UI details that we want to be able to be swapped out when changing project, so we can share the same widgets, but use different styles. Examples being fonts, text colors, and images.
The skin is defined in the BP_SkinPrimaryAsset - this is what is loaded for each skin
Individual skins are assets created from this template
This skin contains a SSkinObject struct, which can be modified/extended to add further fields.
Currently this contains a selection of nested structs, to define particular parts of the skin, e.g. SColorsSkin
The skin also contains a Skin Settings list. This contains an arbitrary list of skin settings, that can be reachable by code. For more details on how these work, see How to make widgets use skins.
The PDA skin assets then allow you to modify these details for your particular skin.
Create the asset using the right click menu, and selecting Create advanced asset -> Miscellaneous -> Data Asset
Select BP_SkinPrimaryAsset as the data asset class (NOT J_SkinPrimaryAsset)
The skin is comprised of three main parts:
The Skin Details struct - this contains a lot of hard-coded structs with common values, like primary, secondary and tertiary button colors and fonts. For these, you can simply modify them directly.
This flow is somewhat old, and we're wanting to move away from it in favour of the second part:
The "skin setting objects" - These are individual skin settings objects for different parts of the codebase. These can be added in the base class the skin asset uses (e.g. BP_SkinPrimaryAsset). For each skin object, you can modify the internal fields directly, or provide a new class extending the setting type (e.g. BP_AdditionalTexturesSkinSettings) which has the modified values set.
The Custom Skin Settings list - as a user you can make your own custom skin settings objects, if you want to add things to the skin which aren't in Origin settings. To do this, you should:
Create a “Skin setting” class, extending from J_SkinSettingBase (this can be a C++ or Blueprint class)
From here, you can add variables to your custom class. You can set sensible defaults in the class BP.
Then you can add the class to the skin's Custom Skin Settings list.
NOTE: Unfortunately, if the Custom Skin Settings array has been modified already on the PDA, it won’t automatically add entries that were added to the BP_SkinPrimaryAsset. Therefore if you're wanting inheritance of skin settings, you should make skin setting object properties as above, rather than adding them to the custom list.
The idea is that when you setup your widget, instead of setting local properties, you should be retrieving the visual data from the current skin PDA.
Remember that there may be race conditions between the skin having loaded and the widget constructing. Refer to How to listen to skin updates for how to get the skin asset safely, and get when it updates at runtime (e.g. via live config)
For the skin settings objects, or the "custom skin settings" list, you can get the individual settings class by calling GetSkinAsset->GetSkinSettingByClass. This returns the skin settings object for the current skin if one exists.
For the skin details struct, there are a number of helper functions in the BPFL_SkinUtilities function library:
GetSkinObject -> Returns the SSkinObject that is currently active
GetCurrentSkinIcons -> Returns the SIconsSkin struct of the current skin
GetCurrentSkinColors -> Returns the SColorsSkin struct of the current skin
GetCurrentSkinFonts -> Returns the SFontsSkin struct of the current skin
GetCurrentWidgetStyleButtons -> Returns the SWidgetStyleSkin struct of the current skin
NOTE: For buttons, the WBP_PrimaryButton has already been set up to apply styling. In the designer, you can select the style for it to use using the Button Style field. We plan to add more “wrapped widgets” later down the line.
NOTE: For styling Combo boxes, any calls to Set Combo Box Font or Set Combo Box Foreground Color won’t take effect on everything unless called before the widget is added to the screen. For these, the On Setup event can be used.
If you are adding a skin to a widget that is on the HUD, or otherwise visible very early in the lifetime of the game, there is a risk of race conditions, where the correct skin won’t have loaded by the time your widget is ready. Additionally, if your skin updates at runtime (i.e. live config changes), you need to listen to the skin updates to apply them.
For this, the ListenToSkinUpdates helper function can be used.
OnSkinLoaded will be called once we get the first skin once it is ready. It will also be triggered every subsequent time the skin is updated.
If called in PreConstruct, it will also apply in “design time” - if you recompile the widget, the designer view should apply the skin that is defined in your skin settings.
The default skin used is specified in your project settings. If you want to use a different skin, this is the best place to replace it.
You can also control the skin that is used via live config, setting General.SkinName to the new asset name. For more details on live config, and how to set local overrides, see Live Config
As well as the General.SkinName, you can add additional live config overrides, which will take priority over this config value if they are set to true.
If you want to switch skin in the widget designer view, you will need to recompile the widget for the updated skin visuals to take effect
GetCurrentSkinColors
ListenToSkinUpdates helper in PreConstruct handles three use cases: It will get your default skin in the project settings at design time, it will wait for your first skin at runtime, and listen to subsequent updates of your skin in-game.
