HopLib

Collection of functions and useful tools, currently mostly about retrieving information about units.

Classes

NameProvider

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 or u_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 in CharacterTweakData: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.

UnitInfoManager

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 about unit.
• UnitInfoManager:get_info(unit, [u_key], [temp]) Returns the information about unit (creates it if it doesn't have it yet). Setting the temp 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.

UnitInfo

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 as UnitInfo:name().
• UnitInfo:owner() Returns the UnitInfo 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() Returns true if the unit is a civilian.
• UnitInfo:is_special() Returns true if the unit is a special enemy.
• UnitInfo:is_boss() Returns true if the unit is a boss type enemy.
• UnitInfo:is_female() Returns true if the unit is female.

Hooks

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 before CharacterTweakData:character_map returns.

Utility

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 the path directory and loads it in localization_manager. Tries to use the registered LocalizationManager if localization_manager is not specified. Returns the language loaded.
• HopLib:load_assets(assets) Loads all files in the assets table. Entries must be tables containing ext, path and file keys and may contain an optional override key.
• HopLib:run_required(path) Runs the file matching the current RequiredScript if it exists in path.

Color Utility

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 if invert_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.

Table Utility

Additional utility functions that operate on tables:

• table.union(tbl1, tbl2, [match_type]) Merges all values from tbl2 into tbl1, replacing existing values in tbl1. If match_type is set, the value types in both tables must match to be replaced.
• table.replace(tbl1, tbl2, [match_type]) Replaces only existing values in tbl1 with values from tbl2. If match_type is set, the value types in both tables must match to be replaced.
• table.recurse(tbl, func) Calls func(value, key) for each non-table value in tbl. If the value is a table itself, calls itself on that table.

Menu Builder

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 identifier id using the table settings_table. The optional parameter settings_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 the MenuManagerBuildCustomMenus hook. The optional parameter parent_menu determines where the menu is added, defaults to the BLT mod options menu.