kuilt-game/us.tractat.kuilt.game

Package-level declarations

Types

class DuplicateHostException(message: String = "another peer already declared host for this session — exactly one gameHost per session is required") : IllegalStateException

Thrown by gameHost when another peer on the same session has already declared itself host.

GamePresence

class GamePresence(seam: Seam, presenceScope: CoroutineScope, expectVirtualTime: Boolean = false)

Lobby presence over seam, backed by an EphemeralMap replicated by Quilter.

GameSession

class GameSession

A running game session: the consensus node plus any named application channels riding the same fabric.

IndexedAction

data class IndexedAction<out A>(val index: Long, val action: A, val dedupKey: DedupKey)

An application action that has been committed to the replicated log at index.

JoinTimeoutException

class JoinTimeoutException(message: String = "timed out waiting for the host to admit or reject this peer") : IllegalStateException

Thrown by gameJoin when the host never signals admission (neither admits nor closes the roster) within the gameJoin joinAdmissionTimeout bound.

ReturnPolicy

enum ReturnPolicy : Enum<ReturnPolicy>

Controls when gameHost returns the leader RaftNode to the caller.

RosterFullException

class RosterFullException(message: String = "the game roster is full — all seats were filled before this peer joined") : IllegalStateException

Thrown by gameJoin when the host signals that admission is closed and this peer is not in the final voter set.

SpectateTimeoutException

class SpectateTimeoutException(message: String = "timed out waiting for the host to admit or reject this spectator") : IllegalStateException

Thrown by gameSpectate when the host never signals spectator admission or rejection within the gameSpectate spectateAdmissionTimeout bound.

SpectatorsClosedException

class SpectatorsClosedException(message: String = "spectators are not allowed or the spectator cap has been reached") : IllegalStateException

Thrown by gameSpectate when the host's spectator gallery is closed — either because the host did not enable spectators (allowSpectators = false, the default) or because maxSpectators has already been reached.

SpeculativeGame

interface SpeculativeGame<S, A>

Consumer-owned description of a deterministic turn-based game, used by SpeculativeSequencer to apply, snapshot, and restore game state.

SpeculativeSequencer

class SpeculativeSequencer<S, A>(sequencer: TurnSequencer<A>, game: SpeculativeGame<S, A>, initialState: S, scope: CoroutineScope)

A wrapper over TurnSequencer that applies local actions optimistically before their committed index arrives, then rolls back and replays if the committed order differs from what was predicted.

TurnEvent

sealed interface TurnEvent<out A>

One instruction in a TurnSequencer's in-order TurnSequencer.events stream.

TurnSequencer

class TurnSequencer<A>(node: RaftNode, serializer: KSerializer<A>, format: BinaryFormat = DEFAULT_FORMAT)

A game-developer-friendly facade over RaftNode.

Functions

gameHost

suspend fun CoroutineScope.gameHost(seam: Seam, peerCount: Int, returnAt: ReturnPolicy = ReturnPolicy.FullMembership, allowSpectators: Boolean = false, maxSpectators: Int = 0, storage: RaftStorage = InMemoryRaftStorage(), raftConfig: RaftConfig = RaftConfig(), livenessConfig: HeartbeatConfig? = null, clock: () -> Instant = { Clock.System.now() }, hostDeclarationTimeout: Duration = DEFAULT_HOST_DECLARATION_TIMEOUT, identity: ClientIdentity = ClientIdentity.Auto): GameSession

Host a game session over seam: check for duplicate hosts, bootstrap a singleton-voter cluster, then admit each connecting peer as learner→voter until the cluster reaches the returnAt watermark, then returns a GameSession whose GameSession.node is the leader.

gameJoin

suspend fun CoroutineScope.gameJoin(seam: Seam, storage: RaftStorage = InMemoryRaftStorage(), raftConfig: RaftConfig = RaftConfig(), joinAdmissionTimeout: Duration = DEFAULT_JOIN_ADMISSION_TIMEOUT, identity: ClientIdentity = ClientIdentity.Auto): GameSession

Join a game session over seam hosted by exactly one gameHost. Starts as a non-voting learner and waits until the host admits this peer as a voter. Returns the local GameSession (its GameSession.node is the admitted follower) once admitted.

gameNode

fun CoroutineScope.gameNode(seam: Seam, voterIds: Set<NodeId>, storage: RaftStorage = InMemoryRaftStorage(), raftConfig: RaftConfig = RaftConfig(), identity: ClientIdentity = ClientIdentity.Auto): GameSession

Constructs a RaftNode over seam for a session whose full voter roster is already known to every peer (e.g. from matchmaking). Every peer builds the identical ClusterConfig.ofVoters and Raft's own election picks the leader — symmetric, no pre-Raft coordination step required.

gameSpectate

suspend fun CoroutineScope.gameSpectate(seam: Seam, storage: RaftStorage = InMemoryRaftStorage(), raftConfig: RaftConfig = RaftConfig(), spectateAdmissionTimeout: Duration = DEFAULT_SPECTATE_ADMISSION_TIMEOUT, identity: ClientIdentity = ClientIdentity.Auto): GameSession

Join a game session over seam as a permanent, non-voting spectator learner.