Cosmetics API

Cosmetics API

Developer library to simplify adding new Crossroads cosmetics to Hades II. Does nothing by itself.

Features

Through this library, you can easily add new cosmetic items to the Crossroads, as offered by Dora.

You can add alternative versions of any existing cosmetic, both "Alt Decor" and "Extra Decor" items are supported.

Adding entirely new cosmetics (in different locations), or replacing assets that aren't already a cosmetic is not supported.

The library will automatically handle grouping cosmetics so that equipping one will unequip any other already equipped cosmetic in the same group.

You can provide names, descriptions and flavour texts for various languages, as well as customize the voicelines used when purchasing, equipping or unequipping the cosmetic.

For even more advanced usecases, you can also provide a function name that is called when your cosmetic is bought or equipped.

You can also register new Arcana Card Back packs. The API handles shop integration, animation hookup and pagination when the card back selection screen exceeds one page.

Usage

Start by adding NikkelM-Cosmetics_API as a dependency in your.toml (ensure you use the latest version):

NikkelM-Cosmetics_API = "1.0.0"

Next, include the Cosmetics API in your main.lua, alongside other dependencies:

---@module "NikkelM-Cosmetics_API"

CosmeticsAPI = mods["NikkelM-Cosmetics_API"]

Registering Packages

If your cosmetics use custom textures bundled in.pkg files, you can register those packages so the API loads them when entering the Crossroads.

Place your.pkg (and.pkg_manifest) files in your mod's plugins_data folder and call RegisterCrossroadsPackages with a table of package names (without the.pkg extension):

CosmeticsAPI.RegisterCrossroadsPackages({ "AuthorName-ModNameCosmetics" })

The API will automatically load all registered packages when the player enters the Crossroads (including the Training Grounds), regardless of which transition is used (DeathAreaRoomTransition, HubPostBountyLoad, or HubPostDreamLoad).

Duplicate package names are silently ignored.

You can alternatively also load the packages yourself within your mod code.

Registering Cosmetics

Now, you can add a new cosmetic by calling CosmeticsAPI.RegisterCosmetic(cosmeticData), where cosmeticData is of type CosmeticData.

If you have your development environment set up correctly, VS Code should offer autocompletion and type hints for this table.

Otherwise, you can always refer to the def.lua file in the Cosmetics API source, or the below example, for all available fields.

CosmeticsAPI.RegisterCosmetic({

-- REQUIRED FIELDS

Id = _PLUGIN.guid.. ".".. "Cosmetic_Pillars_Chronos",

-- At least "en" must be provided for Name, Description and FlavorText

Name = {

en = "Pillars, Timeless",

de = "...",

},

Description = {

-- "{$Keywords.CosmeticSwap}:" resolves to "Alt Decor" with a tooltip for something that replaces something, "{$Keywords.CosmeticAltAdd}:" to "Extra Decor" with a tooltip that it adds or replaces something similar, and {$Keywords.CosmeticAdd} resolves to "Extra Decor" for something that did not exist before. You should not need to use CosmeticAdd, since all cosmetics added through the Cosmetics API replace an existing cosmetic.

en = "{$Keywords.CosmeticSwap}: Time-worn monoliths that stand tall to either side of the {#BoldFormatGraftDark}Cauldron{#Prev}.",

de = "...",

},

FlavorText = {

en = "Nothing stands the test of time they say, yet these pillars beg to differ.",

de = "...",

},

-- Which of Dora's shop locations to add this cosmetic to. One of "CosmeticsShop_Tent" (Mel's Tent), "CosmeticsShop_Main" (Crossroads Main Grounds & West), "CosmeticsShop_Taverna" (Taverna & Crossroads West), "CosmeticsShop_PreRun" (Training Grounds)

ShopCategory = "CosmeticsShop_Main",

-- Which existing cosmetic the new one is a variant of

CosmeticsGroup = "Cosmetic_CauldronPillars01",

-- The in-world asset when the cosmetic is equipped

CosmeticAnimat