i-want-to-heal/README.md

The Ashen Halls

A UI-focused 2D healer game prototype. The player selects party frames and uses healing, shielding, and cleansing spells while an AI party fights through a dungeon encounter.

Why this stack

• React + TypeScript: The game is mostly interactive UI, timers, bars, and state. A full game engine is not necessary for the first version.
• CSS pixel-art presentation: Fast to iterate now; sprite sheets and richer animation can be layered in later.
• SQLite: Stores authored content and durable player data. Live combat state remains in memory because health and cooldowns change many times per second.
• Electron later: The web build can be wrapped as a Windows/macOS/Linux desktop game once the core loop is fun.

Phaser or Godot becomes worthwhile if the design grows into animated battlefield positions, projectile-heavy combat, physics, or map exploration.

Run it

npm install
npm run db:init
npm run dev

Use the mouse to select a party member and click spells, or use keys 1 through 6.

For an online production build, see DEPLOYMENT.md.

Current vertical slice

• Five party members with tank, healer, and damage roles
• Mana management, cooldowns, direct healing, healing over time, group healing, shields, and cleansing
• Reduced starter ability costs tuned to sustain an efficient full dungeon run
• High-contrast selected-target raid frames and a persistent active-target card
• Per-difficulty dungeon efficiency leaderboards ranked by resource spent, with class, level, item-level, and run-duration snapshots
• Account registration, secure password hashing, cookie sessions, logout, and fully isolated character progression for each account
• One-account-per-public-IP registration with local administrator exceptions
• Live-safe SQLite backups for self-hosted account and save data
• Explicit offline characters with local progression, gear, talents, and loot
• A shared repository boundary for online HTTP, browser-local, and future desktop SQLite persistence
• Two trash encounters followed by Warden Vhal
• Boss-wide damage and a dispellable damage-over-time mechanic
• Victory, defeat, loot, and restart states
• Main menu with Dungeons, Raids, PvP, Customize Character, and Talents
• SQLite-backed class selection and persistent six-slot ability loadouts
• Three healer class foundations with level-gated abilities
• SQLite-driven experience progression from level 1 to 25
• Dungeon XP rewards, level-up handling, talent-point awards, and ability unlocks
• SQLite-backed class talent trees with ranks, tiers, prerequisites, refunds, and immediate persistence
• Seven equipment slots, starter item-level 1 gear, inventory comparison, and persistent equipping
• Aggregate item level, healing power, and resource bonuses that affect combat
• Five SQLite-authored dungeon difficulty tiers with level gates, combat scaling, XP multipliers, and item-level reward bands
• Encounter-specific weighted loot tables for every difficulty, with authored drop chances, slot pools, and item-level 5 through 25 reward variants
• One live loot roll per defeated encounter, shown in the combat log and dungeon-complete summary
• Atomic inventory awards with retry-safe roll records and stacked duplicate quantities
• Safe duplicate cleanup that can discard spare copies without removing the character's final copy
• SQLite schema and seed data for progression, talents, item-level difficulties, boss loot, characters, inventory, and runs

Architecture direction

The combat simulator should stay framework-independent as it grows. React renders the current state and handles player input. A content repository will load classes, spells, dungeons, encounters, mechanics, and loot from SQLite. This makes it possible to add content through an editor later without rewriting combat code.

The Vite development and preview servers expose a local SQLite API used by the character screens. The API validates class ownership, unlock levels, duplicate abilities, and the six-slot limit. When the project is wrapped in Electron, this same repository boundary can move into the Electron main process.

Offline characters use a separate browser-local save and do not require an account. Production web builds cache the application shell after one successful visit so they can reopen without a connection. Offline characters are excluded from online leaderboards. Run npm run offline:export after changing SQLite-authored classes, abilities, dungeons, difficulties, items, or loot tables so new offline characters receive the updated starter content.

Suggested milestones

1. Move combat updates into a deterministic simulation module and add tests.
2. Apply authored talent effects to combat calculations.
3. Add currency or crafting materials for selling and salvaging spare gear.
4. Add two more bosses to complete the first three-boss dungeon.
5. Add cast times, global cooldowns, threat, overhealing, and a combat summary.
6. Replace placeholder glyphs with original pixel-art portraits, spell icons, enemies, and effects.

Creative boundary

Genre conventions such as party frames, mana, cooldowns, dispels, and healing styles are fair inspiration. Keep class names, spell names, lore, icons, sounds, characters, encounter text, and artwork original rather than copying World of Warcraft assets or terminology.

I want to Heal

Android and AYN Thor

The Android build uses Capacitor and includes a native DualScreen plugin. The plugin enumerates Android displays, launches the full interactive game on the largest display, and changes the smaller display to a compact dungeon, resource, targeting, skill, and cooldown panel. Android controller key events are forwarded into the web input system so menus and combat can both be navigated without touch.

On devices that do not permit an activity to launch on a secondary display, the plugin falls back to a fullscreen Presentation WebView.

Build prerequisites:

• Android Studio with Android SDK 36
• JDK 17 or the Java runtime bundled with Android Studio

Useful commands:

npm run android:sync
npm run android:open
npm run android:apk

The debug APK is written to:

android/app/build/outputs/apk/debug/app-debug.apk

On the Thor, open Settings and inspect the display diagnostics under AYN Thor Dual-Screen Mode. The expected displays are approximately:

• 1920×1080 at 120 Hz
• 1240×1080 at 60 Hz

If Android starts the main activity on the upper panel, the next native fallback is a second activity launched onto the lower display with ActivityOptions.setLaunchDisplayId(). The diagnostics identify whether that fallback is needed on the installed Thor firmware.