Files
sor/Client/context-files/scenes.md
T

15 KiB

Scenes and Client/Server Data Plan (Draft 1)

This file defines scene scope and network data flow for the first client/server planning pass.


1) Scene/Page/UI Map (Client-First Draft)

1.1 Boot + Session Scenes

  1. ClientLaunch
  2. HubConnection
  3. PatchAndVersionCheck
  4. AuthGateway

1.2 Auth Scenes

  1. Login
  2. Register
  3. OAuthStart
  4. OAuthCallback

1.3 Primary App Scenes

  1. MainMenu
  2. Bazaar
  3. Leaderboard
  4. Settings
  5. AccountManagement
  6. CollectionHub
  7. RankedPlay
  8. CustomPlay
  9. DeckEditor
  10. CardViewer
  11. Cosmetics

1.4 Global Persistent UI (All Scenes)

  • Settings button is present in every scene.
  • Report Bug button is present in every scene.
  • Placement and interaction pattern must remain consistent across scenes.

1.5 Per-Scene UI Blocks (Draft)

ClientLaunch

  • Splash/logo
  • Build/version text
  • Background init indicator

HubConnection

  • Connection status indicator (connecting/retrying/failed)
  • Retry button + diagnostics link (optional)

PatchAndVersionCheck

  • Version comparison summary
  • Patch progress bar
  • Release notes panel (optional)
  • Continue button when ready

AuthGateway

  • Account/session check spinner
  • Auth route chooser (Login/Register/OAuth)
  • Service status banner

Login

  • Username/email field
  • Password field
  • Remember device toggle
  • Submit + Forgot Password actions

Register

  • Email/username/password inputs
  • Terms/privacy acceptance controls
  • Submit action + validation messages

OAuthStart

  • Provider buttons
  • OAuth status text

OAuthCallback

  • Verifying auth state message
  • Success/failure redirect panel

MainMenu (Primary Interactive Hub)

  • Navigation nodes/buttons to:
    • Bazaar
    • Leaderboard
    • Settings
    • AccountManagement
    • CollectionHub
    • RankedPlay
    • CustomPlay
  • Profile summary widget
  • Notifications widget
  • Settings/logout actions
  • Input support:
    • mouse + touch (multi-touch required)
    • use standard camera gestures for movement
    • selection input: left click and middle mouse click on option nodes
    • input behavior baseline is global and must remain consistent across all scenes
  • Interactive background system:
    • dark aura visual treatment
    • rotatable 3D grid layer
    • grid topology state can shift between square and hex

AccountManagement

  • Identity panel:
    • username
    • email
    • profile image
  • Password change action:
    • Change Password button opens popup/modal
    • fields: new password, confirm password
    • actions: Submit and Cancel
  • Linked accounts panel:
    • Link Account action for available OAuth providers
    • show currently linked OAuth providers/status
  • Stats panel:
    • Origin points
    • Win
    • Loss
    • Forfeit
    • Draw
    • Cards owned
    • Cards played
  • Spending panel:
    • Total Spent value censored by default
    • toggle to uncensor and reveal:
      • money spent
      • origin points spent
    • Download Report action for full spending profile/metrics export
  • Legal links panel:
    • Terms of Service (TOS)
    • EULA
    • other required legal documents

CollectionHub

  • Tab nav (DeckEditor/CardViewer/Cosmetics)
  • Collection summary strip

DeckEditor

  • Deck list panel
  • Card search/filter panel
  • Deck composition panel
  • Validation/errors panel
  • Save/duplicate/delete actions

CardViewer

  • Search input
  • Filter/sort controls
  • Card grid/list
  • Card detail drawer/modal

Cosmetics

  • Cosmetic category selector (back/trim/art/model)
  • Preview pane
  • Owned/locked state indicators
  • Equip/apply controls

2) Shared Transport Notes

  • Connection model:
    • Persistent real-time session to relay/hub for presence + notifications.
    • HTTPS API calls for auth/account/content operations.
  • Auth model:
    • Short-lived access token + refresh token.
    • Device/session id tracked by server.
  • Data model:
    • Every payload includes requestId and serverTimeUtc.
    • Every list endpoint supports paging (page, pageSize) and sorting.

3) Scene Details

3.1 ClientLaunch

Client

  • Boot local config, device fingerprint, cached token state.
  • Initialize telemetry/session id.
  • Transition to HubConnection.

Server

  • None yet (local-only scene).

Data Exchange

Client -> Server:

  • none

Server -> Client:

  • none

3.2 HubConnection

Client

  • Open relay/hub socket.
  • Send initial hello with client build + platform metadata.
  • Wait for connection acceptance and service availability.

Server

  • Validate protocol version compatibility.
  • Return environment capabilities and endpoint map.
  • Return maintenance/degraded status if active.

Data Exchange

Client -> Server (HubHello):

  • requestId
  • clientVersion
  • contentVersion (installed asset/content hash)
  • platform (windows, linux, etc.)
  • locale
  • deviceId
  • sessionId

Server -> Client (HubWelcome):

  • requestId
  • connectionId
  • minSupportedClientVersion
  • latestClientVersion
  • latestContentVersion
  • serviceStatus (ok, degraded, maintenance)
  • apiBaseUrl
  • cdnBaseUrl
  • authProvidersEnabled (google, steam, apple, microsoft)
  • motd (optional)

3.3 PatchAndVersionCheck

Client

  • Compare installed version/content against server-required values.
  • If update needed: show patch status UI, download/apply, then reconnect.
  • If up-to-date: continue to AuthGateway.

Server

  • Provide update manifest and rollout policy.
  • Enforce hard-block if client below minimum supported version.

Data Exchange

Client -> Server (VersionStatusRequest):

  • requestId
  • clientVersion
  • contentVersion
  • platform

Server -> Client (VersionStatusResponse):

  • requestId
  • isClientSupported
  • requiresClientUpdate
  • requiresContentUpdate
  • minimumAllowedVersion
  • targetClientVersion
  • targetContentVersion
  • updateManifestUrl
  • updateNotes (optional)
  • blockReason (if unsupported)

3.4 AuthGateway

Client

  • Decide entry path:
    • Existing session refresh.
    • Username/password login.
    • Register new account.
    • OAuth provider login.
  • Render enabled options based on server capabilities.

Server

  • Validate refresh tokens and return session state.
  • Provide auth policy (password rules, age gates, region restrictions if needed).

Data Exchange

Client -> Server (SessionProbe):

  • requestId
  • refreshToken (optional)
  • deviceId

Server -> Client (SessionProbeResult):

  • requestId
  • isAuthenticated
  • accountId (if authenticated)
  • displayName (if authenticated)
  • authMethodsAvailable
  • passwordPolicy

3.5 Login / Register

Client

  • Login:
    • Submit account identifier + password.
  • Register:
    • Submit account fields and required agreements.
  • On success transition to MainMenu.

Server

  • Login:
    • Validate credentials, enforce lockout and MFA if enabled.
  • Register:
    • Create account, validate uniqueness, persist agreements.
  • Return auth tokens + account summary.

Data Exchange

Client -> Server (LoginRequest):

  • requestId
  • emailOrUsername
  • password
  • deviceId

Server -> Client (LoginResponse):

  • requestId
  • success
  • accessToken
  • refreshToken
  • expiresAtUtc
  • accountSummary
  • errorCode (if failed)

Client -> Server (RegisterRequest):

  • requestId
  • email
  • username
  • password
  • countryCode
  • dob (if required by policy)
  • acceptedPolicies (policy ids + timestamps)

Server -> Client (RegisterResponse):

  • requestId
  • success
  • accessToken (optional; if auto-login enabled)
  • refreshToken (optional)
  • accountSummary (optional)
  • requiresEmailVerification
  • errorCode (if failed)

3.6 OAuthStart / OAuthCallback

Client

  • Start OAuth flow with selected provider.
  • Open provider auth URL.
  • Receive callback code/state and exchange with backend.
  • On success transition to MainMenu.

Server

  • Generate signed OAuth start URL and anti-forgery state.
  • Exchange auth code with provider and bind/create game account.
  • Return tokens and account summary.

Data Exchange

Client -> Server (OAuthStartRequest):

  • requestId
  • provider (google, steam, apple, microsoft)
  • returnUri
  • deviceId

Server -> Client (OAuthStartResponse):

  • requestId
  • authorizationUrl
  • state
  • codeVerifier (if PKCE client-managed)

Client -> Server (OAuthExchangeRequest):

  • requestId
  • provider
  • authorizationCode
  • state
  • codeVerifier (if PKCE)

Server -> Client (OAuthExchangeResponse):

  • requestId
  • success
  • accessToken
  • refreshToken
  • expiresAtUtc
  • accountSummary
  • errorCode (if failed)

3.7 MainMenu

Client

  • Display entry points:
    • Ranked Play
    • Custom Play
    • Collection
    • Bazaar
    • Account Management
    • Settings
    • Leaderboard
    • Log Out
    • Admin (only if authorized)
  • Show account profile and key notifications.

Server

  • Return entitlement/role-based menu permissions.
  • Return badge counts (rewards, inbox, moderation flags, etc.).
  • Return feature flags for visible modules.

Data Exchange

Client -> Server (MainMenuBootstrapRequest):

  • requestId
  • accountId
  • clientVersion

Server -> Client (MainMenuBootstrapResponse):

  • requestId
  • profileSummary
  • roles (player, admin, etc.)
  • featureFlags
  • menuPermissions
  • notificationCounts
  • rankedSummary (current rank, season id)

3.8 AccountManagement

Client

  • Display identity/profile details and account-linked providers.
  • Support password update via modal workflow.
  • Display account stats and spending summary with default-censored totals.
  • Allow uncensor toggle for spending values.
  • Provide export action for full spending profile report.
  • Show legal document links (TOS, EULA, related policies).

Server

  • Return account profile, linked OAuth providers, and player/account stats.
  • Process password change requests.
  • Return spending summary fields and detailed spending report export.
  • Return legal document metadata and URLs.

Data Exchange

Client -> Server (AccountOverviewRequest):

  • requestId
  • accountId

Server -> Client (AccountOverviewResponse):

  • requestId
  • username
  • email
  • profileImageUrl
  • linkedProviders
  • stats:
    • originPoints
    • wins
    • losses
    • forfeits
    • draws
    • cardsOwned
    • cardsPlayed
  • spendingSummary:
    • moneySpent
    • originPointsSpent
    • censoredByDefault (true)
  • legalDocuments (name + url)

Client -> Server (ChangePasswordRequest):

  • requestId
  • currentPassword (if policy requires)
  • newPassword
  • confirmPassword

Server -> Client (ChangePasswordResponse):

  • requestId
  • success
  • errorCode (if failed)

Client -> Server (LinkOAuthRequest):

  • requestId
  • provider

Server -> Client (LinkOAuthResponse):

  • requestId
  • success
  • linkedProviders
  • errorCode (if failed)

Client -> Server (SpendingReportRequest):

  • requestId
  • format (csv, json, pdf)

Server -> Client (SpendingReportResponse):

  • requestId
  • success
  • downloadUrl
  • expiresAtUtc
  • errorCode (if failed)

3.9 Collection (Hub Scene)

Client

  • Load owned cards, deck list, cosmetics.
  • Provide tabs/sub-scenes:
    • DeckEditor
    • CardViewer
    • Cosmetics

Server

  • Return collection inventory + ownership states.
  • Return deck metadata and validation rules.
  • Return unlocked/purchasable card backs, trims, and art/model variants.

Data Exchange

Client -> Server (CollectionBootstrapRequest):

  • requestId
  • accountId
  • includeInventory
  • includeDecks
  • includeCosmetics

Server -> Client (CollectionBootstrapResponse):

  • requestId
  • cardInventory (card definition id + ownership/quantity + variants owned)
  • deckSummaries
  • cosmeticInventory
  • collectionStats
  • rulesVersion

3.10 DeckEditor

Client

  • Build/edit decks with full filtering and sorting.
  • Validate deck locally with server rule mirror.
  • Save, duplicate, rename, delete deck.

Server

  • Validate deck against current legal format/rules.
  • Persist deck revisions and return canonical saved state.

Data Exchange

Client -> Server (DeckValidateRequest):

  • requestId
  • deckDraft
  • formatId

Server -> Client (DeckValidateResponse):

  • requestId
  • isValid
  • errors
  • warnings

Client -> Server (DeckSaveRequest):

  • requestId
  • deckId (optional for new deck)
  • deckName
  • deckCards (card instance ids or definition ids + quantity model)
  • formatId

Server -> Client (DeckSaveResponse):

  • requestId
  • success
  • deckId
  • deckRevision
  • isValid
  • errors (if invalid/rejected)

3.11 CardViewer

Client

  • Browse card library and owned-only views.
  • Apply filters/sorts:
    • Type, affinity, cost, rarity, owned/unowned, set, text search.
  • View alternate art/model versions.

Server

  • Return searchable card metadata and ownership projection.
  • Return art/model variant manifests.

Data Exchange

Client -> Server (CardSearchRequest):

  • requestId
  • query
  • filters
  • sort
  • page
  • pageSize

Server -> Client (CardSearchResponse):

  • requestId
  • results
  • totalCount
  • facets

3.12 Cosmetics (Card Back / Trim / Variant Selection)

Client

  • Display available card back/trim options and card-specific art/model variants.
  • Preview and equip selections.

Server

  • Verify ownership and compatibility for selected cosmetic.
  • Persist equipped defaults and per-card overrides.

Data Exchange

Client -> Server (CosmeticEquipRequest):

  • requestId
  • scope (globalDeckDefault, cardDefinition, cardInstance)
  • targetId
  • cardBackId (optional)
  • trimId (optional)
  • artVariantId (optional)
  • modelVariantId (optional)

Server -> Client (CosmeticEquipResponse):

  • requestId
  • success
  • equippedState
  • errorCode (if failed)

3.13 Global Input Consistency Rules

  • Multi-touch support is required for touch-capable devices.
  • Core camera gestures and selection semantics are shared across all scenes.
  • Scene-specific controls may add actions, but must not override baseline navigation behavior.
  • Input remapping and accessibility options should apply globally, not per-scene.

4) Security and Validation Baseline

  • Server authoritative for:
    • Account identity/session state
    • Collection ownership
    • Deck legality
    • Cosmetic entitlement
  • Client authoritative for:
    • Local scene rendering
    • Non-authoritative UI filtering/sorting state
  • Every mutating request requires:
    • valid access token
    • account ownership check
    • anti-replay safeguards (requestId, timestamp window)

5) Next Draft Targets

  • Ranked Play scene breakdown and matchmaking payload contracts.
  • Custom Play lobby + room state contracts.
  • Bazaar transaction flow and inventory mutation rules.
  • Settings scene-level data model and interactions.
  • Admin scene contracts and role-gated operations.