How to use skins

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.

What is a skin?

  • 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.

How to add a 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)

  • Name the asset with the following convention: PDA_Skin_{Name}

  • Once you have created your new skin asset, you can customize it however you want.

    • NOTE: When supplying assets to the skin (e.g. providing textures in the Skin Details -> Images list), make sure that any of these assets belong to the plugin that contains your skin asset, or come from a plugin included by it (i.e. Juno Parkland can contain assets from Juno General). You can verify this by linting the folder using the Juno Full Ruleset).

  • Make sure in Project Settings -> Game -> Asset Manager -> Primary Asset Types to Scan, the UISkin entry can find your created asset, ether by adding its directory in the Directories field, or adding it to the Specific Assets list.

    • NOTE: This step isnโ€™t required in World Builder projects.

How to use skins:

How to modify a skin

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.

How to make widgets use skins

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)

Skin Settings Objects

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.

Skin Details Structs

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

Extra notes

  • 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.

How to listen to skin updates

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.

How to switch skin (in-game or in-editor)

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

Last updated