Collection of functions and useful tools, currently mostly about retrieving information about units.
Provides names based on a unit name or tweak_data id. The active NameProvider
instance can be retrieved by calling HopLib:name_provider()
. There are two functions that can be called on the NameProvider
instance:
NameProvider:name_by_id(tweak)
Returns the name based on the tweak_data id.NameProvider:name_by_unit(unit, [u_key])
Returns the name based on the unit oru_key
if you provided it, which is useful if the unit doesn't actually exist currently. This is done through a lookup table, so it is not guaranteed to return a name (Only works for units defined inCharacterTweakData:character_map()
which should contain all human enemies).
The names are taken from the localization file if available, otherwise the modified string id (Capitalized words, removed underscores, etc) will be used as the name.
Can be used to return information about a unit. Unit infos are created upon request (i.e. a call to get_info
) or by HopLib in certain cases. The following functions can be called on the active UnitInfoManager
instance, which can be retrieved by calling HopLib:unit_info_manager()
:
UnitInfoManager:all_infos()
Returns a table (indexed by unit key) containing all unit infos.UnitInfoManager:clear_info(unit, [u_key])
Clears the information aboutunit
.UnitInfoManager:get_info(unit, [u_key], [temp])
Returns the information aboutunit
(creates it if it doesn't have it yet). Setting thetemp
argument to true will retrieve the unit information but not save it.
Providing the optional u_key
skips the function's internal unit:key()
which might be useful if the unit has already been deleted but you have its key.
The UnitInfoManager
creates and returns UnitInfo
instances, which contain information about the unit. The following functions can be called on a UnitInfo
retrieved from the UnitInfoManager
:
UnitInfo:unit()
Returns the unit.UnitInfo:key()
Returns the unit key.UnitInfo:id()
Returns the unit id.UnitInfo:type()
Returns the type of the unit. Possible values are"local_player"
,"remote_player"
,"npc"
,"team_ai"
,"joker"
,"sentry"
and"vehicle"
.UnitInfo:name()
Returns the name of the unit.UnitInfo:nickname()
Returns the nickname of the unit (used for jokers and sentries). If it doesn't have one, returns the same asUnitInfo:name()
.UnitInfo:owner()
Returns theUnitInfo
of the unit owner if it has one (used for jokers and sentries).UnitInfo:damage()
Returns the amount of damage the unit has dealt.UnitInfo:kills()
Returns the number of kills the unit made.UnitInfo:peer()
Returns the peer object if the unit is of type"player"
.UnitInfo:level()
Returns the level if the unit is of type"player"
.UnitInfo:rank()
Returns the infamy rank if the unit is of type"player"
.UnitInfo:color_id()
Returns the color id of the unit.UnitInfo:is_civilian()
Returnstrue
if the unit is a civilian.UnitInfo:is_special()
Returnstrue
if the unit is a special enemy.UnitInfo:is_boss()
Returnstrue
if the unit is a boss type enemy.UnitInfo:is_female()
Returnstrue
if the unit is female.
HopLib provides the following hooks:
HopLibOnMinionAdded
with parameters(unit, player_unit)
Called when an enemy is converted by a player.HopLibOnMinionRemoved
with parameters(unit)
Called when a converted enemy is removed (died, released, etc).HopLibOnUnitDamaged
with parameters(unit, damage_info)
Called whenever a unit takes damage.HopLibOnUnitDied
with parameters(unit, damage_info)
Called when a unit dies.HopLibOnCharacterMapCreated
with parameters(char_map)
Called beforeCharacterTweakData:character_map
returns.
HopLib also provides some utility functions:
HopLib:get_game_language()
Returns the language the game is set to as a string.HopLib:get_modded_language()
Returns the language the game is set to through mods.HopLib:load_localization(path, [localization_manager])
Automatically chooses the correct language file in thepath
directory and loads it inlocalization_manager
. Tries to use the registeredLocalizationManager
iflocalization_manager
is not specified. Returns the language loaded.HopLib:is_object_of_class(object, c)
Returnstrue
ifobject
is of classc
, either directly or by inheritance.HopLib:load_assets(assets)
Loads all files in theassets
table. Entries must be tables containingext
,path
andfile
keys and may contain an optionaloverride
key.
Additional utility functions that operate on color values:
Color:grayscale()
Returns a grayscale version of the color by taking the average of all color channels.Color:invert([invert_alpha])
Returns the inverse of the color, inverting the alpha channel ifinvert_alpha
is set.
All color utility functions operate on the game's color objects (e.g. Color.black:invert()
) and return a new Color rather than changing the existing one.
Additional utility functions that operate on tables:
table.union(tbl1, tbl2)
Merges all values fromtbl2
intotbl1
, replacing existing values in tbl1.table.replace(tbl1, tbl2, [match_type])
Replaces only existing values intbl1
with values fromtbl2
. Ifmatch_type
is set, the value types in both tables must match to be replaced.table.recurse(tbl, func)
Callsfunc(value, key)
for each non-table value intbl
. If the value is a table itself, calls itself on that table.
Automatically creates a options menu from an identifier and a settings table. The following functions exist:
MenuBuilder:new(id, settings_table, [settings_params])
Creates a new menu builder with the mod identifierid
using the tablesettings_table
. The optional parametersettings_params
allows to specify custom ranges, items and priorities for specific settings.MenuBuilder:save_settings()
Saves the current settings. Called automatically when settings are changed via the options menu.MenuBuilder:load_settings()
Loads previously saved settings. Called automatically when the menu builder is created.MenuBuilder:create_menu(menu_nodes, [parent_menu])
Creates the menu.menu_nodes
are the existing menu nodes obtained in theMenuManagerBuildCustomMenus
hook. The optional parameterparent_menu
determines where the menu is added, defaults to the BLT mod options menu.