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
deriveRnginserver/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
schemaVersionof the game: the Dart twin of the same-named TSGameRulesunit. - 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
isRejectedtype 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'smeta. -
LocalGameRules<
TState, TObs, TAction, TConfig> -
One
schemaVersionof a game, implemented a second time in Dart so the device can play it with no network: the twin of the TypeScriptGameRuleshooks inserver/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 minSeconds–maxSeconds.
- 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
Rnginserver/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, whosenullvariant is NoCause here so the type stays non-nullable and aswitchstays exhaustive. - TurnTimerBuilder
-
Headless widget that ticks toward a deadline, exposing the remaining
Durationto a builder callback every second. - Authentication boundary used when an app has not installed an adapter.
- 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:
enginein the server's game rules,externalby a hosted service,localby 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.
onlineis decided entirely by the server;localwas 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. Agameaction is rules-scoped and rejectable; alifecycleaction 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
RejectCodeinserver/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< run()) → Future<T> >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()inserver/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
buildContentconsume 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
avatarUrlinto 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_versionhas no entry in GameModule.versions. It was created by a newer app version and can't be loaded until the user updates.