From 167741cfbba0b9f6d6d8f846563c9df38e5df731 Mon Sep 17 00:00:00 2001 From: Steve Streeting Date: Mon, 26 Oct 2020 13:05:41 +0000 Subject: [PATCH] Add dedicated UiTheme docs, and document InputImage --- doc/InputImage.md | 36 ++++++++++++++++ doc/UiTheme.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++ doc/Widgets.md | 61 -------------------------- 3 files changed, 143 insertions(+), 61 deletions(-) create mode 100644 doc/InputImage.md create mode 100644 doc/UiTheme.md diff --git a/doc/InputImage.md b/doc/InputImage.md new file mode 100644 index 0000000..9cd4e59 --- /dev/null +++ b/doc/InputImage.md @@ -0,0 +1,36 @@ +# InputImage + +InputImage is a subclass of Image which can be told to display an image of +a keyboard key, mouse button, gamepad stick / button, etc. It can also look +up the key currently assigned as input for an associated Action or Axis, changing +dynamically based on what the current input method is (mouse, keyboard, gamepad). + +InputImage requires a [UiTheme](UiTheme.md) to operate, which links to the images it needs. + +## Properties + +### Binding Type + + +* "Action" if the image should display the current mapping for an input action +* "Axis" to look up an input axis +* "Key" to manually specify a key (which can be gamepad or mouse too) + +### Action or Axis Name + +The name of the input action or axis that should be looked up to determine the +key that we'll need an image for. + +You can leave this blank if you set Binding Type to "Key". + +### Key + +If you don't want the InputImage to look up an action, but want to manually specify +an input action, then drop down this list and pick a key (which can be a gamepad +button, mouse axis etc as well as a keybaord key) and the InputImage will display +that. + +### Custom Theme + +This is an optional link to a [UiTheme](UiTheme.md) you want to use for this +InputImage. If blank, the default UiTheme is used. diff --git a/doc/UiTheme.md b/doc/UiTheme.md new file mode 100644 index 0000000..337e432 --- /dev/null +++ b/doc/UiTheme.md @@ -0,0 +1,107 @@ +# UiTheme + +Some features of this plugin such as InputImage need a `UUiTheme` asset, which +is just a Data Asset based on the `UUiTheme` class which references other +resources like button images. There is one in the +[Examples project](https://github.com/sinbad/StevesUEExamples) as reference, +under Content/Data/UI. + +## Making UiTheme a Primary Asset + +UiThemes are a new kind of primary asset, loaded from code at runtime. They're not directly +linked in a Blueprint, so to make sure you can load them, and also that they +are packaged in your project, you need to register them with Unreal. + +There are a couple of ways to do this: + +1. Directly reference the UiTheme type +2. Use Primary Asset Labels to tag things indirectly + +I prefer the latter, because you only have to change your project settings once, +and from then on you just need to create Primary Asset Labels whenever you +want something else that's loaded dynamically at runtime from code like this. + +### Set up your project to use Primary Asset Labels + +1. Edit > Project Settings +1. Click "Asset Manager" in the tree +1. Expand "Primary Asset Types To Scan" +1. Add a new entry to this array: + 1. Primary Asset Type = PrimaryAssetLabel + 1. Asset Base Class = PrimaryAssetLabel + 1. Has Blueprint Classes = false + 1. Is Editor Only = false (important! packaging won't work otherwise) + 1. Directories = /Game (this just means you can use PrimaryAssetLabels anywhere) + 1. Rules > Apply Recursively = true + 1. Cook Rule = Unknown (this just means you can choose in each label) + + +## Create a UiTheme + +1. Click Add New > Miscellaneous > Data Asset +1. Select "UiTheme" as the class +1. Save the new asset with your chosen name + +## Setting the default theme + +To avoid having to configure the theme for every usage, this library has a +default theme, which is configured in Steve's Game Subsystem. The best way +to set this is by editing your DefaultGame.ini: + +``` +[/Script/StevesUEHelpers.StevesGameSubsystem] +DefaultUiThemePath="/Game/Path/To/YourUiThemeName.UiTheme" +``` + +That ".UiTheme" postfix is required, it's how UE knows what the type is. + +You need to **restart the editor** after making this change. + +## Create the PrimaryAssetLabel + +We need to tag this UiTheme as relevant for runtime use and packaging using the +PrimaryAssetLabel, since it won't be directly referenced by another asset: + +1. In the same directory as the uiTheme, click Add New > Miscellaneous > Data Asset +1. Select "Primary Asset Label" as the class +1. Name it however you like +1. Double-click to edit +1. Under "Explicit Assets", add an entry and pick the UiTheme you created above +1. Save the changes + + +## Create button sprite data + +The UiTheme wants to reference DataTables which contain links between the input +keys and button sprites. So the first job is to create the button sprites. + +The [Examples project](https://github.com/sinbad/StevesUEExamples) includes some +button sprites already; contained in a packed sprite sheet. I created these using +TexturePacker and imported into UE which created the sprites, but you can create +them however you like. However, we do require sprites rather than plain textures. + +This means you must have the Paper2D plugin enabled in your project. + +## Create DataTables linking inputs to button sprites + +Once you have a set of button sprites, you need to create DataTables which map +input FKeys (which can be keys, or mouse buttons, or gamepad buttons / sticks) +to these sprites, so that for example InputImage can be told to display the action +"Fire", and then display either say the left mouse button or a gamepad trigger +depending on what's being used. + +Personally I did this using a CSV file for ease of use, for example: + +```csv +Name,Key,Sprite +Gamepad_LeftX,Gamepad_LeftX,"PaperSprite'/Game/Textures/UI/Sprites/Frames/XboxOne_Left_Stick'" +Gamepad_FaceButton_Bottom,Gamepad_FaceButton_Bottom,"PaperSprite'/Game/Textures/UI/Sprites/Frames/XboxOne_A'" +``` + +You should import this as a DataTable based on the KeySprite type. A separate +one is needed for keyboard / mouse and gamepad. Once you've created them, or +copied the ones from the examples, you should update the UiTheme asset you +created to point at these data tables. + +Again see the [Examples project](https://github.com/sinbad/StevesUEExamples) for +a concrete example, in the Content/Data/UI folder. diff --git a/doc/Widgets.md b/doc/Widgets.md index b9c681a..75556c5 100644 --- a/doc/Widgets.md +++ b/doc/Widgets.md @@ -44,64 +44,3 @@ Several custom widgets are supplied to assist with some common challenges: easy to create multi-level on-screen menus with a simple "back" navigation. -# Additional Configuration - -## UiTheme - -Some features of this plugin such as InputImage need a `UUiTheme` asset, which -is just a Data Asset based on the `UUiTheme` class which references other -resources like button images. There is one in the Examples project as reference. - -### Create a UiTheme: - - -1. Click Add New > Miscellaneous > Data Asset -1. Select "UiTheme" as the class -1. Save the new asset with your chosen name - -### Create a Primary Asset Label - -UiThemes are a new kind of primary asset, loaded at runtime. To ensure this -asset is included when packaging, create a Primary Asset Label in the same folder: - -1. Click Add New > Miscellaneous > Data Asset -1. Select "Primary Asset Label" as the class -1. Name it however you like -1. Double-click to edit -1. Under "Explicit Assets", add an entry and pick the UiTheme you created above -1. Save the changes - -This just ensures that the packaging system knows to include your UiTheme, since -it won't be directly referenced by any other primary asset. - -### Create button sprite data - -The UiTheme wants to reference DataTables which contain links between the input -keys and button sprites. So the first job is to create the button sprites. - -The Example project includes some button sprites already; contained in a packed -sprite sheet. I created these using TexturePacker and imported into UE which created -the sprites, but you can create them however you like. However, we do require sprites -rather than plain textures. - -This means you must have the Paper2D plugin enabled in your project. - -### Linking input keys to button sprites -Once you have a set of button sprites, you need to create DataTables which map -input FKeys (which can be keys, or mouse buttons, or gamepad buttons / sticks) -to these sprites, so that for example InputImage can be told to display the action -"Fire", and then display either say the left mouse button or a gamepad trigger -depending on what's being used. - -Personally I did this using a CSV file for ease of use, for example: - -```csv -Name,Key,Sprite -Gamepad_LeftX,Gamepad_LeftX,"PaperSprite'/Game/Textures/UI/Sprites/Frames/XboxOne_Left_Stick'" -Gamepad_FaceButton_Bottom,Gamepad_FaceButton_Bottom,"PaperSprite'/Game/Textures/UI/Sprites/Frames/XboxOne_A'" -``` - -You should import this as a DataTable based on the KeySprite type. A separate -one is needed for keyboard / mouse and gamepad. Once you've created them, or -copied the ones from the examples, you should update the UiTheme asset you -created to point at these data tables.