eigen_flutter library

Reusable Flutter integration for EigenInteractive game applications.

A game app depends on this package and implements a GameModule. It can install EigenFlutterScope beneath its own application root or use the opinionated eigen_shell package for the complete first-party product.

import 'package:eigen_flutter/eigen_flutter.dart';

EigenFlutterScope(
  module: const MyGameModule(),
  config: appConfig,
  child: const MaterialApp(home: MyHome()),
);

This is the supported game-facing import. It exposes the embeddable scope, configuration, game contract, wire vocabulary, and shared game UI without taking ownership of routing or a root application widget.

Start with the EigenInteractive quickstart and use the task guides for end-to-end TypeScript and Dart examples.

Classes

AccessCapability
AccessSnapshot
AccountReplica
One account's replica: what its screens read, and what its writers write (decision 0013).
AccountRepository
The signed-in account: its sync, its profile, and its lifecycle.
AccountSync
ActiveEntitlement
AppConfig
Whitelabel configuration for one game app built on the engine.
AppTheme
Minimal app theme configuration using Material 3.
AuthGateway
Authentication required by the Flutter presentation package.
AuthStateChange
A single emission of the auth state stream: what happened, and who the session user is now (null when signed out).
AuthUser
The signed-in user as the app sees it: the backend-agnostic twin of the auth provider's session user.
AvatarStorageService
Uploads the signed-in user's avatar.
BearerTokenInterceptor
Adds a bearer token supplied by an identity adapter to engine requests.
Bot
BotRunner
Where a bot brain runs: the port the Flutter adapter implements.
BotSeatableArgs
A candidate bot seating, passed to GameRules.botSeatable.
BotTag
Compact pill that labels a participant as a bot.
Branding
User-facing identity for the app shell.
BudgetConfig
Each player has a personal time bank that drains while they act (Fischer increment).
CheckoutLauncher
Opens a provider's checkout page.
CommandAccepted
CommerceCatalog
CommerceDeliveries
The purchase-delivery outbox, in the replica database.
CommerceOffer
CommerceProduct
CommercePurchaseClaim
Provider evidence for one registered logical offer.
CommerceRepository
Provider-neutral commerce access to the Eigen Worker.
CommerceService
Joins this build's storefronts to the authoritative Worker projection.
CommercialLimitAccess
ContentGrant
Created
DeviceRepository
Push registrations for the authenticated user's installations.
EigenClient
A configured EigenInteractive backend.
EigenFlutterScope
Installs Eigen's reusable Flutter state beneath an application-owned root.
EigenRng
The engine's deterministic random stream, ported bit for bit from the kernel's deriveRng in server/packages/kernel/src/rng.ts.
EngineConfig
Runtime configuration the framework needs to talk to its backends.
Envelope<TState>
The result of advancing a local game by one transition: the twin of the TypeScript Envelope, and the return of every state hook.
Frame
Friend
FriendRequest
GameCause<TAction>
A rules-scoped move by playerIndex: the TypeScript {kind:"game"} variant.
GameContentContext
Everything GameRules.buildContent needs, bundled into one object.
GameCreationSpec
Declarative description of what is valid when creating a game of this type.
GameFrame
A single observation snapshot of an active or finished game.
GameModule
Contract every game implementor provides.
GamePlayer
Unified game-level player concept.
GameRepository
Everything a client does to a game: discovery, the waiting room, moves, and the live frame feed.
GameRules<TObs, TAction, TConfig>
The client-side surface of one schemaVersion of the game: the Dart twin of the same-named TS GameRules unit.
GameSession
One game's live session, as the client holds it: the newest snapshot the server stated, plus the frame being rendered and the one it replaced.
GameSocket
Opens a game's socket and keeps it open for the screen's lifetime.
GameSummary
GameTransition
The step from one frame to the next: the unit a game animates.
GuestTag
Compact pill that labels a player as an anonymous guest.
HostedCheckoutStorefront
Shared shape of a storefront whose purchase happens on a provider's page.
HostedStorefront
A storefront whose purchase UI is a provider-hosted page.
HttpDate
Parses the RFC 1123 dates HTTP uses.
InlineBotRunner
A BotRunner that runs the brain on the caller's isolate.
LifecycleAction
The engine-constructed payload of a lifecycle action, recorded verbatim in the transition log: the twin of the TypeScript LifecycleAction.
LifecycleAutoForfeit
The engine-driven forfeit (an account purge), which a local game only ever sees when replaying a record the server resolved.
LifecycleCause<TAction>
An engine-scoped lifecycle action: the TypeScript {kind:"lifecycle"} variant.
LifecycleForfeit
A voluntary resign by playerIndex.
LifecycleTimeout
The clock ran out for every seat in the pending set.
LocalActionIntent
A move by seat, decided against expectedVersion.
LocalBotActionArgs<TObs, TConfig>
A seated bot's turn to move: the twin of the TypeScript BotActionArgs.
LocalBotJob
One bot's turn to think, as the engine hands it to a BotRunner.
LocalCommitPlan
The transition to apply: the twin of the kernel's CommitPlan.
LocalCommitResult
What one commit produced: either a plan to apply, or a refusal. Sealed so a caller must handle both, where the TypeScript twin needs an isRejected type guard.
LocalEffect
Something the engine should do after applying a plan: the twin of the kernel's Effect, holding only the one a local game has.
LocalForfeitIntent
Resign seat. Unconditional: no pending, version or deadline guard.
LocalGame
A local game as the engine holds it in memory: everything but the log.
LocalGameEngine
The device's Durable Object: one serialized command queue over one local game (decision 0012).
LocalGameMeta
The game's standing configuration: the twin of the kernel's GameRow, and the local record's meta.
LocalGameRules<TState, TObs, TAction, TConfig>
One schemaVersion of a game, implemented a second time in Dart so the device can play it with no network: the twin of the TypeScript GameRules hooks in server/packages/rules/src/contract.ts.
LocalGameStorage
Where the games this device decides live: rows in the replica, the same tables every other game is in (decision 0013).
LocalGameSync
Carries a device's local games to the server, where they become ordinary games (decision 0012).
LocalGameTransition
One committed transition of a local game: what the Durable Object stores per version, minus the engine's clocks.
LocalIntent
What the device asks the kernel to do: the twin of the kernel's Intent, restricted to the three a local game can raise.
LocalObservationFrame
One seat's projected frame: the twin of the kernel's ObservationFrame. No raw state escapes the kernel except through this projection.
LocalRecord
LocalRejected
An intent the kernel refused: the twin of the kernel's Rejected. A value, not a throw, because a rejection is part of the normal protocol.
LocalRejection
LocalSeat
One seat of the roster: the twin of the kernel's Seat.
LocalStartIntent
Begin the game at version 0 with a freshly minted base seed.
LocalStateRow
The latest committed transition: the twin of the kernel's StateRow, without the clocks an untimed game has no use for.
LocalSyncReport
What one LocalGameSync.syncAll pass did.
LocalTransition
LocalTransitionAction
The transition log entry for one commit: the twin of the kernel's TransitionAction, and the exact JSON shape the import route replays.
LocalTransitionRow
LocalTransitions
LocalTransitionsApplied
LocalWakeBot
A bot seat became pending and its brain should run.
MySeat
A sealed union of the two ways the current user relates to a game.
NoCause<TAction>
The opening frame, which no action produced: the TypeScript null.
ObservationSlice<TObs>
One participant's view of the state, produced by LocalGameRules.computeObservation: the twin of the TypeScript ObservationSlice.
Outcome
PerActionConfig
Each turn gets a fresh fixed window of minSecondsmaxSeconds.
Player
PlayerAvatar
Circular avatar for a player, with customizable size.
PlayerBatchLoader
Coalesces single-id player lookups into one batch request per frame.
PlayerLimits
The seats one config may be played with, returned by GameRules.playerLimits.
PlayerRepository
Fetches public player identities, humans and bots alike.
PlayersContext
Player identity data passed to GameRules.buildContent.
PlayerTimerBuilder
Headless widget that computes a single player's remaining budget time, exposing it to a builder callback every second.
Profile
PublicReplica
The replica's public reference data: identities, the bot catalog, and display ratings. Shared by every account on the device, because none of it belongs to one (decision 0013).
PurchaseDeliveryStore
Durable outbox for completed provider deliveries awaiting full processing.
PurchaseGateway
A storefront whose purchase UI is an on-device billing SDK.
PurchaseUpdate
Evidence emitted by a platform billing adapter.
Rating
RatingDelta
RatingIdentity
RatingPoolArgs
The chosen game settings, passed to GameRules.ratingPool.
RatingRepository
Another player's ratings.
RazorpayHostedStorefront
Razorpay hosted checkout behind the HostedStorefront port.
ReplicaConfig
What the device replica keeps of what it has synced (decision 0013).
ReplicaDatabase
The device's database: a replica of the server's read model for every account signed in here, plus the games this device decides (decision 0013).
Rng
Deterministic random source for one transition: the twin of the TypeScript Rng in server/packages/rules/src/contract.ts.
Seat
Seated
The current user holds seat index in the game (a participant).
ServerClock
Server time, as best the client can tell.
Session
SocialRepository
The friend graph's writes, user search, and friends' open games.
SoloStarted
Storefront
One way a player can buy, in this build, on this platform.
StoreProduct
A localized storefront product returned by a platform billing SDK.
StripeHostedStorefront
Stripe hosted Checkout behind the HostedStorefront port.
SyncPass
Brings one account's replica up to date with the server (decision 0013).
SyncReport
What one SyncPass.run did.
TimingContext
Timing data passed to GameRules.buildContent for every active game.
TimingModeConfig
Configuration for one timing option shown in the new-game dialog.
TransitionAction
TransitionCause<TAction>
What produced the state being projected: the twin of the TypeScript TransitionCause, whose null variant is NoCause here so the type stays non-nullable and a switch stays exhaustive.
TurnTimerBuilder
Headless widget that ticks toward a deadline, exposing the remaining Duration to a builder callback every second.
UnavailableAuthGateway
Authentication boundary used when an app has not installed an adapter.
UnavailablePurchaseGateway
Default for applications that do not opt into commerce.
UntimedConfig
No time limit. Players act at any pace. No additional controls rendered.
Viewer
The current user has no seat: a non-participant viewing a replay.

Enums

AccessCapabilityAccessEnum
AccessCapabilityKindEnum
ActionSubmitResult
How a submitted action resolved, reported to the game through the future returned by GameContentContext.onAction.
AuthEvent
Auth lifecycle events surfaced by the authentication state stream.
AuthSignInResult
How a sign-in the player started ended, when it did not fail.
AuthUpgradeResult
Result of trying to turn a guest session into a Google-backed account.
BotType
How this bot's moves are produced: engine in the server's game rules, external by a hosted service, local by a brain shipped in the client.
CommerceOfferKindEnum
CommercialLimitAccessMetricEnum
CommercialPeriodKind
The commercial accounting window. Calendar months always use UTC.
DevicePlatform
Push-delivery platforms understood by the engine.
ErrorCode
A stable machine code identifying why a request failed.
FrameTypeEnum
FriendRequestDirectionEnum
FriendRequestResultStatusEnum
GameAccess
GameOrigin
Where a game is played. online is decided entirely by the server; local was played on the device against on-device bots and imported afterwards.
GameStatus
LifecycleType
The trigger of a lifecycle action: the twin of the TypeScript LifecycleType.
LocalActionKind
Which species a logged transition is: the twin of the TypeScript ActionKind. A game action is rules-scoped and rejectable; a lifecycle action is engine-scoped and always resolves.
LocalActionType
The performer recorded on a logged transition: the twin of the TypeScript ActionType.
LocalActor
Who submitted a move. A local game logs a brain's move as bot, which is exactly what the import route replays it as.
LocalRejectCode
Why the local kernel refused an intent: the twin of the kernel's RejectCode in server/packages/kernel/src/errors.ts, minus the codes an untimed single-device game cannot produce.
LocalSyncOutcome
How one game's synchronization ended.
LocalTransitionKindEnum
OutcomeResultEnum
PurchaseUpdateState
The normalized state of one platform purchase update.
SeatTypeEnum
TransitionActionKindEnum
TransitionActionTypeEnum

Extensions

AuthStateChangePatterns on AuthStateChange
Adds pattern-matching-related methods to AuthStateChange.
AuthUserPatterns on AuthUser
Adds pattern-matching-related methods to AuthUser.
LocalRejectCodeError on LocalRejectCode
The wire error code each rejection surfaces as, so a local rejection and a server rejection reach the UI through one path.

Constants

defaultKeptReplays → const int
Ended online games whose replays the replica keeps, most recently opened first. A replay beyond it is fetched again when opened.
historyPageSize → const int
Number of games fetched per page of history older than a device holds.
hostedOfferQueryParameter → const String
The query parameter carrying the logical offer through a hosted checkout.
kMaxBudgetSeconds → const int
Infra hard maximum for budget (accumulated) clock (10 days).
kMaxTurnSeconds → const int
Infra hard maximum for per-action turn time (30 days).
kMinBudgetSeconds → const int
Infra hard minimum for budget (accumulated) clock (seconds).
kMinTurnSeconds → const int
Infra hard minimum for per-action turn time (seconds).
lobbyPageSize → const int
Number of games fetched per lobby page.
localSyncBatchSize → const int
The most transitions one append carries. The route accepts 200, and a long game syncs as several batches rather than one body the server would refuse.
profileGamesPageSize → const int
Number of games shown in the replay list on a player's profile.
razorpayProvider → const String
The provider key this storefront sells through.
stripeProvider → const String
The provider key this storefront sells through.

Properties

appConfigProvider AppConfigProvider
The active AppConfig.
final
commerceRepositoryProvider CommerceRepositoryProvider
Pure-Dart access to the Worker's commerce API.
final
commerceServiceProvider CommerceServiceProvider
Provider-neutral coordinator joining storefront updates to server verification.
final
currentGameModuleProvider CurrentGameModuleProvider
The active GameModule.
final
localPlayAvailableProvider LocalPlayAvailableProvider
Whether this build can play any game on the device at all: the local arm of the solo picker's availability.
final

Functions

botOf(BotRow row) Bot
A stored catalog row as the wire states it.
buildGameSocketUri({required String apiBaseUrl, required String gameId, required String ticket}) → Uri
Builds the browser-compatible authenticated socket URI.
causeOf(LocalTransitionAction? action, AnyLocalGameRules rules) TransitionCause<Object?>
What the projection is told produced a state, erased for the fan-out.
engineCall<T>(Future<T> run()) → Future<T>
Runs a generated API call, rethrowing a server-reported failure as the domain EngineException so nothing above the data layer handles Dio types.
engineData<T>(Future<Response<T>> run()) → Future<T>
Runs a generated API call and returns its decoded body, unwrapping the Response.
fanOutObservations(AnyLocalGameRules rules, {required Object? state, required List<int> pending, required int participantCount, required TransitionCause<Object?> cause, required bool isReplay, required Object? config}) → List<LocalObservationFrame>
Projects the new state into one slice per seat: the port of the kernel's fanOutObservations.
jsonEquals(Object? a, Object? b) → bool
Deep equality for two serializations of the same JSON value.
localCommit({required LocalGameMeta game, required LocalStateRow? state, required List<LocalSeat> roster, required LocalIntent intent, required AnyLocalGameRules rules}) LocalCommitResult
One state transition in, one plan or rejection out: the port of the kernel's commit() in server/packages/kernel/src/commit.ts, restricted to what a local game can need.
localGameFromRemote({required LocalRecord remote, required AnyLocalGameRules rules}) RebuiltLocalGame
Rebuilds a local game from the server's copy of it.
localSession(LocalGame game, {required LocalObservationFrame? frame}) Session
Builds the Session snapshot a local game presents, so a game screen, replay, history and buildContent consume a local game through the existing session path with no game code change (decision 0012).
newCheckoutOperationId() → String
Creates an identity for one hosted-checkout operation.
newGameCreationId() → String
Creates an identity for one game-creation operation.
newLocalGameId([Random? random]) → String
A fresh game id: a random UUID the device mints, which the server adopts verbatim when the game is imported.
newLocalSeed([Random? random]) → String
A fresh base RNG seed: 128 random bits, hex-encoded, exactly like the kernel's randomSeed().
playerOf(PlayerRow row) Player
A stored identity as the wire states it.
projectTransition(AnyLocalGameRules rules, {required LocalGameTransition transition, required Map<String, dynamic> config, required int participantCount}) → List<LocalObservationFrame>
Every seat's projection of transition: what the commit that produced it fanned out.
ratingOf(PlayerRatingRow row) Rating
A stored rating as the wire states it.
replicatedSessions({required AccountReplica replica, required GameRepository games, required String gameId, DateTime clock() = DateTime.now}) → Stream<GameSession>
One online game's live session, opened from the replica and written back to it (decision 0013).
resolveAvatarUrl(String? avatarUrl, String apiBaseUrl) → String?
Resolves a stored avatarUrl into something an image widget can load.
usableLocalBots(List<Bot> bots, GameModule module, {required Map<String, dynamic> config}) → List<Bot>
Bots this build can run on the device for a game using config.

Typedefs

AccessTokenProvider = Future<String?> Function()
Obtains the current access token for one engine request.
AnyLocalGameRules = LocalGameRules<Object?, Object?, Object?, Object?>
A LocalGameRules unit with its payload types erased: the twin of the TypeScript AnyGameRules, and what the kernel, the engine and the bot runner hold.
GameSocketEvent = Session
The socket carries exactly one message: the complete live truth about the game as this seat sees it.
GamesPage = ({List<GameSummary> games, String? nextCursor})
One page of a paged game list, plus the token that continues it.
HistoryState = ({bool hasOlder, DateTime? lastSyncedAt})
Where an account's history stands on this device.
LocalBotAction<TAction, TObs, TConfig> = FutureOr<TAction> Function(LocalBotActionArgs<TObs, TConfig>)
One local bot brain: the value type of LocalGameRules.botActions, and the twin of the TypeScript BotAction.
PendingDelivery = ({String deliveryId, String evidence, String offerKey, String providerReference})
One store purchase the device holds evidence for and has not yet delivered.
RebuiltLocalGame = ({List<LocalObservationFrame> frames, LocalGame game, List<LocalGameTransition> transitions})
A local game pulled back from the server, ready to be written in place of whatever this device held under its id.
StorefrontUpdate = ({Storefront storefront, PurchaseUpdate update})
One storefront update, carrying the storefront that produced it.
SyncLock = Future<void> Function(Future<void> body())
Keeps a pass's work from overlapping another pass over the same replica.
VerifiedPurchaseUpdate = ({AccessSnapshot? access, PurchaseUpdate update})
A purchase update after server verification when evidence was available.

Exceptions / Errors

AuthWindowBlockedException
The provider's sign-in could not open its window: in a browser, a pop-up blocker refused it.
EngineException
A failure the engine server itself reported: a non-2xx response carrying the { error, code? } envelope.
IllegalMoveException
A move the game's rules refuse: the twin of the TypeScript IllegalMoveError.
LocalBotFailed
A bot's turn failed: its brain threw, answered with a move the rules refused, or has no registry row on this device.
LocalGameBugError
A broken game or engine invariant: the twin of the TypeScript GameBugError.
PlayerNotFoundException
Thrown when a player lookup matches no row.
UnsupportedGameSchemaException
Thrown when a game's games.schema_version has no entry in GameModule.versions. It was created by a newer app version and can't be loaded until the user updates.