What do I need to create a HUD widget?

You need:
1. SWF authoring software - I use Adobe Flash CS6 for this purpose.
2. A Papyrus script to control widget registration, loading, and passing information to the UI widget.
3. The HUDFramework Development Kit - this contains the HUDFramework Papyrus API and an AS3 interface file for your widgets.

*** Before you start, download the HUDFramework Sample Widget from the Files tab for a simple widget example! ***

Copy contents of the two folders in the HUDFramework Development Kit into your Papyrus source folder and Flash project folder, respectively.

First, create your HUD widget in Flash. Add text, graphics, etc. as you see fit. Use white color (#000000) for all your UI elements, as your UI widgets will automatically be tinted to the HUD UI color at runtime.

Ensure that the document class of your SWF file implements IHUDWidget, and has a function named processMessage(command:String, params:Array):void. Any messages that you send from Papyrus to the widget will be received in that function.

On the Papyrus end, to load a HUD widget, you need to:
1. Get a reference to HUDFramework by calling HUDFramework hud = HUDFramework.GetInstance(). If HUDFramework is not installed, this returns None.

2. Register your widget. Call hud.RegisterWidget(Self, "MyWidget.swf", afX = 10.0, afY = 10.0, abLoadNow = True, abAutoLoad = True) to register MyWidget.swf and place it at coordinates (10, 10) on the screen. abLoadNow will load the widget immediately after registration, and abAutoLoad will tell HUDFramework to automatically load your widget whenever the game is loaded. Change these parameters as you see fit.

If you are not using autoloading, you can load and unload your widget by calling LoadWidget("MyWidget.swf") and UnloadWidget("MyWidget.swf").

3. Make sure that the Papyrus script that is loading the widget implements the function HUD_WidgetLoaded(string asWidgetID) to be notified when your widget is loaded and ready to receive messages. You should not attempt to communicate with your widget before it is loaded!

Once your HUD_WidgetLoaded(string asWidgetID) is called by HUDFramework, your widget has been loaded and is ready to receive messages. You can call hud.SendMessage("MyWidget.swf", MY_COMMAND_ID, 200) to send a command with the ID MY_COMMAND_ID and the value 200 to your HUD widget. This will be received by your widget's processMessage function with the command ID and value that was sent.


How do I change existing UI elements on the HUD?

You have two options:
1. Use HUDFramework's Eval function to run ActionScript 3.0 code on HUDMenu directly from Papyrus.
2. Write an invisible HUD widget that manipulates UI elements in AS3 from within Scaleform.

If you just want to change the scale, rotation, etc. of existing UI elements, the Eval function will suffice.
When using the Eval function, the variable "hud" will refer to the HUDMenu root.

If you want to change sprites, you will need to create a SWF that contains these new sprites so that you can swap them out at runtime.


Important information on XB1 Deployment

Take note that on the XB1 platform, HUDFramework is an ESP, not an ESM. This is so that XB1 users can re-order HUDFramework to ensure that it takes precedence over other mods that replace HUDMenu.

If HUDFramework has been specified as a masterfile, before you upload your mod to Bethesda.net, ensure that you use FO4Edit to rename the masterfile requirement to HUDFramework.esp instead of HUDFramework.esm.

I recommend that before uploading for XB1, make a copy of your plugin and archive with a recognizable name, e.g. MOD_XB1.esp and make the masterfile change on the copy, as the Creation Kit does not allow ESPs to be specified as masters and will strip the master if the file is subsequently saved in the CK.