GameFi runtime and mobile web game performance roadmap

[Jim8y]

English

This issue defines a focused roadmap for improving OneGate as a high-performance GameFi/mobile web game runtime while avoiding overlap with existing PRs and avoiding previously rejected directions from Erik/admin review.

Related context: #36 covers first-party OneGate Experiences compatible with current web dApps. This issue is narrower: game runtime performance, game developer requirements, and GameFi integration quality.

Current PR overlap audit

The following open PRs already cover adjacent work and should not be duplicated here:

• Improve gaming hub experience #56 Improve gaming hub experience: game discovery/hub polish. Do not mix hub UI changes into runtime-performance PRs.
• Add dApp load failure and retry states #67 Add dApp load failure and retry states: generic dApp load failure/retry states. Do not duplicate generic loading/error work.
• [codex] Add dApp address book contact picker API #72 Add dApp address book contact picker API: native address-book picker for dApps.
• [codex] Add dApp QR scanner API #73 Add dApp QR scanner API: native QR scanner for dApps.
• [codex] Add dApp asset picker API #74 Add dApp asset picker API: native wallet asset picker for dApps.
• [codex] Add dApp share API #75 Add dApp share API: native system share sheet for dApps.
• Improve dApp detail page #55 Improve dApp detail page, Add Activity Center #53 Add Activity Center, Polish design system styles #57 Polish design system styles, Add global search #54 Add global search: avoid touching these surfaces unless a task explicitly depends on them and the PR stays narrow.

Erik/admin review guardrails

Future PRs from this roadmap must respect these constraints from historical Erik/admin feedback:

• Keep PRs small and focused. Erik explicitly asked to break large work down into smaller PRs (P0: Limit wallet hardening to requested fixes #30).
• Do not commit screenshots or visual QA artifacts to the repo ([codex] Add address book transfer history #31). Upload screenshots externally and comment on the PR.
• Do not include unrelated changes in PRs ([codex] Add address book transfer history #31, Add address book data service #37).
• Do not add clipboard-related UI/behavior unless explicitly requested (Improve send address safety #35).
• Do not store transaction records locally; OneGate should provide online/RPC access instead (Add address book data service #37).
• Avoid empty-string defaults for data labels (Add address book data service #37).
• Keep converter/helper code in appropriate separate files when needed (Add visual system foundation #38).
• Preserve OneGate's multi-window dApp design; each dApp should open as its own window/document where supported (Fix game dApp launch and wallet injection #40).
• Avoid large card-heavy designs that do not improve quality (Redesign home feed with card visuals #42).
• Do not add a persistent dApp runtime trust bar; it takes too much space. Put truly useful content on dApp details instead (Add dApp runtime trust bar #47).
• Do not adapt third-party dApp UI inside OneGate. DApp-specific mobile layout issues should be reported to dApp developers (Improve N3 Governance mobile layout #48).
• Do not build a connected-app permission center that treats public addresses as private authorization state. NEP-21 authenticate is for website authentication, not generic user authorization (Add connected apps permission center #49).
• Transaction preview improvements must focus on missing key information such as asset hash and payment/receiving addresses, and avoid repetitive fee/amount clutter (Add transaction preview v2 #50).
• Do not create an “official dApp” wrapper just to mark an existing dApp official (Officialize OneGate Vault experience #51).
• Avoid duplicated Security Center panels and generic separate recommendation panels (Improve Security Center risk overview #52).
• Use clear domain naming; avoid vague names such as VaultOperation (Add Activity Center #53).
• Use real token/dApp/contact icons where expected (Add global search #54).
• Gaming UI must provide useful content and correct alignment/margins (Improve gaming hub experience #56).
• Do not use NEO green as OneGate brand color (Polish design system styles #57).

Proposed PR sequence

Each PR must be independently reviewable, must avoid unrelated refactors, and must include Android + iOS simulator validation with screenshots posted in the PR comments only.

1. Game Runtime Mode

Scope: Add a dedicated runtime mode for game dApps: immersive/fullscreen container, safe exit affordance, orientation handling, safe-area handling, and minimized app chrome.

Why: Heavy games need more screen space and fewer layout interruptions than normal dApps. This is different from the rejected trust bar (#47): it removes chrome instead of adding a persistent bar.

Acceptance: Android and iOS simulator launch a game dApp in runtime mode; normal dApps remain unchanged; no game-specific UI adaptation is hardcoded.

2. Game Runtime Lifecycle Controls

Scope: Pause/resume hooks, background/foreground handling, audio suspension/resume, WebGL context-loss detection messaging, and reload recovery affordance.

Why: Mobile WebView games are sensitive to lifecycle changes. OneGate should help the runtime recover cleanly without owning the game's internal UI.

Acceptance: Runtime exposes lifecycle events to dApps and handles app background/foreground transitions without crashing.

3. Game Performance HUD for Developer Mode

Scope: Add a developer-only HUD for game dApps showing FPS estimate, long-frame count, load timing, WebGL support/context-loss status, and current URL/origin.

Why: Game performance issues need concrete metrics. The HUD must be developer-only so it does not repeat the rejected always-visible trust bar pattern.

Acceptance: HUD is hidden unless developer mode is enabled; screenshots show metrics on Android and iOS; no user-facing clutter by default.

4. Game Manifest and Capability Contract

Scope: Define a lightweight onegate-game.json manifest schema: game type, preferred orientation, fullscreen preference, asset budget, required OneGate APIs, supported input methods, and version/hash metadata.

Why: OneGate needs a predictable way to decide runtime mode and preload policy without guessing per dApp.

Acceptance: Runtime reads optional manifest metadata; missing manifest falls back to current behavior.

5. CDN Asset Budget and Cache Policy

Scope: Add documented and/or runtime-enforced budgets for initial JS/WASM, textures, audio, total first-load bytes, cache headers, and hashed filenames.

Why: Current game pain points include long white screens and heavy assets. The fix should be a game publishing contract, not ad hoc OneGate-side adaptation.

Acceptance: A developer checklist and optional runtime diagnostics warn when a game exceeds budget; no blocking behavior without explicit policy.

6. OneGate Game SDK Package

Scope: Provide a small TypeScript SDK wrapper over existing dAPI/native capabilities: wallet connect, sign/send, address picker (#72), QR scanner (#73), asset picker (#74), share (#75), fullscreen/orientation/lifecycle events.

Why: Game developers should not hand-roll bridge calls. The SDK should encode OneGate best practices while respecting NEP-21 semantics.

Acceptance: SDK sample works inside Android WebView and iOS WKWebView; SDK does not add new wallet authorization semantics that conflict with Erik's NEP-21 feedback.

7. Phaser/Pixi GameFi Starter Template

Scope: Add an external/template project or docs for a mobile-first GameFi starter using Phaser or PixiJS, TypeScript, Vite, responsive canvas, loading/progress/error states, wallet connect, and deferred chain settlement.

Why: For most OneGate games, Phaser/Pixi are better mobile-web defaults than shipping heavy desktop/Unity builds. This should guide game teams without bloating OneGate app code.

Acceptance: Template demonstrates mobile canvas sizing, resource loading, OneGate SDK usage, and a mock settlement flow.

8. Game QA Checklist and Performance Gate

Scope: Create a repeatable QA checklist for game submissions: Android/iOS simulator validation, low-end-device budget, load time, FPS/jank, memory, WebGL context loss, wallet connect/sign, orientation, offline/retry, screenshots.

Why: Game quality should be enforced before listing, not patched inside OneGate after launch.

Acceptance: Checklist is usable in PR/issue review and references current screenshot policy.

9. DApp/Game Submission Form Extension

Scope: Extend the dApp listing issue form after #70 lands to include game-specific fields: manifest URL, runtime mode, orientation, resource budget, wallet APIs used, screenshots, and licensing notes.

Why: Game submissions need more metadata than normal dApps.

Dependency: Wait for #70 to land or update #70 if reviewer prefers. Do not create a competing issue template PR before #70 is resolved.

10. Runtime Diagnostics Report Export

Scope: Add a debug action to export/copy a diagnostics summary for the current game session: URL, device, WebView platform, timing, errors, native API calls summary, and app version.

Why: Game developers need actionable reports when OneGate users report performance or wallet-integration issues.

Acceptance: Report contains no private keys, seed data, or sensitive wallet data.

Explicit non-goals

• No OneGate-side per-game DOM/CSS adaptation for third-party dApps.
• No persistent dApp trust bar.
• No connected-app permission center that conflicts with NEP-21 semantics.
• No local transaction history database.
• No official dApp wrapper for existing dApps.
• No broad dashboard redesign or unrelated visual polish.
• No screenshots committed to the repository.

---

中文

这个 issue 定义 OneGate 作为高性能 GameFi / 移动 Web 游戏运行时的路线图，同时避免和现有 PR 重复，也避免重复做 Erik / 管理员历史上已经拒绝过的方向。

相关背景：#36 讨论的是兼容现有 web dApp 的 first-party OneGate Experiences。这个 issue 范围更窄，只关注游戏运行时性能、游戏开发规范、GameFi 钱包集成质量。

当前 PR 重合审计

以下 open PR 已经覆盖相邻工作，本 issue 后续任务不应重复：

• Improve gaming hub experience #56 Improve gaming hub experience：游戏发现 / 游戏入口体验。后续运行时性能 PR 不混入 Hub UI。
• Add dApp load failure and retry states #67 Add dApp load failure and retry states：通用 dApp 加载失败 / 重试状态。不要重复做通用加载错误态。
• [codex] Add dApp address book contact picker API #72 Add dApp address book contact picker API：dApp 调用 OneGate 地址簿。
• [codex] Add dApp QR scanner API #73 Add dApp QR scanner API：dApp 调用 OneGate 扫码。
• [codex] Add dApp asset picker API #74 Add dApp asset picker API：dApp 调用 OneGate 资产选择。
• [codex] Add dApp share API #75 Add dApp share API：dApp 调用系统分享面板。
• Improve dApp detail page #55、Add Activity Center #53、Polish design system styles #57、Add global search #54 分别覆盖 dApp 详情、活动中心、设计系统、全局搜索；除非某个任务明确依赖，否则不要碰这些页面。

Erik / 管理员历史意见约束

后续所有 PR 必须遵守这些历史反馈：

• PR 必须小而聚焦。Erik 明确要求大 PR 拆小（P0: Limit wallet hardening to requested fixes #30）。
• 不要把截图或 QA 图片提交进仓库；截图上传到外部 GitHub asset 并评论到 PR（[codex] Add address book transfer history #31）。
• 不要混入无关改动（[codex] Add address book transfer history #31、Add address book data service #37）。
• 不要添加剪贴板相关 UI/行为，除非明确要求（Improve send address safety #35）。
• 不要本地存交易记录；OneGate 应提供在线/RPC 查询能力（Add address book data service #37）。
• 数据 label 不要用空字符串作为默认值（Add address book data service #37）。
• converter/helper 需要单独文件时要按结构拆分（Add visual system foundation #38）。
• 保持 OneGate 的多窗口 dApp 设计；支持的平台上每个 dApp 应独立窗口/文档打开（Fix game dApp launch and wallet injection #40）。
• 避免没有明显提升的大卡片设计（Redesign home feed with card visuals #42）。
• 不要做常驻 dApp trust bar；它占空间，真正有用的信息应放到 dApp 详情页（Add dApp runtime trust bar #47）。
• 不要在 OneGate 里适配第三方 dApp UI；第三方 dApp 的移动端布局问题应反馈给 dApp 开发者（Improve N3 Governance mobile layout #48）。
• 不要做和 NEP-21 语义冲突的 connected apps 权限中心；authenticate 是网站认证用户，不是用户授权网站（Add connected apps permission center #49）。
• 交易预览要突出真正缺失的关键信息，例如资产 hash、付款地址、收款地址；避免重复展示金额/手续费并挤占主要内容（Add transaction preview v2 #50）。
• 不要为了“官方化”再包装一个官方 dApp（Officialize OneGate Vault experience #51）。
• 避免重复的 Security Center panel 和泛泛的独立建议面板（Improve Security Center risk overview #52）。
• 命名要清晰，不要使用 VaultOperation 这种模糊名称（Add Activity Center #53）。
• token / dApp / contact 应尽量使用真实图标（Add global search #54）。
• 游戏 UI 必须有用，图标垂直居中、上下边距一致（Improve gaming hub experience #56）。
• 不要把 NEO 绿色当作 OneGate 品牌色（Polish design system styles #57）。

建议 PR 顺序

每个 PR 必须独立可 review，不混入无关重构，并且必须在 Android 和 iOS 模拟器验证，截图只放 PR 评论。

1. Game Runtime Mode

范围： 为游戏 dApp 增加专用运行模式：沉浸/fullscreen 容器、安全退出入口、方向处理、safe area、最小化普通 app chrome。

原因： 重游戏需要更多屏幕空间和更少布局干扰。这和被拒绝的 trust bar 不同：这里是减少 chrome，不是新增常驻栏。

验收： Android/iOS 模拟器能以 runtime mode 打开游戏 dApp；普通 dApp 不受影响；不写死任何具体游戏适配。

2. Game Runtime Lifecycle Controls

范围： pause/resume hooks、前后台切换、音频暂停/恢复、WebGL context lost 检测提示、reload recovery。

原因： 移动 WebView 游戏对生命周期变化敏感。OneGate 应帮助运行时恢复，而不是接管游戏内部 UI。

验收： runtime 能向 dApp 暴露 lifecycle events，前后台切换不崩溃。

3. Game Performance HUD for Developer Mode

范围： 给游戏 dApp 增加仅开发者模式可见的 HUD：FPS 估算、long frame 数量、加载耗时、WebGL 支持/context lost、当前 URL/origin。

原因： 游戏性能问题需要指标定位。HUD 默认隐藏，避免重复 trust bar 的占空间问题。

验收： 只有 developer mode 开启时显示；Android/iOS 截图展示指标；默认用户界面无额外干扰。

4. Game Manifest and Capability Contract

范围： 定义轻量 onegate-game.json：游戏类型、建议方向、是否 fullscreen、资源预算、需要的 OneGate API、输入方式、版本/hash metadata。

原因： OneGate 需要可预测地决定 runtime mode 和 preload 策略，而不是按 dApp 猜测。

验收： runtime 可读取可选 manifest；没有 manifest 时保持现有行为。

5. CDN Asset Budget and Cache Policy

范围： 为首屏 JS/WASM、纹理、音频、总首载大小、cache headers、hashed filenames 建立文档/诊断预算。

原因： 当前游戏痛点包括白屏时间长、资源过重。应通过发布规范解决，而不是 OneGate 临时适配。

验收： 有开发者 checklist；runtime diagnostics 可提示超预算；默认不做阻断。

6. OneGate Game SDK Package

范围： 做 TypeScript SDK 封装现有 dAPI/native 能力：钱包连接、签名/交易、地址簿 #72、扫码 #73、资产选择 #74、分享 #75、fullscreen/orientation/lifecycle events。

原因： 游戏开发者不应手写 bridge 调用。SDK 应编码 OneGate 最佳实践，同时尊重 NEP-21 语义。

验收： SDK 示例能在 Android WebView 和 iOS WKWebView 运行；不新增与 Erik NEP-21 反馈冲突的钱包授权语义。

7. Phaser/Pixi GameFi Starter Template

范围： 提供外部模板或 docs：Phaser/Pixi + TypeScript + Vite，移动优先 canvas、加载/进度/错误态、钱包连接、延迟链上结算。

原因： 对多数 OneGate 游戏，Phaser/Pixi 比直接上桌面化 Unity 大包更适合移动 WebView。

验收： 模板展示移动 canvas sizing、资源加载、OneGate SDK 使用、mock settlement flow。

8. Game QA Checklist and Performance Gate

范围： 制定游戏提交 QA checklist：Android/iOS 模拟器、低端机预算、加载耗时、FPS/jank、内存、WebGL context lost、钱包连接/签名、方向、离线/重试、截图。

原因： 游戏质量应该在上架前把关，而不是上线后靠 OneGate 修补。

验收： checklist 可直接用于 PR/issue review，并遵守当前截图策略。

9. DApp/Game Submission Form Extension

范围： 等 #70 合并后扩展 dApp listing issue form，加入游戏特有字段：manifest URL、runtime mode、方向、资源预算、使用的钱包 API、截图、授权说明。

原因： 游戏提交需要比普通 dApp 更多 metadata。

依赖： 等 #70 合并或按 reviewer 意见更新 #70。不要在 #70 未解决前再开竞争性 issue template PR。

10. Runtime Diagnostics Report Export

范围： 增加调试动作，导出/复制当前游戏 session 诊断摘要：URL、设备、WebView 平台、timing、错误、native API calls summary、app version。

原因： 当用户报告性能或钱包集成问题时，游戏开发者需要可操作的报告。

验收： 报告不包含私钥、助记词或敏感钱包数据。

明确不做

• 不在 OneGate 侧为第三方 dApp 做逐个 DOM/CSS 适配。
• 不做常驻 dApp trust bar。
• 不做与 NEP-21 语义冲突的 connected apps 权限中心。
• 不做本地交易历史数据库。
• 不为现有 dApp 做“官方 dApp”包装。
• 不混入 dashboard 重构或无关视觉 polish。
• 不把截图提交进仓库。

[Jim8y]

Task 2 update: opened draft PR #78 for Game Runtime Lifecycle Controls.\n\nStatus:\n- Android emulator E2E passed, including WebView CDP verification of OneGateGameRuntime, provider/DOM lifecycle events, WebGL context-loss event, background/restore lifecycle events, and non-game dApp regression.\n- iOS simulator build/install/launch passed.\n- iOS app-internal game WebView E2E remains blocked in this local debug environment because simctl openurl https://onegate.space/app/25 routes to Safari/web details instead of the local OneGate WebView. PR remains draft until that path is manually verified or simulator automation is corrected.\n\nScreenshots are posted on #78 as external GitHub assets only.

[Jim8y]

Task 3 update: opened draft PR #79 for the developer-only Game Performance HUD.\n\nStatus:\n- Android emulator E2E passed: developer mode enabled, game dApp opened, HUD displayed, and WebView CDP verified showMetrics() / getMetrics() with FPS, long frames, worst frame, load timing, WebGL support, context-loss count, origin, and URL.\n- iOS simulator build/install/launch passed.\n- iOS app-internal game WebView HUD E2E remains blocked by the same local associated-domain limitation: simctl openurl https://onegate.space/app/25 routes to Safari/web details instead of the local OneGate WebView. PR remains draft until that is manually verified or simulator automation is corrected.\n\nScreenshots are posted on #79 as external GitHub assets only.

[Jim8y]

Task 4 status update: Game Manifest and Capability Contract is implemented in #80. Scope stayed limited to the optional manifest model/loading contract and provider exposure; no hub UI, trust bar, permission center, third-party UI adaptation, or runtime policy decisions were added. Android and iOS simulator validation screenshots are posted on the PR.

[Jim8y]

Task 5 status update: CDN Asset Budget and Cache Policy is implemented in #81. Scope stayed documentation/policy only: budgets, cache headers, content types, hashed filenames, manifest linkage, and submission checklist. It does not add runtime blocking, trust bar, third-party UI adaptation, hub UI changes, SDK, or template work. Android and iOS simulator validation screenshots are posted on the PR.

[Jim8y]

Task 6 status update: OneGate Game SDK Package is implemented in #82. Scope is limited to a standalone TypeScript SDK over the injected OneGate provider and optional native capabilities. It does not add new wallet authorization semantics, permission-center behavior, MAUI runtime changes, trust bar UI, or third-party game UI adaptation. Android and iOS simulator validation screenshots are posted on the PR.

[Jim8y]

Task 7 status update: Phaser/Pixi GameFi Starter Template is implemented in #83 as a starter guide. Scope is documentation only: recommended stack, project layout, loading shell, Phaser/Pixi bootstrap, OneGate SDK integration, wallet settlement pattern, runtime events, and mobile QA expectations. It does not add a full game project, frontend dependency tree, generated assets, app runtime changes, hub UI, or third-party game UI adaptation. Android and iOS simulator validation screenshots are posted on the PR.

[Jim8y]

Task 8 status update: Game QA Checklist and Performance Gate is implemented in #84. Scope is documentation only: submission evidence, loading/failure states, mobile layout, performance thresholds, wallet integration, optional native capabilities, platform matrix, reviewer template, and pass criteria. It does not add runtime diagnostics export, runtime blocking, local transaction storage, permission-center behavior, trust bar UI, or third-party DOM/CSS adaptation. Android and iOS simulator validation screenshots are posted on the PR.