User:TehRealSalt/Custom HUD Library

Interop

The following functions are designed to help mod interop and resolve HUD conflicts.

Function	Return values	Description
customhud.SetupItem(string itemName, string modName, [function(drawer, ...) itemFunc, [string hook, [number layer]]])	boolean	This function can change the display of a HUD item to another already defined type, replace an existing HUD item's drawing function, or create new custom HUD items entirely. itemName is the name of the HUD item. This can be anything from this list of base game HUD items (https://wiki.srb2.org/wiki/Lua/Functions#Togglable_HUD_items), or a new string to define a custom HUD item. modName is a string to use to identify the mod. The string "vanilla" is reserved for base game HUD items, and thus cannot be used for custom HUD items. itemFunc is the function used to draw this HUD item. This can replace the need for using the base game's hud.add at all in your mod. The function format should match the HUD hook this HUD item belongs to. hook is a string for the HUD hook (https://wiki.srb2.org/wiki/Lua/Functions#HUD_hooks) to use for newly created custom HUD items. There is also a special hook called "gameandscores", which has the function format of "scores", and will run regardless of the scoreboard being shown or not. The hook can be left out when not using custom HUD items, as all vanilla HUD items have a hook already defined. If not defined for custom HUD items, then this will get set to "game". layer is a number that determines sorting of custom HUD items. Higher numbers will be drawn on top of lower numbers. This can be left out when not using custom HUD items, as all vanilla HUD items will be put on the lowest possible layer (INT32_MIN) since there is no way to draw anything under them currently. If not defined for custom HUD items, then this will get set to 0. Returns true if no errors occurred, otherwise it will return false. Examples: customhud.SetupItem("rings", "my_mod_name", myModsRings): Creates a new drawing function for the rings HUD in this mod, and changes to it. customhud.SetupItem("bossmeter", "my_mod_name", myModsBossMeter, "game", 0): Creates a custom HUD item, using the "game" hook and on the base layer. customhud.SetupItem("time", "vanilla"): Changes the time HUD back to the original version.
customhud.enable(string itemName)	nil	Enables a HUD item. Should completely replace instances of the base game's hud.enable, as it has support for custom HUD items.
customhud.disable(string itemName)	nil	Disables a HUD item. Should completely replace instances of the base game's hud.disable, as it has support for custom HUD items.
customhud.enabled(string itemName)	boolean	Return true if a HUD item has been enabled or false if it hasn't. Should completely replace instances of the base game's hud.enabled, as it has support for custom HUD items.
customhud.ItemExists(string itemName)	boolean	Returns true if the HUD item has been defined already, otherwise false. customhud.SetupItem already handles HUD item collisions, so you shouldn't need to use this in most cases.
customhud.CheckType(string itemName)	string	Returns the current mod identifier that a HUD item is using. If the HUD item doesn't exist, then this returns nil.

Fonts

The following functions are designed to aid in drawing custom fonts more easily, without needing to write your own functions.

Function	Return values	Description
customhud.SetupFont(string fontName, [number kerning, [number space, [number mono]]])	nil	Defines a new font. This should be done before using any of the font functions. fontName is the font's prefix. This is used for determining the patch to use, which is in xxxxxyyy, where x is the font prefix and y is the ASCII decimal of each character. This cannot be longer than 5 characters. kerning is the spacing between letters. Negative numbers makes letters overlap, positive numbers are spaced farther apart. Defaults to 0. space is how many pixels a space should be. Defaults to 4. mono, makes all characters mono-spaced instead of being based on each patch size. Defaults to nil, for a variable-width font.
customhud.CustomFontString(drawer v, number x, number y, number str, string fontName, number flags, string align, number scale, number color)	nil	Draws a string in a custom font. If scale is not nil, then the X/Y coordinates are expected to be in fixed point scale, otherwise they are expected to be integers. color uses skincolors rather than the base games' text colors.
customhud.CustomFontChar(drawer v, number x, number y, number charByte, string fontName, number flags, number scale, number color)	number	Draws a single character of a custom font. Returns the X position to draw another character at, if trying to draw an entire string.
customhud.CustomFontStringWidth(drawer v, number str, string fontName, number scale)	number	Returns the width of a string if it were drawn in a custom font.
customhud.SetupNumberFont(string fontName, [number kerning, [number space, [number mono]]])	nil	Defines a new number font. Unlike standard fonts, the font prefix can be up to 7 characters long, but it only uses 0-9 as bytes to represent numbers. Generally, it's recommended to use customhud.SetupFont instead, as this is mostly only for backwards compatibility with some older mods' number font names.
customhud.CustomNum(drawer v, number x, number y, number num, string fontName, [number padding, [number flags, [string align, [number scale, [number color]]]]])	nil	Draws a number in a custom number font.
customhud.CustomNumWidth(drawer v, number num, string fontName, [string padding, [number scale]])	number	Returns the width of a number if it were drawn in a custom font. padding is the number of padding zeroes to use, set to nil for no padding.
customhud.GetFont(drawer v, table font, number charByte)	table	Returns font data from customhud.SetupFont or customhud.SetupNumberFont.
customhud.GetFontPatch(drawer v, table font, number charByte)	patch_t	Caches and returns a specific character patch from font data.