Skip to content

Agent.md

Latest commit

 

History

History
49 lines (34 loc) · 3.4 KB

Agent.md

File metadata and controls

49 lines (34 loc) · 3.4 KB
Raw

Agent Directives & Game Context (Aetheris v3.0)

This document is designed to give AI coding assistants and autonomous agents the complete technical context, architecture schema, and structural conventions of Aetheris v3.0. Read this file fully before creating new features or modifying the core gameplay loop.

Overview

Aetheris is an idle/clicker MMO hybrid built on a serverless stack meant to function at scale on Cloudflare's free tier. The architecture specifically avoids long-running processes (like Node.js servers) in favor of Edge computing.

Monorepo Layout (Turborepo)

  • packages/web/ - React/Phaser frontend.
    • src/App.tsx - Main shell, handles tab navigation (forge, upgrades, market, leaderboard, achievements, profile).
    • src/useGameState.ts - God-hook managing the synchronization between local clicks and the remote backend polling mechanism. Keep complex game math here.
    • src/PhaserGame.tsx - The graphical interface. Communicates with React via React.MutableRefObject and imperative handles.
    • src/Market.tsx & src/PriceChart.tsx - Complex UI for the order book and native canvas candlestick charts.
    • src/PasskeyAuth.tsx - WebAuthn registration and verification flows.
  • packages/backend/ - Cloudflare Worker running Hono.
    • src/index.ts - All API routes. Keeps business logic entirely inside Cloudflare Workers.
    • schema.sql - Base DB schema.
    • migration_*.sql - Sequential migrations for updating the D1 database.
  • packages/contracts/ - Hardhat workspace for Solidity. (Currently mostly scaffolding, active logic resides in backend).

Tech Stack & Caveats

  • Package Manager: Bun (bun install, bun run dev).
  • Database: Cloudflare D1 (SQLite semantics). No foreign key constraints enabled by default. ALTER TABLE is limited.
  • Build/Lint: Strict ESLint flat config + Prettier. Run bun run fix prior to any PR.
  • State Management: React local state synced periodically with D1 backend. Immediate visual feedback is prioritized over strict real-time validation to handle edge latency elegantly.

Database Realities (Cloudflare D1)

When adding new features, note the following tables:

  1. mainframe_state: Singleton table (id=1). Tracks integrity, max_integrity, and last_regen_at for boss HP.
  2. users: Stores hash_balance, data_balance, cred_balance and stats.
  3. market_orders & trades: Used by the order matching engine.
  4. passkey_credentials: Maps public keys to user_ids for WebAuthn.

Warning: D1 writes are asynchronously batched under the hood, but reads are highly distributed. The Hono code executes matching engines serially, which works at this scale but must avoid complex distributed locks.

Writing New Features

  1. Backend Extensions: Add new Hono routes in packages/backend/src/index.ts. Remember to interact with c.env.DB securely using bound statements (?1, ?2).
  2. Frontend Extensions: Expose backend endpoints via functions in packages/web/src/useGameState.ts or directly within the new UI component if isolated (like Market.tsx).
  3. UI Components: Build inside packages/web/src/. Rely on Tailwind CSS. Green/Black matrix aesthetics are preferred.

Deployment Strategy

The frontend and backend both run on Cloudflare. The backend worker exposes api.aetheris-backend.workers.dev (or similarly named domains), and the frontend connects via VITE_API_URL fallback constants.