Quick Start Guide: Creating Custom Pilot Skills

Quick start to introduce you to creating your own custom level up skill.

You must register your skill in init() not load(). Once you do that, your skill will appear in the UI and can be enabled, disabled and assigned. That's basically it! If you are doing a simple skill that doesn't require any custom logic you are done at this point.

In the likely case you do need skill specific logic, you should tie into the hooks provided by CPLUS+ Ex related to skill states to determine when and who to apply the skills to. For examples, see the Redacted Rice Mod Pack "More+" mod. In that the common pattern is to setup events when the onActive event is fired but other hooks could be used as well depending on your goals.

You can also optionally register exclusions and other default config options but its not required.

The rest of this will walk you through those steps and explain the important information. For more details you can see the specific pages/APIs of the appropriate submodule.

Table of Contents

• Registering Your Skill
• Creating Custom Behavior
• Testing Your Skill
• Adding Exclusions (optional)
• Adding Inclusions (optional)
• Examples

Registering Your Skill

Add to init() function:

function mod:init()
    cplus_plus_ex:registerSkill("Custom", {
        id = "MyCustomSkill",
        shortName = "My Skill", -- You can also use an ID string e.g. "MySkill_ShortName_Id"
        fullName = "Some Awesome Skill", -- You can also use an ID string e.g. "MySkill_FullName_Id"
        description = "This skill does some really really cool stuff and totally isn't just Skilled", -- You can also use an ID string e.g. "MySkill_Desc_Id"
        reusability = cplus_plus_ex.REUSABLILITY.PER_PILOT, -- Currently the lowest allowed reusability setting
        bonuses = {
            health = 2,  -- +2 HP
            move = 1     -- +1 movement
        }
    })
end

Skill Properties Explained

id

Required. ID used internally to distinguish your skill

shortName

Required. Displayed on the UI in the little boxes below the pilot

fullName

Required. Often the same as shortName. Displayed in the tool tip when hovering over the skill

description

Required. Explains the skill and is displayed in the tool tip when hovering over the skill

bonuses

optional, defaults to 0

Vanilla bonuses to the various stats provided by level up skills

bonuses = {
    health = 2,  -- +2 HP
    move = 1,    -- +1 movement  
    grid = 5,    -- +5% grid defense
    cores = 1    -- +1 reactor core
}

skillType

Optional, defaults to "default"

Determines if the skill is allowed on pilots ("default") unless specifically excluded or if its disallowed on pilots ("inclusion") unless specifically allowed.

See Key Concepts: Exclusions and Inclusions for more info

reusability

optional, defaults to PER_PILOT (vanilla behavior)

Defines how skills can be assigned to pilots.

-- Can be assigned multiple times to same pilot
cplus_plus_ex.REUSABLILITY.REUSABLE

-- Once per pilot (vanilla default)
cplus_plus_ex.REUSABLILITY.PER_PILOT

-- Once per run across all pilots  
cplus_plus_ex.REUSABLILITY.PER_RUN

See Key Concepts: Reusibility for more info

weight

Optional. Defaults to 1.0

The default weight to use for this skill if you want it to appear more or less often by default.

Creating Custom Behavior

For most custom logic, use the Base Classes :

• SkillTrait - add/remove traits on pawns while active
• SkillActive - subscribe to game events while the skill is active
• SkillEffectModifier - mutate weapon SpaceDamage (built on DamageModifierLib)

Pattern: create the skill object and registerSkill in init().

local mySkill = cplus_plus_ex.baseClasses.SkillActive:new{
    id = "MyCustomSkill",
    shortName = "My Skill",
    fullName = "My Skill",
    description = "Reacts to game events",
}

function mySkill:setupEffect()
    table.insert(self.events, modApi.events.onNextTurn:subscribe(function()
        -- your logic
    end))
end

function mod:init()
    cplus_plus_ex:registerSkill("Custom", mySkill)
end

You can also subscribe directly to Events and Hooks (onSkillActive, etc.). Hook/event subscribe accepts an optional priority (DEFAULT_PRIORITY = 100, INTERNAL_PRIORITY = 0. Lower runs first).

Testing Your Skill

1. Start a new game
2. Level up pilots - your skill should appear
3. Check "Mod Content" -> "Modify Pilot Abilities" to see your skill in UI
4. Adjust weight settings and what is enabled/disabled. Disable all but your skill and another one to guarantee it will be selected
5. Enter a run and level up your pilots (~ to open up console, type xp 50, ~ again to close)

Adding Exclusions

Prevent redundant or useless skills in load():

function mod:load()
    -- Skill-to-skill exclusion. These don't play nicely or have significant overlap
    cplus_plus_ex:registerSkillExclusion("FreeShield", "ShieldOnHit")
    
    -- Pilot-specific exclusion. These don't play nicely or have significant overlap
    cplus_plus_ex:registerPilotSkillExclusions("Pilot_Zoltan", "FreeShield")
end

Adding Inclusions

Specifically allow skills in load():

function mod:load()    
    -- Pilot-specific inclusion. These maybe are too powerful or behave oddly on most pilots
    cplus_plus_ex:registerPilotSkillInclusions("Pilot_Entborg", "growth")
end

Examples

Simple Replacement Skill

Replace vanilla Health with improved version:

function mod:init()
    cplus_plus_ex:registerSkill("Vanilla+", {
        id = "HealthPlus",
        shortName = "Health_Plus_Short",
        fullName = "Health_Plus_Name",
        description = "Health_Plus_Desc",
        reusability = cplus_plus_ex.REUSABLILITY.REUSABLE,
        bonuses = {health = 3},  -- +3 instead of +2
        weight = 1.0,
        enabled = true
    })
end

function mod:load()
    modApi:setText("Health_Plus_Short", "Health+")
    modApi:setText("Health_Plus_Name", "Health +3")
    modApi:setText("Health_Plus_Desc", "Piloted Mech health is increased by 3")
    
    -- Disable vanilla (forceApply=true so it still works after config was loaded)
    cplus_plus_ex:disableSkill("Health", true)
    
    -- Copy vanilla exclusions
    cplus_plus_ex:registerPilotSkillExclusions("Pilot_Zoltan", "HealthPlus")
    cplus_plus_ex:registerPilotSkillExclusions("Pilot_Rock", "HealthPlus")
end

More Complex Custom Skill

See More+ and the base class pages for full SkillActive/SkillEffectModifier examples.

Getting Help

Head over to the RedactedRice Discord and post in any appropriate channel