phenom/i-want-to-heal-mmo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 22 Wiki Activity

Update 3D game 2026-07-10 21:20

Browse Source
This commit is contained in:
Warren H
2026-07-10 21:20:17 -04:00
parent 141ec64963
commit e0be0458aa
720 changed files with 366857 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+97
View File
@@ -0,0 +1,97 @@
# AGENTS.md
These requirements apply to every screen, feature, game system, and code change in this repository.
## Product priority
AYN Thor Android app is the primary product. Browser build is a secondary access path for players without an AYN Thor. Do not weaken the Thor experience to simplify the browser version; provide an adaptive browser fallback instead.
## AYN Thor display and layout targets
Design and test against both physical displays in landscape orientation. Physical panel resolution and Android CSS/layout viewport are different concepts; record and validate both.
| Display | Panel specification | Android CSS/layout viewport |
| --- | --- | ---: |
| Main / top | 6-inch AMOLED, 1920 x 1080 physical pixels, 120 Hz | Approximately 960 x 540 CSS pixels |
| Secondary / bottom | 3.92-inch AMOLED, 1240 x 1080 physical pixels, 60 Hz | Approximately 620 x 540 CSS pixels |
- `1920 x 1080` and `1240 x 1080` describe physical framebuffer/panel pixels. They are not the UI layout viewports.
- All Thor UI sizing, breakpoints, typography, hit targets, navigation geometry, and visual QA must use the Android CSS/layout viewport: approximately `960 x 540` for the main display and `620 x 540` for the secondary display.
- Use physical resolution only for render-buffer quality, pixel density, screenshot validation, and GPU/performance decisions.
- Ship gameplay at a stable, locked 60 FPS on both displays. The main panel can refresh at 120 Hz, but 60 FPS is the required game target.
- Treat the displays as two independent surfaces with different aspect ratios, not one continuous `3160 x 1080` canvas.
- Use each display's own container or viewport dimensions for layout and typography. Never size bottom-screen UI from the top screen or combined page viewport.
- Approximate CSS viewports reflect current Android scaling. Runtime code must still measure actual viewport size, device pixel ratio, safe insets, and Android system-bar insets rather than assuming those values are constant.
- Keep critical controls and information inside safe bounds. No clipping, overlap, unreadably small text, or off-screen focus state at either target size.
- Any new full-screen view, menu, modal, HUD, overlay, loading state, and error state must be checked at both CSS/layout viewports and their corresponding physical framebuffer resolutions.
## Dual-screen behavior
- Use both Thor screens whenever the second display can add useful information or controls without duplicating clutter.
- Top screen owns primary 3D gameplay, world presentation, cinematics, and information needed while looking at the action.
- Bottom screen should host contextual/tactical UI such as party state, abilities, maps, inventory, quests, chat, loadouts, and settings where appropriate.
- Actions and state must stay synchronized across displays. Moving a feature to the bottom screen must not hide required feedback from the top screen.
- Keep rendering and update work independent so an expensive bottom-screen UI update cannot stall top-screen gameplay.
- Support display attach, detach, recreation, sleep, and resume without losing game state or duplicating input handlers.
- Browser/single-display mode must preserve all features through responsive panels, tabs, drawers, or overlays. Dual-screen layout remains preferred on Thor.
## Controller-first navigation
Every screen must be fully operable with the built-in controller. Touch, mouse, and keyboard are optional alternate inputs.
- No action may require tapping, clicking, hovering, or focusing the canvas/DOM first.
- Do not depend on browser/DOM focus for gamepad routing. Poll and route controller input through one app-level input service, then send semantic actions to gameplay and UI.
- Every interactive item must be reachable in a deterministic order and show a clear visible focus state.
- Directional navigation must match spatial layout. Define explicit neighbors when automatic spatial navigation would be ambiguous.
- Provide controller paths for confirm, cancel/back, tab or section changes, scrolling, sliders, dialogs, tooltips, pause, and return to gameplay.
- Trap navigation inside an open modal, then restore focus to the element that opened it when the modal closes.
- Choose a safe default focus target whenever a screen opens or the active display changes. Never leave focus nowhere or behind an overlay.
- Prevent held buttons and analog drift from causing uncontrolled repeats. Use dead zones, initial repeat delay, repeat rate, debouncing, and one-shot press edges as appropriate.
- Clear held-input state on controller disconnect, app pause, visibility change, screen recreation, and display handoff.
- Keep controller mappings centralized and remappable. UI prompts must reflect the active controller mapping.
- Avoid text entry for required flows where possible. When required, provide an Android/controller-accessible input path.
- Browser fallback must not require a click to focus individual controls or the game canvas. Browser/OS restrictions may require the browser itself to be active and may require one initial user gesture before the Gamepad API is exposed; no game code may add further focus requirements.
## Modular game architecture
Build every game mechanic as a reusable, composable module. Repeated mechanic code is a defect.
- Separate game rules and state from rendering, React components, display routing, input devices, audio, persistence, and networking.
- Expose mechanics through small typed interfaces and semantic commands/events. Do not let a mechanic read DOM state or hard-code a specific screen.
- Make abilities, effects, enemies, encounters, items, quests, and UI bindings data-driven when behavior differs mainly by configuration.
- Prefer shared systems and composition over copied handlers, large conditional components, or deep inheritance.
- Keep one authoritative state model. Both displays render projections of shared state rather than maintaining competing copies.
- Put shared timing, cooldown, targeting, resource, status-effect, damage, healing, and validation logic in domain modules usable by players, AI, previews, tooltips, and tests.
- Inject platform-specific adapters for Android, browser, storage, display, input, and network behavior.
- Add focused tests for reusable mechanics and regression tests for bugs. A mechanic should be testable without launching the renderer or mounting UI.
- Before adding code, search for an existing system that can be extended. If similar logic appears twice, extract the common behavior unless doing so would create a less coherent abstraction.
## Performance requirements
Stable locked 60 FPS is a release requirement, not a best-effort goal.
- Treat the AYN Thor Lite configuration (Snapdragon 865, 8 GB RAM) as the performance floor unless project requirements explicitly change.
- Maintain a 16.67 ms total frame budget during real gameplay, including simulation, scripting, rendering, UI, and cross-display synchronization.
- Profile representative gameplay on physical Thor hardware. Desktop-only measurements are insufficient for performance-sensitive changes.
- Measure before and after substantial changes. Track frame time, 1% lows, long frames, CPU time, GPU time, JavaScript heap, native memory, draw calls, triangles, texture memory, and garbage-collection pauses where tooling permits.
- Do not allocate objects, arrays, closures, materials, textures, or temporary vectors in hot per-frame paths when reusable storage or pooling is practical.
- Dispose GPU, audio, event-listener, timer, subscription, and display resources deterministically when their owner unloads.
- Use culling, LOD, instancing, batching, compressed textures, bounded particle counts, and asset streaming/lazy loading where they measurably help.
- Keep simulation work bounded. Avoid unbounded searches, per-frame full-collection scans, unnecessary polling, and update loops for invisible or inactive entities.
- Prevent avoidable React renders. Subscribe to narrow state slices, memoize only where measured or structurally useful, batch updates, and throttle non-critical bottom-screen telemetry.
- Load heavy screens and assets on demand, but prefetch predictable transitions when memory budget allows.
- Avoid duplicate assets and duplicate state in memory across displays. Share immutable resources where platform APIs allow.
- Favor algorithms and data layouts that reduce CPU and RAM together. Do not trade a large permanent memory increase for a tiny unmeasured CPU gain.
- Performance fixes must preserve deterministic rules, input responsiveness, visual clarity, and controller accessibility.
## Definition of done
A screen or mechanic is not complete until:
1. Its main-display UI is designed and verified at the approximately `960 x 540` Android CSS/layout viewport, with rendering validated against the `1920 x 1080` physical panel.
2. Its applicable secondary UI is designed and verified at the approximately `620 x 540` Android CSS/layout viewport, with rendering validated against the `1240 x 1080` physical panel.
3. It has a complete single-display browser fallback.
4. Every action is reachable and understandable using only a controller, with no click-to-focus step.
5. Shared game logic is modular, typed, and testable outside the renderer/UI.
6. It introduces no known resource leak, unbounded work, or avoidable hot-path allocation.
7. Representative Thor hardware sustains the locked 60 FPS target, or the change includes measured evidence and an explicit approved exception.