Games (GYP) Headless Functions

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.

Headless function setup

---

getRecreationalGamesMatchup(matchupId: String) -> AsyncStream<Result<LucraMatchup?, APIError>>

Retrieve the latest state for a recreational matchup as a live-updating stream.

Parameters

• matchupId: Lucra matchup identifier.

Returns

• AsyncStream<Result<LucraMatchup?, APIError>> — A stream that emits matchup updates or errors.

Usage

let stream = lucraClient.api.getRecreationalGamesMatchup(matchupId: "c32d...")

Task {
    for await result in stream {
        switch result {
        case .success(let matchup):
            if let matchup {
                print("Matchup status: \(matchup.status)")
            } else {
                print("Matchup not found")
            }
        case .failure(let error):
            print("Failed to load matchup: \(error)")
        }
    }
}

---

getRecreationalGamesMatchup(matchupId: String) async -> Result<LucraMatchup, GamesMatchupError>

Fetch a single snapshot of a recreational matchup.

Parameters

• matchupId: Lucra matchup identifier.

Returns

• Result<LucraMatchup, GamesMatchupError> — The matchup object on success, or a GamesMatchupError on failure.

Usage

let result = await lucraClient.api.getRecreationalGamesMatchup(matchupId: "c32d...")

switch result {
case .success(let matchup):
    print("Matchup status: \(matchup.status)")
case .failure(let error):
    print("Failed to retrieve matchup: \(error)")
}

---

createRecreationalGame(gameTypeId: String, atStake: RewardType, playStyle: PlayStyle) async -> Result<String, GamesMatchupError>

Create a new recreational game matchup.

Parameters

• gameTypeId: ID of the game to be played (e.g. "PICKLEBALL").

• atStake: Reward the players can win (cash reward or tenant reward).

• playStyle: Gameplay type (e.g. team vs team, free-for-all).

Returns

• Result<String, GamesMatchupError> — The created matchup ID on success, or a GamesMatchupError on failure.

Usage

let result = await lucraClient.api.createRecreationalGame(
    gameTypeId: "CORNHOLE_DOUBLES",
    atStake: .cashReward(10),
    playStyle: .teamVTeam
)

switch result {
case .success(let matchupId):
    print("Created matchup: \(matchupId)")
case .failure(let error):
    print("Create failed: \(error)")
}

---

acceptVersusRecreationalGame(matchupId: String, groupId: String) async -> Result<Bool, GamesMatchupError>

Accept a versus-style recreational matchup (team vs team or head-to-head).

Parameters

• matchupId: Matchup to join.

• groupId: Group/team the user wants to join.

Returns

• Result<Bool, GamesMatchupError> — true on success, or a GamesMatchupError on failure.

Usage

let result = await lucraClient.api.acceptVersusRecreationalGame(matchupId: "c32d...", groupId: "team-123")

switch result {
case .success:
    print("Joined contest!")
case .failure(let error):
    print("Unable to join: \(error)")
}

---

acceptFreeForAllRecreationalGame(matchupId: String) async -> Result<Bool, GamesMatchupError>

Accept a free-for-all recreational matchup where players join individually.

Parameters

• matchupId: Matchup to join.

Returns

• Result<Bool, GamesMatchupError> — true on success, or a GamesMatchupError on failure.

Usage

let result = await lucraClient.api.acceptFreeForAllRecreationalGame(matchupId: "ffa-987")

switch result {
case .success:
    print("Joined FFA")
case .failure(let error):
    print("Unable to join FFA: \(error)")
}

---

cancelRecreationalGame(matchupId: String) async -> Result<Bool, GamesMatchupError>

Cancel a recreational matchup created by the authenticated user.

Parameters

• matchupId: Matchup to cancel.

Returns

• Result<Bool, GamesMatchupError> — true on success, or a GamesMatchupError on failure.

Usage

let result = await lucraClient.api.cancelRecreationalGame(matchupId: "c32d...")

switch result {
case .success:
    print("Matchup canceled")
case .failure(let error):
    print("Cancel failed: \(error)")
}

---

Error Types

For specific error handling, please see [Headless Interactions](SDK/docs/1.2.9_headless_interactions.md) Error Handling section.

GamesMatchupError

• .user(UserStateError) — Wraps user state errors

• .location(LocationError) — Wraps location errors

• .customError(message: String) — Custom error message

• .unknown — Unknown error

UserStateError

• .notInitialized

• .unverified

• .notAllowed

• .insufficientFunds

• .demographicInformationMissing

LocationError

• .unauthorized

• .unableToDetermineLocation(error)

• .clError(clError)

---