Contextual Event Help and Tutorial Content - UQcsse3200/2026-studio-3 GitHub Wiki

Overview

Owner: Yihan Wu
Feature: #339 — New Player Battle Tutorial and Contextual Event Help
Task: #392 — Dice and Card Fusion Contextual Help & Tutorial Prompts

This work provides lightweight contextual rules Help for the Dice and Card Fusion Events and reusable battle tutorial prompt content for the guided battle flow.

The contextual Help is intentionally observational: opening or closing it must not resolve an Event choice, reset the current interaction, or mutate encounter state.

Contextual Event Help

A reusable Scene2D Help dialog provides:

  • A title.
  • Short rules text.
  • A Close action.
  • A small ? button in supported encounter views.

Dice Event

The Dice Event provides Help throughout its staged interaction.

The rules text explains:

  • Low: 2–6.
  • High: 8–12.
  • Lucky Seven behaviour.
  • Gold stakes and Double Down escalation.
  • Cash Out and round-two card rewards.
  • Loss conditions.

The Help control is kept outside the rebuilt choice area so that it remains available as the Dice interaction progresses through different stages.

Opening or closing Help does not resolve a Dice choice, reset the Dice session, or change rewards.

Card Fusion Event

Contextual Help is available:

  • Before entering the delegated Card Fusion selection flow.
  • While selecting cards in the Card Fusion selection view.

The Help explains that the player selects exactly three distinct owned Common card copies, including different copies with the same card name, and replaces them with one random Rare card. A successful Fusion is limited to once per run.

Opening or closing Help does not change:

  • Current card selections.
  • PlayerDeck.
  • RunState.
  • Fusion allowance.
  • Delegated Event session state.
  • Event completion state.

Ordinary Chance Events do not receive the contextual Help button.

For the underlying Event mechanics, see the Chance Encounter System.

Battle Tutorial Prompt Content

The task also provides short reusable prompt text for the guided battle tutorial.

The supplied concepts cover:

  1. Opening hand / five cards.
  2. Card cost.
  3. Energy.
  4. Health.
  5. Buffs and status effects.
  6. Card drawing.
  7. End Turn and turn structure.
  8. Win / loss conditions.

The content is implemented in BattleTutorialPromptContent.

This task owns the wording only. Tutorial step ordering, gameplay triggers, progression conditions, highlights, and prompt presentation are owned by the tutorial guidance components.

The prompt content is consumed by the tutorial progression / guidance flow rather than duplicating rule text in the controller.

Integration Boundary

This task does not change:

  • Dice mechanics or Event probabilities.
  • Card Fusion domain rules.
  • Deck semantics.
  • The once-per-run Fusion limit.
  • Tutorial step progression.
  • Battle action detection.
  • Highlight behaviour.
  • Tutorial battle setup.

The goal is to keep player-facing Help and tutorial wording reusable while allowing the Event and tutorial systems to retain ownership of their own gameplay logic.

Testing

Focused automated tests cover:

  • Dice Help opening and closing.
  • Help availability across staged Dice interaction.
  • Dice state preservation.
  • Card Fusion Help on both the Event intro and selection view.
  • Preservation of selected cards, deck state, RunState, Fusion allowance, delegated session state, and completion state.
  • Exclusion of Help from ordinary Chance Events.
  • Presence of all eight tutorial prompt categories.

Relevant commits:

  • 53bac208 — reusable Help dialog and Dice Help.
  • 1a5e8b60 — Card Fusion contextual Help.
  • afdc6ece — battle tutorial prompt content.

Focused tests and the broader :core:test suite were run successfully during implementation and integration.

Related Documentation