Skip to content

Ability system: plan for the first Unity pass

Historical working record: The details below describe decisions and source state at the time they were written, including superseded plans and verification status. For current scope use the playable-game roadmap; for implemented hook usage use the hook reference; for observed checks use the CLI report and playable-path report.

This plan targets a connected implementation that is ready for an initial Unity import and focused gameplay checks. It does not require every ability, stage or platform to be perfect before opening the Editor. Existing changes are not yet compiled or gameplay-verified.

Use the Unity Editor CLI for the first import, compilation and available checks when the main integrations are mostly complete. Keep project plans, inventories, decisions and verification results in the project's docs/ directory.

Rules

  • Ability data and behavior belong in AB_ scripts. Remove individual Ability ScriptableObjects after their data and references are migrated; do not build a legacy fallback.
  • Preserve existing backend-facing ability codes and transmitted values. Dash and character abilities do not need backend codes. Revive is an upgrade action, not an equipped ability.
  • Keep Upgrade ScriptableObjects for reward information and icons. Distinguish ability identity from upgrade identity, even where the current code stores an ability's reporting code in Upgrade.idname.
  • Ability scripts register their own hooks. Do not introduce a hand-maintained central switch naming each ability. Keep final stat formulas together in the central calculation.
  • Preserve authored values and serialized references by mapping them before deletion. Do not invent IDs for ambiguous assets. Record unresolved or intentionally changed behavior.
  • Work in connected batches without a pause for each ability. Note alternative designs for discussion and continue independent work.

Milestone 1: identity and asset mapping

Trace the inventory through character selection, starting lists, Upgrade assets and prerequisites, weapon evolution, UI and leaderboard reporting. Record each relevant asset's GUID, values, corresponding AB_ script, backend code where applicable and consumers. Account for different assets sharing a script, including dash variants: a script type alone may not distinguish their data. Classify the base-script assets as actual abilities, upgrade actions, drafts or unused; do not assume each needs a new ability.

The migration audit now records the direct serialized references and known shared-script and boss-upgrade cases. Active gameplay upgrades are under Resources; the old BossUpgrade folder is development content, and SpecialUpgrade subfolders identify their status. The two dash assets existed to separate players' legacy state; both now point to one internal definition key while keeping state per player. Behavior, backend mapping and individual asset reachability still need tracing.

Ready for next milestone: the active paths have a concrete mapping and unresolved entries are listed. A draft or unused asset does not block the first Editor pass merely because it exists.

Milestone 2: definitions and player runtime

Define an ability representation with name, optional reporting code, cooldown, stamina cost and behavior creation in its AB_ script. Keep per-player mutable state and cooldowns separate from definition data. Provide a way for upgrades and character setup to reference definitions without one Ability SO per ability or a hand-written central ability factory. Select the concrete lookup method after checking Unity serialization and build constraints; a generated registry is a candidate, not an implemented decision.

Replace ScriptableObject cloning and the current script-type-only identity where needed to represent distinct definitions. Connect acquisition, duplicate handling, hook scope, cancellation, removal and reacquisition. Preserve timing differences such as Luster Burst and Ground Breaker rather than forcing them into a single timer.

Current source uses internal keys, ordinary C# definitions and player-owned state; it no longer creates Ability ScriptableObject instances. Resolving type-shared behaviors and verifying Unity integration remain unfinished.

Ready for next milestone: starting and reward abilities can be represented and acquired by the new runtime, and the remaining lifecycle gaps are recorded. No claim of runtime correctness follows from source inspection alone.

Milestone 3: connect player, upgrades and presentation

Migrate character and starting ability setup; Upgrade ability and prerequisite references; reward selection and evolution; weapon upgrades; cooldown display; ability icons and descriptions; and leaderboard reporting/icon lookup. Preserve existing upgrade IDs, backend-facing codes and serialized reward values. Handle Revive as an action. Replace asset references using the mapping before deleting the old assets.

Connect dash, weapon attacks, health, stats, visual bindings and companions to the new runtime. AbilityHolder has been replaced by PlayerAbilityBindings for visual references; scene dash input is owned by Player. Make only the GameManager, input, enemy and stage changes required to connect the ability paths; their broader overhaul is separate.

Ready for next milestone: a selected character has a starting dash and character ability, an upgrade can grant an ability, and the relevant player, UI and reporting paths use the new identity in source. Any unfinished individual ability or integration is explicitly listed.

Current source stores internal keys for character selection, player starting bindings, upgrade grants/prerequisites and MainMenu weapon-evolution entries. Unity serialization, reflection/stripping, callback resolution and gameplay are unverified; the broader holder and individual ability work remains.

Milestone 4: finish a coherent first-pass scope

Trace the actual ability families and their connected hooks, values, effects, projectiles, companion ownership and upgrades. Remove obsolete execution paths and old Ability SO references where migrated. Review evolution timers and shared counters, player removal/reacquisition, pooling and two-player isolation; implement the required ownership changes or document a specific remaining limitation.

The goal is a meaningful first run, not a promise that all 121 inventoried assets are playable or fully balanced. Do not block the Editor pass for draft content, comprehensive optimization, a full stage redesign or platform certification. Do not call an ability complete solely because its AB_ script exists.

Ready for Unity: the intended first-pass player and reward paths are connected in source, old references have been migrated or listed as known gaps, and known source-level missing types and obvious broken links have been addressed. Preserve a list of outstanding risks and scene/asset changes to inspect.

Milestone 5: first Unity import and focused checks

Once the integration above is mostly complete, use the Unity Editor CLI to import the project and report compilation and asset diagnostics. Fix compiler and asset import errors, then inspect representative character, upgrade and prefab references. Use a controlled scene where possible, and check player setup, dash, an equipped reward ability, a weapon/impact effect, a cooldown-style ability, a companion, removal/evolution and a second player as the environment permits. Use existing stage and spawning paths for a full-run check only when their dependencies are available.

Record failures and fix in connected batches. Compilation and import alone do not establish gameplay correctness. Tests, builds and full platform qualification are not prerequisites for starting the Editor pass; broaden verification when the integration is ready and the findings justify it.

Milestone 6: documentation and remaining work

After the first integrated source pass, update the ability inventory and the authoring and hook guide to match the implementation. Consolidate repeated explanations, shorten wording, update links and mark or archive historical plans while preserving useful records. Keep a short list of remaining ability, player, reward and stage work and distinguish source status from observed Unity results.