Games (GYP) Headless Functions

The Lucra SDK exposes headless helpers for Games You Play so hosts can create, inspect, accept, and cancel recreational contests without launching Lucra UI. All functions live on LucraClient and report back through sealed result types—handle each branch to cover both success and failure paths.

Headless function setup

---

Fetch a recreational matchup

getMatchup(matchupId, onResult)

Retrieve the latest state for a recreational matchup.

• Parameters

  • matchupId: Lucra matchup identifier.

  • onResult: callback receiving a GetMatchupResult.

• Results

  • GetMatchupResult.Success — supplies matchup (the full Lucra matchup payload).

  • GetMatchupResult.Failure — wraps a GameInteractions.FailedRetrieveMatchup describing API vs. location errors.

• Usage

LucraClient().getMatchup(matchupId = "c32d...") { result ->
    when (result) {
        is GetMatchupResult.Success -> {
            val matchup = result.matchup
            Log.d("Lucra SDK", "Matchup status: ${matchup.status}")
        }
        is GetMatchupResult.Failure -> {
            Log.w("Lucra SDK", "Failed to load matchup: ${result.failure}")
        }
    }
}

---

Create a recreational matchup

createRecreationalGame(gameTypeId, atStake, playStyle, onResult)

Creates a new recreational matchup for the provided game type and wager type.

• Parameters

  • gameTypeId: e.g. "CORNHOLE_DOUBLES".

  • atStake: RewardType enum (cash, tenant reward, no reward, etc.).

  • playStyle: PlayStyle enum (team vs team, head to head, free for all).

  • onResult: callback receiving a CreateGamesMatchupResult.

• Results

  • CreateGamesMatchupResult.CreateGamesMatchupOutput — supplies the new matchup id and payload.

  • CreateGamesMatchupResult.Failure — wraps API or validation errors.

• Usage

LucraClient().createRecreationalGame(
    gameTypeId = "CORNHOLE_DOUBLES",
    atStake = RewardType.CASH_REWARD,
    playStyle = PlayStyle.TEAM_V_TEAM
) { result ->
    when (result) {
        is CreateGamesMatchupResult.CreateGamesMatchupOutput -> {
            Log.d("Lucra SDK", "Created matchup ${result.matchupId}")
        }
        is CreateGamesMatchupResult.Failure -> {
            Log.e("Lucra SDK", "Create failed: ${result.failure}")
        }
    }
}

---

Accept a versus recreational matchup

acceptVersusRecreationalGame(matchupId, teamId, onResult)

Accepts a versus-style (team v team / head to head) matchup.

• Parameters

  • matchupId: matchup to join.

  • teamId: Lucra team id the user should join.

  • onResult: callback receiving an AcceptRecreationalGameResult.

• Results

  • AcceptRecreationalGameResult.Success — join succeeded; payload includes refreshed matchup data.

  • AcceptRecreationalGameResult.Failure — contains LocationError or APIError converted from the underlying GetMatchupResult/accept call.

• Usage

LucraClient().acceptVersusRecreationalGame(
    matchupId = "c32d...",
    teamId = "team-123"
) { result ->
    when (result) {
        is AcceptRecreationalGameResult.Success -> {
            Log.d("Lucra SDK", "Joined contest! ${result.matchupId}")
        }
        is AcceptRecreationalGameResult.Failure -> {
            Log.w("Lucra SDK", "Unable to join: ${result.failure}")
        }
    }
}

Behind the scenes the SDK first calls getMatchup to ensure the contest is valid and to obtain the latest Lucra matchup object required by the acceptance API.

---

Join a free-for-all recreational matchup

acceptFreeForAllRecreationalGame(matchupId, onResult)

Accepts a free-for-all (FFA) matchup where players join individually.

• Parameters

  • matchupId: matchup to join.

  • onResult: callback receiving an AcceptRecreationalGameResult.

• Results

  • AcceptRecreationalGameResult.Success

  • AcceptRecreationalGameResult.Failure

• Usage

LucraClient().acceptFreeForAllRecreationalGame(matchupId = "ffa-987") { result ->
    when (result) {
        is AcceptRecreationalGameResult.Success -> {
            Log.d("Lucra SDK", "Joined FFA: ${result.matchupId}")
        }
        is AcceptRecreationalGameResult.Failure -> {
            Log.w("Lucra SDK", "Unable to join FFA: ${result.failure}")
        }
    }
}

---

Cancel a recreational matchup

cancelRecreationalGame(matchupId, onResult)

Cancels a recreational matchup created by the authenticated user.

• Parameters

  • matchupId: matchup to cancel.

  • onResult: callback receiving a CancelGamesMatchupResult.

• Results

  • CancelGamesMatchupResult.Success

  • CancelGamesMatchupResult.Failure

• Usage

LucraClient().cancelRecreationalGame(matchupId = "c32d...") { result ->
    when (result) {
        is CancelGamesMatchupResult.Success -> {
            Log.d("Lucra SDK", "Matchup canceled")
        }
        is CancelGamesMatchupResult.Failure -> {
            Log.e("Lucra SDK", "Cancel failed: ${result.failure}")
        }
    }
}

---

Result type reference

Result Type	Success Payload	Failure Payload
GetMatchupResult	matchup (Lucra matchup)	GameInteractions.FailedRetrieveMatchup
CreateGamesMatchupResult	matchupId, lucraMatchup	CreateGamesMatchupResult.Failure
AcceptRecreationalGameResult	matchupId, lucraMatchup	LocationError / APIError
CancelGamesMatchupResult	matchupId	CancelGamesMatchupResult.Failure

Handle each sealed interface exhaustively to ensure you capture both success and error scenarios.