Custom HUDS

From BallisticNG Wiki
Jump to: navigation, search

This article is a stub. You can help BallisticNG Wiki by expanding it.

Arrow introduction[edit | edit source]

BallisticNG as of 1.1.6 will allow you to create your own HUDs that can either be used in your own gamemodes or can replace the existing HUDs of any gamemode. This is an extension of both code mods and the Unity Tools package, so you'll need to be familiar with both to make your own HUD.

The HUD is created inside of Unity using the Unity UI tookit and a script to assign components to IDs for code mods to read. Code mods are used to reference components and then manipulate them to present the information you want to the player.

Arrow important concepts[edit | edit source]

Before you get started there are a few important concepts that you should understand.

HUDs are multiple canvases[edit | edit source]

In BallisticNG HUDs are not part of a single canvas or script. Each component you see on the screen is its own UI canvas with its own script. This allows HUDs to be modular and reused across multiple gamemodes. The speedometer is an example of this. Having HUDs setup like this also reduces overhead on Unity's part as it's quite slow at redrawing UI cavases, so this only requires Unity to redraw specific components that update instead of the entire HUD.

HUDs are prefabs[edit | edit source]

All HUDs are prefab objects. These are gameobject heiarchies that you have made inside a Unity scene and then have dragged out into the project view.

Arrow using custom huds for new gamemodes[edit | edit source]

You can use the custom HUD API to load in your HUDs standalone. The procedure is the same as if you were loading in vanilla huds but you instead call:

ScriptableHud[] SceneHudManager.CreateNewHud<T>(AssetBundle bundle, string assetPath)
--------------------------------------------------------------------------------------
This will load a custom HUD and fully configure it ready to be used in a gamemode.

T                : The component type to load. This needs to be your HUD class.
bundle           : The loaded asset bundle to load the HUD prefab from
assetPath        : The path to the asset This needs to be the full relative path in your Unity Project

Usage Example
    ScriptableHud[] speedometerHuds = SceneHudManager.CreateNewHud<MySpeedometer>(MyHudMod.HudBundle, "assets/my huds/my example hud/speedometer.prefab");


Arrow the api[edit | edit source]

Arrow ScriptableHud[edit | edit source]

Scriptable Hud is what all of your HUD classes need to derive from. This class handles all of the internal behaviours for you so all you have to worry about is the how the specifics of your HUD elements work.

Variables:

Color BnGAccent                       : The standard accent color for BallisticNG interfaces.
RectTransform HudContainer            : The object that contains all of your hud elements. This is used to allow the HUD to be enabled/disabled without disabling the script.
ShipRefs TargetShip                   : The ship that this HUD belongs to.
string TimeFormat                     : The time format to use for FloatToTime.Convert() calls.
string EmptyTime                      : "-:--.--"
HudComponents CustomComponents        : Holds all of the components defined in your HUD prefab. See the section below for more details.

Methods:

You override these. Make sure you leave the base.MethodName call inside as these will be performing important tasks.
ScriptableHud is a monobehaviour so all of Unity's monobehaviour functions are available to you.

virtual void Start()                 : Called when the HUD has started. Do all of your init stuff in here.
virtual voud Update()                : Called every frame. Update your HUD in here.
virtual void OnDestroy()             : Called when the HUD is destroyed. Do any deinit stuff in here.

virtual void OnGamePaused()          : Called when the game is paused. Base implementation closes the HUD.
virtual void OnGameUnpaused()        : Called when the game is unpaused. Base implementation opens the HUD.

RectTransform GetById(string id)
--------------------------------
This will try to find a component by an ID and return the rect transform component. If it doesn't find anything it will return null.

id        : The ID of the component to load

Usage Example
    RectTransform scoreTransform = GetById("ScoreDisplay");

T GetById<T>(string id)
-----------------------
This will try to find a component by an ID and return a component of the specified type. This allows you to easily grab specific components without having to do any of the casting yourself. If it doesn't find anything it will return null.

T        : The component type to load.
id       : The ID of the component to load.

Usage Example
    Text scoreDisplay = GetById<Text>("ScoreDisplay"); 

Arrow SceneHudManager[edit | edit source]

A scene hud manager is where you register your HUDs into the gamemode. You need to create a scene hud manager for each gamemode you want to override the HUD for.

virtual void OnCreateHuds()
---------------------------
Called when your manager needs to create it's HUDs.

Usage Example
    public override void OnCreateHuds()
    {
        RegisterHud<MySpeedometer>(MyHudMod.HudBundle, "assets/my huds/my example hud/speedometer.prefab");
        RegisterInternalHud(BallisticNG.RaceUi.InterfaceLoader.Huds.WrongWayDisplay);
    }

ScriptableHud[] RegisterHud<T>(AssetBundle assetBundle, string assetPath)
---------------------------------------------------------
Registers and loads a new HUD into the current gamemode. Returns the loaded huds per player.

T              : The class type component to load
assetBundle    : The loaded asset bundle to load the HUD prefab from
assetPath      : The path to the asset This needs to be the full relative path in your Unity Project

Usage Example
    RegisterHud<MySpeedometer>(MyHudMod.HudBundle, "assets/my huds/my example hud/speedometer.prefab");

void RegisterInternalHud(string name)
-------------------------------------
Registers and loads an internal HUD into the current gamemode. See the BallisticNG.RaceUI.InterfaceLoader.Huds class for the entire list of names.

name        : The name of the HUD to load

Usage example
    RegisterInternalHud(BallisticNG.RaceUi.InterfaceLoader.Huds.WrongWayDisplay);

Arrow CustomHudRegistry[edit | edit source]

The Custom Hud Registry is where you register your mod and your mods HUD content to the game.

First off make sure you have an ID for your mod. It's reccomended you store this in a constant so you can reference it everywhere and only have to edit the constant if you want to update the mod's ID everywhere.

void RegsterMod(string mod)
---------------------------
Registers your mod into the UI. This will allow people to select it from the hud style option in the gameplay menu.

mod        : The ID of your mod. This doubles up as the display name so make sure the ID is something people will recognise.

Usage Example
    CustomHudRegistry.RegisterMod("MyHudMod");

void RegisterSceneManager(string gamemodeId, string mod, SceneHudManager manager)
---------------------------------------------------------------------------------
Registers a scene manager into the game. This is what will spawn your HUD when the game asks you to.

gamemodeId        : The gamemode ID that the HUD manager will be responsible for.
mod               : The ID of your mod. Needs to be the same as what you provide to RegisterMod
manager           : An instance of your scene manager.

Vanilla gamemode IDs are "Race", "Time Trial", "Speed Lap", "Survival", "Knockout", "Eliminator", "Upsurge, "Track Creator", "Precision" and "Practice".

Usage Example
    CustomHudRegistry.RegisterMod("Race", "MyHudMod", new MyHudModRaceManager());

void RegisterWeaponSprite(string weaponId, string mod, Sprite sprite)
---------------------------------------------------------------------
Registers a weapon sprite override into the game.

weaponId        : The weapon ID that the sprite will be assigned to. 
mod             : The ID of your mod. Needs to be the same as what you provide to RegisterMod
sprite          : The sprite itself.

Vanilla weapon IDs are "rockets", "missile", "mines", "plasma", "energywall", "cannon", "shield", "autopilot", "emergencypack", "tremor", "turbo", "hunter" and "hellstorm"

Usage Example
    string basePath = Path.Combine(ModLocation, "Icons");
    CustomHudRegistry.RegisterWeaponSprite("rockets", "MyHudMod", LoadSpriteFromDisk(Path.Combine(basePath, "Weapon_Rockets.png"));

Sprite LoadSpriteFromDisk(string filePath)
------------------------------------------
Loads a jpg or png from disk and loads it into memory as a sprite.

filePath        : The absolute file path to the image you want to load.

Usage Example
    string path = Path.Combine(ModLocation, "MySpriteImage.png");
    Sprite mySprite = CustomHudRegistry.LoadSpriteFromDisk(path);

Sprite GetWeaponSprite(string weaponId, bool fallbackToIngame)
--------------------------------------------------------------
Returns a loaded weapon sprite for the active HUD mod. Will return null if othing is found.

weaponId                : The weapon ID to get the sprite for. See above for a list of vanilla IDs
fallbackToIngame        : Whether to fallback to the game's vanilla sprites if a sprite isn't found

Usage Example
    Sprite weaponSprite = CustomHudRegistry.GetWeaponSprite("rockets", true);

Sprite GetIngameIcon(string weaponId)
-------------------------------------
Returns an ingame weapon sprite. This is also called by GetWeaponSprite if no sprite is found while fallbackToIngame is set to true. Will return null if nothing is found.

weaponId        : The weapon Id to get the sprite for. See above for a list of vanilla IDs

Usage Example
    Sprite weaponSprite = CustomHudRegistry.GetIngameIcon("rocets");