Api List - MemeMayhem/ModExamples GitHub Wiki

---@class AttributeDataConfigDisplayRequirements
---@field always_hide boolean hide this attribute in UI
---@field always_show boolean always show this attribute in UI
---@field is_hero boolean only show this attribute for hero
---@field default_value number the default value of the attribute, by default it is 0. The color will change based on this value
---@field perk string the attribute will only show when the unit has this perk
---@field relic string the attribute will only show when the unit has this relic
---@field missile string the attribute will only show when the unit has this missile(emoji)
---@field max number it will display in format current/max

---@class AttributeDataConfig
---@field id string
---@field display_name string
---@field description string
---@field flavor_text string
---@field icon string
---@field display_type fun(value:number):string the function to display the attribute value, like percentage, integer, or large number with comma
---@field min_value number the minimum value of the attribute used for CombatUnit:GetBoundedAttribute
---@field max_value number the maximum value of the attribute used for CombatUnit:GetBoundedAttribute
---@field is_neutral boolean the color of the attribute in UI will not change
---@field is_negative boolean the color of the attribute in UI will be reversed: green->red, red->green
---@field display_requirements AttributeDataConfigDisplayRequirements
---@field granularity number related to how many icons flying to the attribute panel when get this attribute, usually it is 1 or 0.01

---@param config AttributeDataConfig
Api:RegisterAttribute(config)

---@class MissileData
---@field id string
---@field display_name string
---@field tip string the description of the missile
---@field flavor_text string flavor text in the description
---@field icon string
---@field missile string SimpleUnit
---@field impact string SimpleUnit
---@field damage number the damage of the missile if it is a fixed value
---@field sounds table<string> random sound will be played from this list
---@field spin_speed number default is 0, set how fast the missile will spin in degrees per second
---@field target_self boolean if true, the missile will target the caster
---@field undodgeable boolean if true, the missile cannot be dodged
---@field flight_time number 0.75 for missile and 1 for ult. It only affect how long the missile actor will be removed, wont affect when the actual effect is applied
---@field static boolean|nil only affect ultimate. boolean if true, the missile will not rotate and the facing will depend on the caster is player or enemy

---@param missile_id string
---@param config MissileData
---@param initializer fun(unit:CombatUnit) the function to initialize the missile when its applied or loaded
Api:RegisterMissile(missile_id, config, initializer)

---@class DefaultMissileAttackData
---@field is_critical boolean
---@field is_dodged boolean
---@field direction integer  -- [Visual] launch direction 0 for left, 1 for right. You can set direct_move = true to make it move straight
---@field missile_id string
---@field damage number|nil
---@field direct_move boolean|nil  -- [Visual] move straight to the target

---Set this damage will overwrite the damage passed in Api:RegisterMissile
---Use this when you want to write a function to calculate the damage
---The attack_data passed in only has the first 4 fields filled in at the moment
---@param missile_id string
---@param damage_setter fun(attack_data:DefaultMissileAttackData, caster:CombatUnit):number
Api:SetMissileDamage(missile_id, damage_setter)

---Set what happens when the missile hits the target
---@param missile_id string
---@param impact_callback fun(attack_data:DefaultMissileAttackData, caster:CombatUnit, target:CombatUnit)
Api:SetMissileImpact(missile_id, impact_callback)

---Set this sound will overwrite the sound passed in Api:RegisterMissile
---You can just put the sounds list in the config of Api:RegisterMissile
---@param missile_id string
---@param sounds table<string>
Api:SetMissileHitSound(missile_id, sounds)

---Similar as Api:RegisterMissile, but the missile will be used as ultimate
--- the config only accepts id, icon, missile, spin_speed, flight_time, static
---@param ultimate_id string
---@param config MissileData
Api:RegisterUltimate(ultimate_id, config)

---Set sound when the ultimate is launched
---@param character_id string
---@param sound string
Api:SetUltimateLaunchSound(character_id, sound)

---Set sound when the ultimate hits the target
---@param character_id string
---@param sound string
Api:SetUltimateHitSound(character_id, sound)

---Tooltip will display the description of attribute or missile, or the description of keyword
---@class ExtraTooltip
---@field name string
---@field type string keyword, attribute, missile

---@class BehaviorData
---@field description string if not set, the perk description will be shown in buff bar
---@field is_positive boolean|nil the label of the buff will be green if true, red if false|nil
---@field buff_bar_icon string
---@field duration number|nil how long does 1 stack last. If set to nil, the behavior will be permanent
---@field modify_attributes table<string, number> modify attributes when the behavior is applied
---@field interval number|nil behavior with intervals only use one instance (and thus do not support durations)
---@field interval_effect table<string, boolean>|nil used along with interval, now only support stun, disarm and absorb_damage

---@class PerkData
---@field id string
---@field display_name string
---@field description string
---@field flavor_text string flavor text in the description
---@field icon string
---@field perk_type string perk or missile, only affect display text in perk card
---@field rarity string  common | rare | epic | legendary | divine
---@field is_player_only boolean|nil this perk will not appear on enemy
---@field attacks table<string, number>|nil list of missile id that be applied
---@field extra_tooltips table<ExtraTooltip>|nil
---@field scaling_values table|nil values that will be scaled by level, custom your own keys here
---@field non_scaling_values table|nil values that will not be scaled by level, custom your own keys here
---@field modify_attributes table|nil modify attributes of the owner
---@field behavior BehaviorData some perk can apply behavior to caster or target, you can also create a dummy perk only used for behavior so it can be used in multiple perks
---@field description_replacement_values table replace VAR1, VAR2, ... in description with values found from address in the relic data
---@field max_level number|nil the perk will not appear in the perk selection if the owner already has the perk at max level
---@field triggering_event string|nil OnWin: scaling_values will by applied to modify attribute. OnHealthThreshold: emergency behaviors will be applied. Rush: rush behaviors will be applied

---@param perk_id string
---@param config PerkData
---@param initializer fun(unit:CombatUnit) add register callbacks when the perk is applied or loaded
Api:RegisterPerk(perk_id, config, initializer)

---Override the fields of a perk of the passed in config
---@param perk_id string
---@param override_config PerkData
Api:ModifyPerk(perk_id, override_config)

---@class RelicData
---@field id string
---@field display_name string
---@field description string
---@field icon string
---@field text_icon string|nil if the relic has text_icon and the rarity is rare, epic or legendary, then it can be trade in the trade offer choice
---@field rarity string permanent | rare | epic | legendary | combo | divine
---@field attacks table<string, number>|nil list of missile id that this perk will be applied to
---@field extra_tooltips table<ExtraTooltip>|nil
---@field scaling_values table|nil values that will be scaled by level, custom your own keys here
---@field non_scaling_values table|nil values that will not be scaled by level, custom your own keys here
---@field modify_attributes table|nil modify attributes of the owner
---@field behavior BehaviorData some perk can apply behavior to caster or target, you can also create a dummy perk only used for behavior so it can be used in multiple perks
---@field description_replacement_values table replace VAR1, VAR2, ... in description with values found from address in the perk data
---@field max_level number|nil the perk will not appear in the perk selection if the owner already has the perk at max level
---@field sl_break boolean|nil if true, the relic will be destroyed when S/L
---@field minimum_ascension number|nil the relic will be removed if ascension is lower than the requirement
---@field dependent_perk_chains table<table>|nil list of perk chains that this perk is dependent on, the perk chain is the reference of the table
---@field triggering_event string|nil only support OnWin: scaling_values will by applied to modify attribute.

---Register a new relic
---@param name string
---@param config RelicData
---@param initializer fun(combat_unit:CombatUnit) add register callbacks when the relic is applied or loaded
---@param add_to_pool boolean whether add the relic to the relic pool, so it can appear in shop or drop from boss
Api:RegisterRelic(name, config, initializer, add_to_pool)

---@param character_id string
---@param relic_combos table<string, table<string, number>> the relic combo table of relic ids registred by Api:RegisterRelic
Api:RegisterRelicCombos(character_id, relic_combos)
---relic_combos example
local relic_combos = {
    angry_troll = {
        formula = {
            health_regen_percentage = 1,
            fire_cracker = 1,
        },
    },
    bottled_danger = {
        formula = {
            glass_cannon = 1,
            nuke = 1,
        },
    },
}

---Trigger some custom events when a perk or relic is applied(when you get a new perk or relic)
---Check out Advanced-Mod1 of our [mod examples]
---@param name string
---@param callback fun(unit_data:CombatUnit, perk_or_relic_data:PerkData|RelicData, is_perk:boolean)
Api:RunPerkRelicOnApplyEvent(name, callback)

---@class CharacterConfig
---@field id string the unique id of the character to avoid conflict with build-in characters or other mods
---@field display_name string if not set, the id will be used as the display name
---@field short_description string will display in the character selection
---@field icon string 500x500 will used in combat
---@field icon_low_resolution 152x152, display as small icon in the character selection
---@field icon_high_resolution string 1024x1024 will used in character selection background
---@field icon_high_resolution_size table<string, number> { width = 700, height = 700}, the size of the icon_high_resolution
---@field unit string Unit
---@field attributes table<string, number> modify the initial attributes of the character
---@field relics table<string> a list of relic ids registred by Api:RegisterRelic
---@field attack_ids table<string> a list of missile ids registred by Api:RegisterMissile
---@field perk_chains table<table<string>> a list of perk chains, the table reference can be used in dependent_perk_chains in RelicData
---@field blocked_perks table<string> a list of perk ids that will not appear in the perk pool
---@field blocked_relics table<string> a list of relic ids that will not appear in the relic pool

---@param new_character_id string this id will be used as the character_id in the game
---@param character_id string the base character id, all the missing fields in the config will be copied from the base character
---@param config CharacterConfig the id in this config will be overwritten by new_character_id
Api:CreateCharacter(new_character_id, character_id, config)

---Copy the base character and create a new character using Api:CreateCharacter
---@param base_character_id string all the missing fields in the config will be copied from the base character
---@param config CharacterConfig the id in this config will be used as new_character_id
Api:CopyCharacter(base_character_id, config)

---Set the initial magazine of the character, you can put this in the character config as "attack_ids"
---@param character_id string
---@param magazine table<string> the missile table of missile ids registred by Api:RegisterMissile
Api:SetCharacterStartMagazine(character_id, magazine)

---@class ChoiceOptionData
---@field flavor string the option description
---@field description string preview the consequence of the choice if it is discovered
---@field sound string|nil sound to play when the option is selected
---@field modify_attributes table<string, number> modify attributes when the option is selected
---@field aftermath_narrative string the content when this option is selected
---@field aftermath_description string display in the consequence bar after the option is selected
---@field gain_relics table<string, number> gain relics when the option is selected
---@field lose_relics table<string, number> lose relics when the option is selected
---@field values table<string, number> now only support get or lose gold
---@field description_replacement_values table replace VAR1, VAR2, ... in description and aftermath_description with values found from address in the option data
---@field requirement table|nil lock the option if requirement is not met

--- There are the requirements that we support now
options = {
    ...
    {
        ...
        -- limit relic
        requirement = {
            relic = "trolley_switch",
        },
    },
    {
        ...
        -- limit perk
        requirement = {
            perk = "gain_attack",
        },
    },
    {
        ...
        -- limit relic rarity
        requirement = {
            relic_rarity = "epic",
        },
    },
    {
        ...
        -- limit attributes, you can set multiple attributes, all of them must be satisfied to unlock
        requirement = {
            attributes = {
                attack = 30,
            },
        },
    },
    {
        ...
        -- limit selected options in previous events, all of them must be satisfied to unlock
        requirement = {
            choice_selected = {
                ["my_choice_id"] = { 1 },
            },
        },
    },
}

---@class ChoiceData
---@field id string
---@field display_name string the title of the choice
---@field image string
---@field description string the content of the choice
---@field options ChoiceOptionData
Api:RegisterChoice(choice)

---Set the choice pool of this character, you can get public pool names in the Choices Page
---@param character_id string
---@param list table<string> a list of choice ids registred by Api:RegisterChoice or in public pool
Api:SetChoicePool(character_id, list)

---Custom the choice to only appear in certain waves
---[min_wave, max_wave] are the range of waves, can be set to nil to indicate no lower or upper limit
---@param choice_id string
---@param min_wave number|nil
---@param max_wave number|nil
Api:RegisterWaveRequiredChoices(choice_id, min_wave, max_wave)

---Custom the choice to only appear in certain waves
---[min_wave, max_wave]are the range of waves (can't be nil). If they are equal, the event will only appear in this wave, otherwise it will appear in the range of waves．
---If more than one `RegisterWaveSpecialChoices` is registered in the same wave, the game will randomly select one of them.
---@param choice_id string
---@param min_wave number
---@param max_wave number
---@param limit_characters table<string>|nil list of character ids that can trigger this event, if empty then all characters can trigger this event (not recommended as it will affect other mods)
Api:RegisterWaveSpecialChoices(choice_id, min_wave, max_wave, limit_characters)

---@class BossData
---@field id string
---@field display_name string
---@field string Unit
---@field icon string
---@field icon_high_resolution string
---@field cosmetic_data table change ultimate by ultimate_id, the ultimate must be registerd in Api:RegisterUltimate or use an existing ultimate
---@field attributes table<string, number> set attributes value
---@field perks table<string, number> the perk ids and levels of the boss
---@field relics table<string> relics ids the boss has
---@field rewards table<string, table<string>>|nil only used for reconcile_relics={"relic_id",...}, it will trigger reconcile event if set
---@field lines table<string, table<string|table<string>>> trash talk of the boss, check example in Advanced-Mod2. Text can be set randomly, or send multiple in one time
Api:RegisterBoss(config)

---Set the boss pool of this character, you can get public pool names in the Boss Page
---@param character_id string the id of this mod character
---@param list table<string> a list of boss ids registred by Api:RegisterBoss or in public pool
Api:SetCampaignBossPool(character_id, list)

---@class CampaignEnemySettings
---@field health_base number
---@field health_growth number affected by mini_boss_power_up, boss_power_up, shop_growth
---@field damage_base number
---@field damage_growth number affected by mini_boss_power_up, boss_power_up, shop_growth
---@field rock_base number
---@field rock_growth number affected by mini_boss_power_up, boss_power_up, shop_growth
---@field dodge_base number
---@field dodge_growth number affected by mini_boss_power_up, boss_power_up, shop_growth
---@field mini_boss_power_up number growth on mini boss every 5 waves
---@field boss_power_up number growth on boss every 10 waves
---@field shop_growth number growth on shop every 5 waves

---Modify the difficulty growth of the battle, check Basic-ModDifficulty
Api:SetCampaignEnemySettings(character_id, settings)

---Gold in combat can be negative, default is false
---You want to trigger this when get an relic or perk
Api:AllowNegativeGold()
---Example
Api:RegisterRelic(
    -- relic id and data
    "my_allow_debt",
    {
        id = "my_allow_debt",
        display_name = "Debt",
        description = "Allow negative gold",
        icon = DCEI.Texture("smh_cookie"),
        rarity = "permanent",
        max_level = 1, -- you can only get 1 of this relic
    },
    -- initializer, whenever this relic is applied or loaded, it will trigger allow negative gold
    function()
        Api:AllowNegativeGold()
    end,
    true -- add to relic pool
)

---Do the callback after the duration
---@param callback fun()
---@param duration number seconds
---@param execute_on_terminate boolean if true, the callback will be executed when all the timers are cleared on battle end
Api:RunTimer(callback, duration, execute_on_terminate)

---Do the callback after the duration, will not execute when the battle ends
---@param callback fun()
---@param duration number seconds
---@param missile_owner_id number 1 - player, 2 - enemy used for blackhole and paradox_warlock to eliminate the missile effect
Api:RunCombatOnlyTimer(callback, duration, missile_owner_id)

---Get a random integer between [min, max], ensure the same result after S/L
---@param min number
---@param max number
---@return number
Api:RandomInt(min, max)

---Get a random float between [min, max], ensure the same result after S/L
---@param min number
---@param max number
---@return number
Api:RandomFloat(min, max)

---Add gold in combat
Api:AddGold(amount)

---Get gold in combat
Api:GetGold(amount)

---@class FloatingCombatTextArgs
---@field color string example "<color=red>" "<color=#54bdff>"
---@field size string example "<size=100%>"
---@field show_duration number the duration of the floating text. There is a short, fixed fade in and out duration at the start and end, respectively. If duration this is longer than the anim_duration, this duration will be used.
---@field anim_duration number The duration of the animation. If this duration is longer than the show_duration, this duration will be used.
---@field anim_type number the animation of the floating text. 0 - Text pops in. 1 - text slowly floats upwards
---@field center_at_unit boolean the text will display at the unit center
---@field horizontal_offset number the text will display to the left or right of the unit
---@field use_impact_offset boolean the text will display above the impact FX
---@field offset_radius number the text will display at a random offset within this radius

---Display text in combat, like damage number, or status text 
---@param combat_unit CombatUnit
---@param content string
---@param args FloatingCombatTextArgs
Api:DisplayFloatingCombatText(combat_unit, content, args)

---By default the log is enabled, if you don't want to print a lot of logs, you can disable it
Api:EnableLog(enable)

---Print a log message for debugging
---Press Ctrl + F8, then click "Open local mods folder" to find the log file
Api:Log(message)

---Using the following functions to print the latest data
Api:PrintCharacters()
Api:PrintAttributes()
Api:PrintMissiles()
Api:PrintPerks()
Api:PrintRelics()
Api:PrintChoices()
Api:PrintBosses()

Api:GetCharacterData(character_id)

Api:GetAllCharacterData()

Api:GetCampaignData()