Projeto Apoteose Development

Expert guidance for working with Projeto Apoteose, a browser-based cultivation/immortal progression game inspired by Chinese cultivation novels.

Overview

Projeto Apoteose is built entirely in vanilla JavaScript with ES6 modules and runs directly in the browser without any build process. The architecture follows a modular system-component pattern with clear separation of concerns.

Running the Game

The game requires no build step. To run it:

1. **Option 1:** Open `index.html` directly in a browser

2. **Option 2 (Recommended):** Serve locally to avoid CORS issues with modules:

```bash

python -m http.server 8000

```

Then visit `http://localhost:8000`

Game state persists in LocalStorage as `apoteose_save_v3`.

Architecture

Core Systems

1. **State Management** (`js/core/gameState.js`)

- Centralized state with controlled mutation via getters/setters

- All state access must use `getGameState()` and `updateGameState()`

- Save/load system automatically handles state persistence

2. **Game Loop** (`js/core/gameLoop.js`)

- 1-second logic tick for game systems

- 60fps rendering loop using requestAnimationFrame

- Clear separation between game logic updates and visual rendering

3. **Rendering System** (`js/rendering/`)

- Grid-based efficient rendering with minimal DOM manipulation

- CSS Grid with absolute positioning for entities

- Pure rendering logic with no game state mutations

4. **Game Systems** (`js/systems/`)

- Independent systems: combat, aperture, world generation, faction, quest

- Data-driven design with content defined in `js/core/constants.js`

5. **UI Management** (`js/ui/`)

- Event delegation and component management

- Centralized event handling in `js/ui/eventHandlers.js`

Key Game Systems

Development Guidelines

File Organization

Code Style

- `camelCase` for variables and functions

- `PascalCase` for classes

State Management Pattern

```javascript

// ✅ CORRECT: Use gameState module for all state access

import { getGameState, updateGameState } from './js/core/gameState.js';

const state = getGameState();

updateGameState({ player: { ...state.player, qi: newValue } });

// ❌ INCORRECT: Don't mutate state directly

state.player.qi = newValue;

```

Model-View Separation

Adding New Features

1. **New Game System**: Create in `js/systems/` following existing patterns

2. **New UI Component**: Add to `js/ui/` with event delegation

3. **New Content**: Define in `js/core/constants.js` (data-driven)

4. **New Rendering**: Add to `js/rendering/` with minimal DOM manipulation

Testing

No automated testing framework. Manual testing checklist:

Browser Requirements

Requires modern browser with ES6 module support:

Development Workflow

1. Make code changes in your editor

2. Refresh browser to see changes (no build step)

3. Use browser DevTools for debugging

4. Test save/load by checking LocalStorage

5. Verify across different cultivation realms and game states

Common Tasks

Adding a New Cultivation Realm

1. Update `REALMS` in `js/core/constants.js`

2. Add cultivation requirements and benefits

3. Update UI to display new realm information

4. Test progression and state persistence

Creating New Combat Runes

1. Add rune definitions to `js/core/constants.js`

2. Implement rune effects in `js/systems/combatSystem.js`

3. Update drag-and-drop UI if needed

4. Balance test against existing content

Implementing New Faction

1. Define faction in `js/core/constants.js`

2. Add relationship logic in `js/systems/factionSystem.js`

3. Create faction-specific quests

4. Test world generation with new faction

Important Notes