[CPLUS plus ex] Home - Redacted-Rice/ITB-RedactedRiceExts GitHub Wiki

Custom Pilot Level Up Skills and More Extension (CPLUS+ Ex)

CPLUS+ Ex is an extension that allows customizing the Pilot Level Up Skills (often also called Abilities in the game). It allows players to customize odds and what skills can appear. It allows modders to add custom level up skills to the Game.

Table of Contents

Overview

CPLUS+ Ex manages the assignment of skills to pilots. It uses memhack to modify pilot skill data in memory and ensures changes persist correctly in save files and across timelines.

The extension provides a complete API for registering custom skills, configuring their behavior, and tracking which skills are active during gameplay.

CPLUS+ Ex also features a "Modify Pilot Abilities" option in Mod Content which dynamically generates a UI for controlling all registered Level Up Skills, allowing players to easily customize skills and for modders to easily add custom skills with automatic UI integration.

Key Features

Players

  • Choose what skills are in the Game
  • Modify the odds of individual skills being chosen
  • Define relationships to prevent redundant/useless skills
  • Option to display icons next to level up skills when they are earned (defaults to enabled)

Modders

  • Create custom level up skills with automatic UI integration
  • Configure default config values for skills
    • Set default exclusions to prevent bad, redundant, or useless skill assignments
    • Automatically reads and applies exclusions for skills in the Vanilla "blacklist" field of Pilots
    • Can also define Skill to Skill exclusions
  • Track skill state across the game (enabled, in-run, active on mechs)
  • Hooks for responding to skill state changes

CPLUS+ Ex Functionality

Quick start guide for adding custom level up skills

API

Hooks

  • Events/Hooks - Events fired when skill states change (i.e. they become active)

Key Concepts

Skill Slots and Virtual Skills

Skill Slots

Skill slots are a concept for defining which level up skill on a pilot is used. In vanilla there is slot 1 & 2 for levels 1 & 2. Additionally, CPLUS+ allows for adding more "virtual" skills beyond the vanilla two slots starting with slot 3. More about virtual skills below.

For many APIs, it returns skillIdx or slots. These all support both vanilla slots (1 & 2) and virtual slots (3+). CPLUS+ overrides some memhack APIs that utilize slots/indexes as well to support virtual skills so all APIs that take indexes/slot should work for both vanilla and virtual skills unless otherwise noted.

Virtual Skills

Virtual skills are additional pilot level-up skills beyond the vanilla slots (1 and 2). They:

  • Occupy "slots" 3, 4, 5, etc.
  • Are always considered earned so only should be added to the pilot when you want them to take effect
  • Will NOT be displayed in the in game Pilot UI. I recommend adding to the pilot skill description for display
  • Are stored in Lua allocated memory rather than vanilla game structures
  • Are tracked separately but function identically to vanilla skills
  • Persist in save data via CPLUS+ extension data

Most skills should be able to be virtual but some vanilla skills are hardcoded expecting the skill slots 1 & 2 so cannot be added as virtual skills without significant effort. These current are Opener, Closer, Popular, Thick, Invulnerable, Adrenaline, Pain, Regen, Conservative

Level Up Skill Reusability

Skills can have one of three reusability settings:

  • REUSABLE (1) - Can be assigned to any pilot any number of times
  • PER_PILOT (2) - A pilot can only have this skill once (vanilla behavior)
  • PER_RUN (3) - Can only be assigned once per run across all pilots. Use for powerful skills or skills that affect the whole squad

These are incrementally more restrictive. If a skill is registered as PER_PILOT, it cannot be set to RESUABLE. This is because CPLUS+ assumes the resubility registered with reflects the programmed capabilities of the skill - i.e. if the modder implemented the skill such that it only can apply to the pilot once or uses something that only makes sense to apply once, they would use PER_PILOT

Slot Restrictions

Skills can specify which level up slots they can appear in - e.g. for the first level up, second level up or both. Typically skills are expected to allow both but some skills such as XP boosters/reducers may only make sense in the first slot while some powerful skills maybe should only go in the second slot to reward maxing out pilots.

  • ANY (1) - Can appear in any slot - vanilla behavior
  • FIRST (2) - Can appear only if first/level 1 slot
  • SECOND (3) - Can appear only if second/level 2 slot

Skill States

Skills can be in different states during gameplay:

  • Enabled - The skill is available to be selected
  • In Run - The skill has been assigned to at least one pilot in the current run. The pilot may be piloting a mech or may be in storage
  • Active - The skill is on a pilot currently piloting a mech

Additionally, there is a concept of an "earned" skill. This means the pilot has level-uped enough that the skill is now in effect

Exclusions and Inclusions

Exclusions

Exclusion are more or less what you would expect. They define criteria that will prevent skills from being selected. Currently both Pilot to Skill and Skill to Skill exclusions are supported.

The "default" type of Pilot level up skill can be assigned to any pilot and as such needs to be specifically excluded in certain cases.

Pilot to Skill exclusions are the same as the vanilla "blacklist" field on Pilots. It prevents the Pilot from recieving that skill presumably because it does not make sense, would be useless or is redundant with the pilot's main skill.

Squad to skill exclusions prevent any pilot from earning a skill when a given squad is chosen. This could be useful for excluding skill for hovering over water for an all flying squad for example.

Skill to Skill exclusions are a new concept but function similarly.

Inclusions

A new concept that allows for skills that are NOT allowed by default. These are the inversion of exclusions as they will only be assigned if the criteria is met.

Pilot level up skills can be registered as type "inclusion" in which case they are excluded by default and are ONLY available based on the defined inclusions. This could be skills that are more specific to subset of pilots or that would be too powerful on most pilots.

Squad to skill inclusions operate similarly - they ONLY are available if a squad is selected. This could be useful for skills specific to a squad such as a thematic level upgrade such as something to do with environment effects for a squad that manipulates environments for example.

Skill to Skill inclusions are not supported.

Groups

Skills can be organized into exclusion groups to prevent incompatible or highly similar skills from appearing together to prevent conflicts or to provide a better spread of skills. These do nothing unless enabled

SaveVal (registration field - deprecated)

Passing saveVal when calling cplus_plus_ex:registerSkill(...) is no longer supported. The registry ignores it and logs a warning. Pilot identity is handled by Pilot UID , not by a registered skill saveVal.

Pilot UID

Pilot ID alone is not unique when multiple pilots share the same type. CPLUS+ uses a Pilot UID (pilotId:sv1:sv2 from the saveVal pair on slots 1 and 2) so per pilot skill data stays attached to the correct instance across wrapper recreation and saves.

Persistent tables are keyed by UID:

  • GAME.cplus_plus_ex.pilotSkills[uid]
  • GAME.cplus_plus_ex.pilotVirtualSkills[uid]

When skills are applied/swapped on slots 1-2, the slot saveVal integers are treated as UID tokens and preserved. See Pilot UID for full API and minting details.

Internal Skills

Skills registered with internalSkill = true can still be set explicitly via applySkillIdsToPilot, but are omitted from the Modify Pilot Abilities UI and from random assignment pools (getAssignableSkillIds). Use cplus_plus_ex:isInternalSkill(skillOrId) to check. See Skill Registration .