Encounter Resolution and Cross System Integration - UQcsse3200/2026-studio-3 GitHub Wiki

# Encounter Resolution and Cross-System Integration

## Contribution Overview

This page documents my Sprint 1 contribution to Team 2's Non-Battle Encounter feature.

My main responsibility was the **Encounter Resolution and Cross-System Integration** layer.

The goal of this work was to connect Team 2's Chance and Shop encounters with the systems owned by other teams while keeping the encounter logic independent from their internal implementations.

My work focused on:

- encounter lifecycle coordination
- player state integration
- card library integration
- player deck integration
- map completion integration
- Chance outcome resolution
- Shop transaction safety
- exactly-once encounter completion
- rollback and failure handling
- integration and lifecycle testing
- supporting integration documentation

The implementation was developed under:

- [Issue #68 — Encounter Resolution and Cross-System Integration](https://github.com/UQcsse3200/2026-studio-3/issues/68)
- [PR #69 — Integrate Encounter Resolution with Player, Card, Deck and Map](https://github.com/UQcsse3200/2026-studio-3/pull/69)

PR #69 was successfully merged into the Team 2 `Feature-2` branch.

---

# 1. Integration Architecture

A major part of my contribution was creating an integration boundary between Team 2's encounter code and systems owned by other feature teams.

Instead of allowing Chance and Shop logic to directly depend on external implementation classes, I introduced gateway and adapter boundaries.

The architecture follows this pattern:

```text
                        Map
                         |
                         v
              EncounterFlowController
                         |
             +-----------+-----------+
             |                       |
             v                       v
      Chance Encounter          Shop Encounter
             |                       |
             +-----------+-----------+
                         |
                         v
                Integration Layer
                         |
          +--------------+--------------+
          |              |              |
          v              v              v
       Player          Cards           Deck
                         |
                         v
                        Map

This structure reduces coupling between Team 2 and other teams.

If another team changes its API, the integration adapter can be changed without rewriting the core Chance or Shop behaviour.

2. Encounter Lifecycle Controller

I implemented the encounter lifecycle coordination through the encounter flow controller.

The controller is responsible for tracking which encounter is currently active and controlling how an encounter finishes.

The lifecycle is:

Map Node Selected
       |
       v
Encounter Starts
       |
       v
Active Node Recorded
       |
       v
Encounter Resolves
       |
       v
Completion Callback
       |
       v
Map Completion
       |
       v
Active Encounter Cleared

A key design requirement was that only one encounter should be active at a time.

The controller therefore prevents a second encounter from incorrectly replacing an active encounter.

3. Exactly-Once Completion

One of the main risks I addressed was repeated encounter completion.

Without protection, the same callback could potentially cause:

duplicate rewards
repeated purchases
duplicate map-node completion
repeated screen transitions
incorrect game progression

I implemented protection so that a completion callback is accepted only when it matches the currently active encounter.

After a valid completion:

the encounter is resolved
the map is notified
the active encounter is cleared

Any later stale or duplicate callback is ignored.

Completion Callback
        |
        v
Does node match active encounter?
        |
      +---+
      |   |
     No  Yes
      |   |
      v   v
   Ignore Complete
             |
             v
       Clear Active State

This provides exactly-once completion behaviour for encounter resolution.

4. Player State Integration

Chance and Shop encounters both need to interact with player state.

I created an adapter boundary so encounter code only accesses the player information it actually requires.

The integration supports operations involving:

current health
maximum health
current currency
health updates
currency updates

This avoids coupling encounter logic directly to the internal Player implementation.

The encounter system therefore depends on a small player-state interface rather than the entire Player subsystem.

5. Chance Outcome Resolution

I implemented the integration logic for applying Chance encounter outcomes to player state.

A Chance outcome can modify:

player health
player currency
or both at the same time

For example:

Chance Outcome
    |
    +---- Health +10
    |
    +---- Gold -20
    |
    v
Validate Outcome
    |
    v
Apply State Changes

A major concern was preventing partial state updates.

For example, the game should not end in this state:

Health updated successfully
Currency update failed

because the outcome was intended to be a single logical operation.

I therefore implemented rollback protection for multi-state Chance outcomes.

If one part of the update fails, the integration layer attempts to restore the previous state.

6. Chance Failure Handling

The Chance resolution logic also handles invalid or unsafe state changes.

The implementation includes protection for cases such as:

unaffordable negative currency outcomes
invalid state changes
rejected player-state updates
arithmetic overflow
failure during rollback

The objective is to fail safely rather than leave player state partially modified.

7. Shop Transaction Integration

Another major part of my contribution was coordinating Shop purchases across multiple systems.

A Shop purchase requires interaction with:

Card Library
Player Deck
Player currency

The transaction flow is:

Purchase Requested
        |
        v
Does Card Exist?
     |       |
    No      Yes
     |       |
   Reject    v
         Enough Gold?
          |       |
         No      Yes
          |       |
       Reject     v
               Add Card
                  |
                  v
            Deduct Gold
                  |
                  v
               Success

The Shop itself does not need to know the implementation details of the Card Library, Player or Deck systems.

Those dependencies are accessed through integration gateways.

8. Transaction-Safe Purchases

A major risk in Shop integration is a partially completed purchase.

For example:

Initial:
Gold = 100
Deck = []

Player buys a card for 40.

Step 1:
Card added to deck.

Step 2:
Currency update fails.

Without rollback, the player would receive a free card.

I implemented transaction rollback behaviour so that if payment fails after the card has already been added, the integration layer attempts to remove the card again.

Expected final state:

Gold = 100
Deck = []

This keeps the Shop transaction consistent.

9. Card Library Boundary

I introduced a card-catalogue integration boundary for validating cards used by the Shop.

The purpose of this adapter is to allow Team 2 to ask whether a card exists without depending on Card Library implementation details.

Conceptually, the boundary provides:

Shop
 |
 v
Card Catalogue Gateway
 |
 v
Card Library / Card Service

The Shop only needs to know whether the requested card ID represents a valid card.

Card loading, metadata storage and card implementation remain the responsibility of the Card system.

10. Deck Boundary

I also introduced a Deck integration boundary.

The Shop only requires a small subset of Deck behaviour:

add a purchased card
remove a card during rollback

Conceptually:

addCard(cardId)
removeCard(cardId)

This allows Shop transaction logic to remain separate from the internal implementation of the player's deck.

The adapter boundary was intentionally designed so that the final external Deck implementation could be connected without rewriting the Shop transaction logic.

11. Map Integration

Encounter completion must eventually be reported back to the Map system.

I implemented a Map completion adapter so the encounter system does not directly manipulate map internals.

The integration boundary is responsible for communicating:

which encounter node completed
whether the encounter completed successfully

Conceptually:

EncounterFlowController
          |
          v
 Map Completion Adapter
          |
          v
         Map

This also isolates node-ID differences between Team 2 and the Map system from the core encounter logic.

12. Cross-Team Responsibility Boundaries

The integration layer was designed to preserve clear ownership between feature teams.

Team 2 — Encounter Integration

My integration work is responsible for:

encounter lifecycle management
Chance state application
Shop transaction coordination
exactly-once completion
adapter / gateway boundaries
rollback behaviour
integration failure handling

Player System

The Player system remains responsible for:

health storage
maximum health
currency
player-owned components

Card System

The Card system remains responsible for:

card definitions
card lookup
card metadata
card validation

Deck System

The Deck system remains responsible for:

player-owned cards
adding cards
removing cards
deck state

Map System

The Map system remains responsible for:

node identity
graph progression
node completion state
map behaviour after encounter completion

UI / Game Flow

The UI/Game Flow system remains responsible for:

encounter screen presentation
overlays
transitions between screens
returning control to the correct game screen

This separation prevents Team 2 from taking ownership of systems belonging to other teams.

13. Integration Testing

I added integration-focused tests around the areas most likely to fail when several systems interact.

The tests cover both successful behaviour and failure paths.

Encounter Lifecycle Tests

The lifecycle tests verify that:

an encounter can start
only one encounter is active
a valid encounter completes successfully
completion happens only once
duplicate callbacks are ignored
stale callbacks are ignored

Chance Resolution Tests

The Chance tests verify:

health-only outcomes
currency-only outcomes
combined health and currency outcomes
insufficient currency rejection
rollback when an update fails
safe handling of invalid changes
arithmetic overflow protection
rollback failure reporting

Shop Integration Tests

The Shop tests verify:

valid purchases
card existence checks
insufficient currency rejection
successful card addition
successful currency deduction
no charge when a purchase fails
card rollback when currency update fails
rollback failure handling

Adapter Tests

The adapter-focused tests verify behaviour at the integration boundaries between encounters and:

Player
Card Library
Deck
Map

14. Verification Evidence

The implementation and review evidence is available through PR #69.

Main implementation PR

PR #69 — Integrate Encounter Resolution with Player, Card, Deck and Map

Final PR head before merge:

16909c5

PR #69 was merged into Feature-2 with merge commit:

bf129e4

Automated verification performed for the implementation included:

Java formatting verification
Gradle unit tests
encounter integration tests
lifecycle tests
rollback tests
failure-path tests

The Gradle test execution completed successfully.

15. Documentation

As part of the integration work, supporting documentation was also prepared for:

architecture
integration boundaries
encounter lifecycle
expected API behaviour
integration risks
manual test scenarios
final demonstration flow

The main Sprint integration route is:

Map → Chance → Shop → Map

This route is intended to demonstrate that encounter state, player state, Shop purchases and map progression continue to work together.

16. Key Engineering Decisions

Adapter-Based Integration

I used adapters and gateways instead of direct external dependencies.

This reduces cross-team coupling and makes API changes easier to isolate.

Atomic State Changes

Chance outcomes that modify multiple player values are treated as one logical operation.

This reduces partial-update bugs.

Transaction-Safe Shop Purchases

Shop purchases use rollback behaviour when one stage of a multi-system transaction fails.

Exactly-Once Completion

Encounter completion is protected against duplicate and stale callbacks.

Clear Ownership

The integration layer coordinates systems but does not take ownership of their internal implementation.

17. Problems Addressed

The integration work specifically addressed several risks that can occur when multiple feature teams are developing independently:

external APIs changing during development
different map node-ID representations
duplicate encounter callbacks
partial player-state updates
failed Shop transactions
invalid card IDs
deck update failures
player currency update failures
tightly coupled feature code

Using adapter boundaries allowed these risks to be handled without embedding external implementation details directly into Team 2's encounter code.

18. Result

My Sprint 1 contribution produced the integration layer required to connect Team 2's non-battle encounters with the wider game architecture.

The completed contribution provides:

a controlled encounter lifecycle
exactly-once encounter completion
safe Chance outcome resolution
transaction-safe Shop purchases
Player integration boundaries
Card integration boundaries
Deck integration boundaries
Map completion boundaries
rollback and failure handling
integration-focused automated tests
supporting technical documentation

This provides a foundation for Team 2's Chance and Shop encounters to integrate with the rest of the game while keeping cross-team dependencies isolated.