Add character-specific aliases to the Action enum #15

New issue

Open

opened 2026-08-22 01:41:48 +00:00 by JayKobe6k · 0 comments

JayKobe6k commented

2026-08-22 01:41:48 +00:00

Owner

Problem

Action is a single global enum, but Melee action IDs above the common state range are character-relative. The same raw value therefore has different meanings for different fighters. For example, raw action 341 is canonically named LASER_GUN_PULL, but for Mewtwo it is Shadow Ball ground charge startup; raw action 369 is canonically MARTH_COUNTER, but for Donkey Kong it is Giant Punch ground charge startup.

Current character-aware tables correctly retain the fighter as part of interpretation, but declarations such as Action(341) are difficult to read and audit.

Proposed change

Add explicit character-prefixed aliases for character-relative action states, for example:

class Action(Enum):
    LASER_GUN_PULL = 341
    MEWTWO_SHADOW_BALL_GROUND_START_CHARGE = 341

    MARTH_COUNTER = 369
    DK_GIANT_PUNCH_GROUND_CHARGE_STARTUP = 369

Derive and verify aliases against the authoritative per-character doldecomp MotionState tables rather than formatted action labels.

Python enum aliases intentionally share identity with the first declared member. Consequently, this change improves source readability only: Action(341).name will remain the canonical first name, and runtime interpretation must continue using (Character, Action) rather than treating an alias as distinct state.

Acceptance criteria

Add character-prefixed aliases for the supported roster's character-relative special-action states.
Preserve every existing numeric value, canonical member, iteration behavior, and comparison behavior.
Keep character-aware slot and classification tables; do not flatten aliases into character-agnostic action sets.
Document the alias identity and canonical .name behavior.
Update strict type stubs and relevant bot-facing declarations to use readable aliases where doing so is unambiguous.
Add tests covering representative collisions such as Mewtwo/Fox at 341 and DK/Marth at 369.

Reference

doldecomp character motion-state tables: github.com/doldecomp/melee@68f92c47d6/src/melee/ft/chara

## Problem `Action` is a single global enum, but Melee action IDs above the common state range are character-relative. The same raw value therefore has different meanings for different fighters. For example, raw action `341` is canonically named `LASER_GUN_PULL`, but for Mewtwo it is Shadow Ball ground charge startup; raw action `369` is canonically `MARTH_COUNTER`, but for Donkey Kong it is Giant Punch ground charge startup. Current character-aware tables correctly retain the fighter as part of interpretation, but declarations such as `Action(341)` are difficult to read and audit. ## Proposed change Add explicit character-prefixed aliases for character-relative action states, for example: ```python class Action(Enum): LASER_GUN_PULL = 341 MEWTWO_SHADOW_BALL_GROUND_START_CHARGE = 341 MARTH_COUNTER = 369 DK_GIANT_PUNCH_GROUND_CHARGE_STARTUP = 369 ``` Derive and verify aliases against the authoritative per-character doldecomp `MotionState` tables rather than formatted action labels. Python enum aliases intentionally share identity with the first declared member. Consequently, this change improves source readability only: `Action(341).name` will remain the canonical first name, and runtime interpretation must continue using `(Character, Action)` rather than treating an alias as distinct state. ## Acceptance criteria - Add character-prefixed aliases for the supported roster's character-relative special-action states. - Preserve every existing numeric value, canonical member, iteration behavior, and comparison behavior. - Keep character-aware slot and classification tables; do not flatten aliases into character-agnostic action sets. - Document the alias identity and canonical `.name` behavior. - Update strict type stubs and relevant bot-facing declarations to use readable aliases where doing so is unambiguous. - Add tests covering representative collisions such as Mewtwo/Fox at `341` and DK/Marth at `369`. ## Reference - doldecomp character motion-state tables: https://github.com/doldecomp/melee/tree/68f92c47d697c98e80911a14218f74982915acc9/src/melee/ft/chara