Split scene planning into global + per-scene context files
This commit is contained in:
@@ -0,0 +1,28 @@
|
||||
# Global Client Rules and Shared Contracts
|
||||
|
||||
## 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.
|
||||
|
||||
## Shared Transport Notes
|
||||
- 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.
|
||||
- Every payload includes `requestId` and `serverTimeUtc`.
|
||||
- List endpoints support paging (`page`, `pageSize`) and sorting.
|
||||
|
||||
## 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.
|
||||
|
||||
## Security and Validation Baseline
|
||||
- Server authoritative for identity/session, ownership, deck legality, and entitlements.
|
||||
- Client authoritative for rendering and non-authoritative UI state (filters/sorts).
|
||||
- Every mutating request requires:
|
||||
- valid access token
|
||||
- account ownership check
|
||||
- anti-replay safeguards (`requestId`, timestamp window)
|
||||
+31
-724
@@ -1,724 +1,31 @@
|
||||
# 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
|
||||
5. `Login`
|
||||
6. `Register`
|
||||
7. `OAuthStart`
|
||||
8. `OAuthCallback`
|
||||
|
||||
### 1.3 Primary App Scenes
|
||||
9. `MainMenu`
|
||||
10. `Bazaar`
|
||||
11. `Leaderboard`
|
||||
12. `Settings`
|
||||
13. `AccountManagement`
|
||||
14. `CollectionHub`
|
||||
15. `RankedPlay`
|
||||
16. `CustomPlay`
|
||||
17. `DeckEditor`
|
||||
18. `CardViewer`
|
||||
19. `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
|
||||
- Spending controls panel:
|
||||
- set monthly spending cap (money and/or origin points, per policy)
|
||||
- cap is lock-enforced once set and can be changed only once per month
|
||||
- clear warnings/explanations shown before setting or changing cap
|
||||
- show next eligible cap-change date/time
|
||||
- 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.
|
||||
- Enforce monthly spending cap locks and cap-change cooldown windows.
|
||||
- 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`)
|
||||
- `spendingCap`:
|
||||
- `capEnabled`
|
||||
- `moneyCapAmount` (optional)
|
||||
- `originPointsCapAmount` (optional)
|
||||
- `effectiveFromUtc`
|
||||
- `nextCapChangeAllowedAtUtc`
|
||||
- `lockReason` (when change is blocked)
|
||||
- `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 (`SpendingCapUpdateRequest`):
|
||||
- `requestId`
|
||||
- `moneyCapAmount` (optional)
|
||||
- `originPointsCapAmount` (optional)
|
||||
- `acceptWarning` (`true` required)
|
||||
|
||||
Server -> Client (`SpendingCapUpdateResponse`):
|
||||
- `requestId`
|
||||
- `success`
|
||||
- `spendingCap`
|
||||
- `nextCapChangeAllowedAtUtc`
|
||||
- `warningMessage`
|
||||
- `errorCode` (if failed, including cooldown violation)
|
||||
|
||||
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.
|
||||
# Scenes Index
|
||||
|
||||
This file is the top-level map. Scene details now live in `context-files/scenes/*.scene.md`.
|
||||
|
||||
## Boot + Session
|
||||
1. `ClientLaunch` → `scenes/client-launch.scene.md`
|
||||
2. `HubConnection` → `scenes/hub-connection.scene.md`
|
||||
3. `PatchAndVersionCheck` → `scenes/patch-and-version-check.scene.md`
|
||||
4. `AuthGateway` → `scenes/auth-gateway.scene.md`
|
||||
|
||||
## Auth
|
||||
5. `Login` → `scenes/login.scene.md`
|
||||
6. `Register` → `scenes/register.scene.md`
|
||||
7. `OAuthStart` → `scenes/oauth-start.scene.md`
|
||||
8. `OAuthCallback` → `scenes/oauth-callback.scene.md`
|
||||
|
||||
## Primary App
|
||||
9. `MainMenu` → `scenes/main-menu.scene.md`
|
||||
10. `Bazaar` → `scenes/bazaar.scene.md`
|
||||
11. `Leaderboard` → `scenes/leaderboard.scene.md`
|
||||
12. `Settings` → `scenes/settings.scene.md`
|
||||
13. `AccountManagement` → `scenes/account-management.scene.md`
|
||||
14. `CollectionHub` → `scenes/collection-hub.scene.md`
|
||||
15. `RankedPlay` → `scenes/ranked-play.scene.md`
|
||||
16. `CustomPlay` → `scenes/custom-play.scene.md`
|
||||
17. `DeckEditor` → `scenes/deck-editor.scene.md`
|
||||
18. `CardViewer` → `scenes/card-viewer.scene.md`
|
||||
19. `Cosmetics` → `scenes/cosmetics.scene.md`
|
||||
|
||||
## Global Rules
|
||||
- Shared/global client rules are in `global.md`.
|
||||
|
||||
@@ -0,0 +1,72 @@
|
||||
# AccountManagement Scene
|
||||
|
||||
## UI
|
||||
- Identity panel: username, email, profile image
|
||||
- Password change modal:
|
||||
- fields: `new password`, `confirm password`
|
||||
- actions: `Submit`, `Cancel`
|
||||
- Linked accounts panel:
|
||||
- `Link Account` for OAuth providers
|
||||
- linked provider status list
|
||||
- Stats panel:
|
||||
- Origin points, Win, Loss, Forfeit, Draw, Cards owned, Cards played
|
||||
- Spending panel:
|
||||
- `Total Spent` censored by default
|
||||
- uncensor toggle
|
||||
- money spent + origin points spent
|
||||
- `Download Report` for full spending profile
|
||||
- Spending controls panel:
|
||||
- set monthly spending cap (money and/or origin points)
|
||||
- cap lock-enforced once set
|
||||
- cap can be changed once per month
|
||||
- warnings required before set/change
|
||||
- show next eligible cap-change date/time
|
||||
- Legal links panel:
|
||||
- TOS, EULA, other required legal docs
|
||||
|
||||
## Client
|
||||
- Display profile, linked providers, stats, spending, legal docs.
|
||||
- Support password update workflow.
|
||||
- Support spending cap update workflow with warning acknowledgment.
|
||||
|
||||
## Server
|
||||
- Return account profile, linked providers, stats, spending summary.
|
||||
- Process password changes.
|
||||
- Enforce spending cap locks and cooldown windows.
|
||||
- Return spending report export URL.
|
||||
- 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`
|
||||
- `spendingCap`: `capEnabled`, `moneyCapAmount`, `originPointsCapAmount`, `effectiveFromUtc`, `nextCapChangeAllowedAtUtc`, `lockReason`
|
||||
- `legalDocuments` (name + url)
|
||||
|
||||
### Client -> Server (`ChangePasswordRequest`)
|
||||
- `requestId`, `currentPassword` (if policy requires), `newPassword`, `confirmPassword`
|
||||
|
||||
### Server -> Client (`ChangePasswordResponse`)
|
||||
- `requestId`, `success`, `errorCode`
|
||||
|
||||
### Client -> Server (`LinkOAuthRequest`)
|
||||
- `requestId`, `provider`
|
||||
|
||||
### Server -> Client (`LinkOAuthResponse`)
|
||||
- `requestId`, `success`, `linkedProviders`, `errorCode`
|
||||
|
||||
### Client -> Server (`SpendingCapUpdateRequest`)
|
||||
- `requestId`, `moneyCapAmount` (optional), `originPointsCapAmount` (optional), `acceptWarning`
|
||||
|
||||
### Server -> Client (`SpendingCapUpdateResponse`)
|
||||
- `requestId`, `success`, `spendingCap`, `nextCapChangeAllowedAtUtc`, `warningMessage`, `errorCode`
|
||||
|
||||
### Client -> Server (`SpendingReportRequest`)
|
||||
- `requestId`, `format` (`csv`, `json`, `pdf`)
|
||||
|
||||
### Server -> Client (`SpendingReportResponse`)
|
||||
- `requestId`, `success`, `downloadUrl`, `expiresAtUtc`, `errorCode`
|
||||
@@ -0,0 +1,22 @@
|
||||
# AuthGateway Scene
|
||||
|
||||
## UI
|
||||
- Account/session check spinner
|
||||
- Auth route chooser (Login/Register/OAuth)
|
||||
- Service status banner
|
||||
|
||||
## Client
|
||||
- Decide entry path: session refresh, login, register, OAuth.
|
||||
- Render enabled options based on server capabilities.
|
||||
|
||||
## Server
|
||||
- Validate refresh tokens and return session state.
|
||||
- Provide auth policy.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`SessionProbe`)
|
||||
- `requestId`, `refreshToken` (optional), `deviceId`
|
||||
|
||||
### Server -> Client (`SessionProbeResult`)
|
||||
- `requestId`, `isAuthenticated`, `accountId`, `displayName`
|
||||
- `authMethodsAvailable`, `passwordPolicy`
|
||||
@@ -0,0 +1,9 @@
|
||||
# Bazaar Scene
|
||||
|
||||
## Status
|
||||
Draft placeholder.
|
||||
|
||||
## Planned Scope
|
||||
- Define scene UI blocks
|
||||
- Define client interactions
|
||||
- Define server contract and payloads
|
||||
@@ -0,0 +1,20 @@
|
||||
# CardViewer Scene
|
||||
|
||||
## UI
|
||||
- Search input
|
||||
- Filter/sort controls
|
||||
- Card grid/list
|
||||
- Card detail drawer/modal
|
||||
|
||||
## Client
|
||||
- Browse card library and owned-only views.
|
||||
|
||||
## Server
|
||||
- Return searchable metadata, ownership projection, and variant manifests.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`CardSearchRequest`)
|
||||
- `requestId`, `query`, `filters`, `sort`, `page`, `pageSize`
|
||||
|
||||
### Server -> Client (`CardSearchResponse`)
|
||||
- `requestId`, `results`, `totalCount`, `facets`
|
||||
@@ -0,0 +1,14 @@
|
||||
# ClientLaunch Scene
|
||||
|
||||
## UI
|
||||
- Splash/logo
|
||||
- Build/version text
|
||||
- Background init indicator
|
||||
|
||||
## Client
|
||||
- Boot local config, device fingerprint, cached token state.
|
||||
- Initialize telemetry/session id.
|
||||
- Transition to `HubConnection`.
|
||||
|
||||
## Server
|
||||
- None (local-only scene).
|
||||
@@ -0,0 +1,18 @@
|
||||
# CollectionHub Scene
|
||||
|
||||
## UI
|
||||
- Tab nav (`DeckEditor`, `CardViewer`, `Cosmetics`)
|
||||
- Collection summary strip
|
||||
|
||||
## Client
|
||||
- Load owned cards, deck list, cosmetics.
|
||||
|
||||
## Server
|
||||
- Return collection inventory, deck metadata, validation rules, cosmetic inventory.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`CollectionBootstrapRequest`)
|
||||
- `requestId`, `accountId`, `includeInventory`, `includeDecks`, `includeCosmetics`
|
||||
|
||||
### Server -> Client (`CollectionBootstrapResponse`)
|
||||
- `requestId`, `cardInventory`, `deckSummaries`, `cosmeticInventory`, `collectionStats`, `rulesVersion`
|
||||
@@ -0,0 +1,20 @@
|
||||
# Cosmetics Scene
|
||||
|
||||
## UI
|
||||
- Cosmetic category selector (back/trim/art/model)
|
||||
- Preview pane
|
||||
- Owned/locked state indicators
|
||||
- Equip/apply controls
|
||||
|
||||
## Client
|
||||
- Display and preview cosmetic options; equip selections.
|
||||
|
||||
## Server
|
||||
- Verify ownership/compatibility and persist equipped defaults/overrides.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`CosmeticEquipRequest`)
|
||||
- `requestId`, `scope`, `targetId`, `cardBackId`, `trimId`, `artVariantId`, `modelVariantId`
|
||||
|
||||
### Server -> Client (`CosmeticEquipResponse`)
|
||||
- `requestId`, `success`, `equippedState`, `errorCode`
|
||||
@@ -0,0 +1,9 @@
|
||||
# Custom play Scene
|
||||
|
||||
## Status
|
||||
Draft placeholder.
|
||||
|
||||
## Planned Scope
|
||||
- Define scene UI blocks
|
||||
- Define client interactions
|
||||
- Define server contract and payloads
|
||||
@@ -0,0 +1,27 @@
|
||||
# DeckEditor Scene
|
||||
|
||||
## UI
|
||||
- Deck list panel
|
||||
- Card search/filter panel
|
||||
- Deck composition panel
|
||||
- Validation/errors panel
|
||||
- Save/duplicate/delete actions
|
||||
|
||||
## Client
|
||||
- Build/edit decks, local mirror validation, save/duplicate/rename/delete.
|
||||
|
||||
## Server
|
||||
- Validate deck against current rules and persist deck revisions.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`DeckValidateRequest`)
|
||||
- `requestId`, `deckDraft`, `formatId`
|
||||
|
||||
### Server -> Client (`DeckValidateResponse`)
|
||||
- `requestId`, `isValid`, `errors`, `warnings`
|
||||
|
||||
### Client -> Server (`DeckSaveRequest`)
|
||||
- `requestId`, `deckId`, `deckName`, `deckCards`, `formatId`
|
||||
|
||||
### Server -> Client (`DeckSaveResponse`)
|
||||
- `requestId`, `success`, `deckId`, `deckRevision`, `isValid`, `errors`
|
||||
@@ -0,0 +1,25 @@
|
||||
# HubConnection Scene
|
||||
|
||||
## UI
|
||||
- Connection status indicator (connecting/retrying/failed)
|
||||
- Retry button + diagnostics link (optional)
|
||||
|
||||
## 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`, `platform`, `locale`, `deviceId`, `sessionId`
|
||||
|
||||
### Server -> Client (`HubWelcome`)
|
||||
- `requestId`, `connectionId`
|
||||
- `minSupportedClientVersion`, `latestClientVersion`, `latestContentVersion`
|
||||
- `serviceStatus`, `apiBaseUrl`, `cdnBaseUrl`
|
||||
- `authProvidersEnabled`, `motd` (optional)
|
||||
@@ -0,0 +1,9 @@
|
||||
# Leaderboard Scene
|
||||
|
||||
## Status
|
||||
Draft placeholder.
|
||||
|
||||
## Planned Scope
|
||||
- Define scene UI blocks
|
||||
- Define client interactions
|
||||
- Define server contract and payloads
|
||||
@@ -0,0 +1,21 @@
|
||||
# Login Scene
|
||||
|
||||
## UI
|
||||
- Username/email field
|
||||
- Password field
|
||||
- Remember device toggle
|
||||
- Submit + Forgot Password actions
|
||||
|
||||
## Client
|
||||
- Submit account identifier + password.
|
||||
- On success transition to `MainMenu`.
|
||||
|
||||
## Server
|
||||
- Validate credentials, enforce lockout and MFA if enabled.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`LoginRequest`)
|
||||
- `requestId`, `emailOrUsername`, `password`, `deviceId`
|
||||
|
||||
### Server -> Client (`LoginResponse`)
|
||||
- `requestId`, `success`, `accessToken`, `refreshToken`, `expiresAtUtc`, `accountSummary`, `errorCode`
|
||||
@@ -0,0 +1,30 @@
|
||||
# MainMenu Scene (Primary Interactive Hub)
|
||||
|
||||
## UI
|
||||
- Navigation nodes/buttons to:
|
||||
- `Bazaar`, `Leaderboard`, `Settings`, `AccountManagement`, `CollectionHub`, `RankedPlay`, `CustomPlay`
|
||||
- Profile summary widget
|
||||
- Notifications widget
|
||||
- Settings/logout actions
|
||||
- Interactive background:
|
||||
- dark aura visual treatment
|
||||
- rotatable 3D grid layer
|
||||
- grid topology can shift between square and hex
|
||||
|
||||
## Input
|
||||
- mouse + touch (multi-touch required)
|
||||
- standard camera gestures for movement
|
||||
- node selection via left click and middle mouse click
|
||||
|
||||
## Client
|
||||
- Display entry points and key account notifications.
|
||||
|
||||
## Server
|
||||
- Return role/entitlement menu permissions, badge counts, feature flags.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`MainMenuBootstrapRequest`)
|
||||
- `requestId`, `accountId`, `clientVersion`
|
||||
|
||||
### Server -> Client (`MainMenuBootstrapResponse`)
|
||||
- `requestId`, `profileSummary`, `roles`, `featureFlags`, `menuPermissions`, `notificationCounts`, `rankedSummary`
|
||||
@@ -0,0 +1,19 @@
|
||||
# OAuthCallback Scene
|
||||
|
||||
## UI
|
||||
- Verifying auth state message
|
||||
- Success/failure redirect panel
|
||||
|
||||
## Client
|
||||
- Receive callback code/state and exchange with backend.
|
||||
- On success transition to `MainMenu`.
|
||||
|
||||
## Server
|
||||
- Exchange auth code with provider and bind/create game account.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`OAuthExchangeRequest`)
|
||||
- `requestId`, `provider`, `authorizationCode`, `state`, `codeVerifier`
|
||||
|
||||
### Server -> Client (`OAuthExchangeResponse`)
|
||||
- `requestId`, `success`, `accessToken`, `refreshToken`, `expiresAtUtc`, `accountSummary`, `errorCode`
|
||||
@@ -0,0 +1,19 @@
|
||||
# OAuthStart Scene
|
||||
|
||||
## UI
|
||||
- Provider buttons
|
||||
- OAuth status text
|
||||
|
||||
## Client
|
||||
- Start OAuth flow with selected provider.
|
||||
- Open provider auth URL.
|
||||
|
||||
## Server
|
||||
- Generate signed OAuth start URL and anti-forgery state.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`OAuthStartRequest`)
|
||||
- `requestId`, `provider`, `returnUri`, `deviceId`
|
||||
|
||||
### Server -> Client (`OAuthStartResponse`)
|
||||
- `requestId`, `authorizationUrl`, `state`, `codeVerifier` (if PKCE client-managed)
|
||||
@@ -0,0 +1,25 @@
|
||||
# PatchAndVersionCheck Scene
|
||||
|
||||
## UI
|
||||
- Version comparison summary
|
||||
- Patch progress bar
|
||||
- Release notes panel (optional)
|
||||
- Continue button when ready
|
||||
|
||||
## Client
|
||||
- Compare installed version/content against server-required values.
|
||||
- If update needed: show patch status UI, download/apply, reconnect.
|
||||
- If up-to-date: continue to `AuthGateway`.
|
||||
|
||||
## Server
|
||||
- Provide update manifest and rollout policy.
|
||||
- Enforce hard-block 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)
|
||||
@@ -0,0 +1,9 @@
|
||||
# Ranked play Scene
|
||||
|
||||
## Status
|
||||
Draft placeholder.
|
||||
|
||||
## Planned Scope
|
||||
- Define scene UI blocks
|
||||
- Define client interactions
|
||||
- Define server contract and payloads
|
||||
@@ -0,0 +1,20 @@
|
||||
# Register Scene
|
||||
|
||||
## UI
|
||||
- Email/username/password inputs
|
||||
- Terms/privacy acceptance controls
|
||||
- Submit action + validation messages
|
||||
|
||||
## Client
|
||||
- Submit account fields and required agreements.
|
||||
- On success transition to `MainMenu`.
|
||||
|
||||
## Server
|
||||
- Create account, validate uniqueness, persist agreements.
|
||||
|
||||
## Data Exchange
|
||||
### Client -> Server (`RegisterRequest`)
|
||||
- `requestId`, `email`, `username`, `password`, `countryCode`, `dob`, `acceptedPolicies`
|
||||
|
||||
### Server -> Client (`RegisterResponse`)
|
||||
- `requestId`, `success`, `accessToken` (optional), `refreshToken` (optional), `accountSummary` (optional), `requiresEmailVerification`, `errorCode`
|
||||
@@ -0,0 +1,9 @@
|
||||
# Settings Scene
|
||||
|
||||
## Status
|
||||
Draft placeholder.
|
||||
|
||||
## Planned Scope
|
||||
- Define scene UI blocks
|
||||
- Define client interactions
|
||||
- Define server contract and payloads
|
||||
Reference in New Issue
Block a user