Skip to content

feat(practice): per-ring guided hints, Ring-N-of-M progress, and retry mechanic #173

@TheMeinerLP

Description

@TheMeinerLP

Description

MapDefinition gains optional per-ring hint text to guide players in Practice Mode. The HUD shows ring progress instead of a competitive score bar. Players can retry instantly via teleport and state reset.

Acceptance Criteria

  • MapDefinition JSON ring entries accept an optional `hint` string field (e.g. `{"id": 1, "type": "STANDARD", "hint": "Fly through the green ring!"}`)
  • Absent `hint` fields are deserialized as `null` / `Optional.empty()` — no validation error
  • In Practice Mode, entering a ring with a non-null hint displays the hint as an action bar or title message
  • Hint display duration is configurable (default: 3 seconds)
  • HUD shows ring progress as `Ring N of M` instead of the competitive score bar in Practice Mode
  • A retry action (command or item interaction) teleports the player to the map spawn point
  • On retry, all ring-tracker state is reset (rings completed = 0, timer = 0)
  • No world reload occurs during retry — pure state reset + teleport
  • Gson adapter (`RingEntryAdapter`) handles absent `hint` field gracefully
  • Unit tests cover: hint deserialization (present, absent, null), HUD switch, retry state reset

Technical Details

  • `hint` is stored in the ring DTO/record (e.g. `RingEntry`); existing entries without `hint` remain valid JSON
  • `RingEntryAdapter` lives in `adapter` subpackage, is `final`, follows Gson Adapter naming convention
  • `HudComponent` gains a `mode` discriminator or Practice-specific fields (record, compact constructor validates)
  • Retry state reset must invoke the same ring-tracker initialization path used at map start

Dependencies

Estimate

M

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestgameplayGameplay mechanicsplayer-feelGame feel, feedback timing, or player experience

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions