Imported from V1staz/GreedyCave3.0 (AGENTS.md). Install upstream with npx skills add V1staz/GreedyCave3.0. Copyright stays with the author.

AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

Project Overview

Dark pixel-art RPG "Greedy Cave 3.0" — an HCI course assignment (Tongji University). Core mechanic is a timeline-based deckbuilding auto-battler: the player arranges attack/defense segments on a looping timeline, then sends their hero into a procedurally generated dungeon tree where combat runs automatically.

The active development track is html/game.html (PixiJS 7.4). The prototype/ directory holds Python reference implementations of the battle logic. source/ is an asset library (pixel art, fonts, Unity prefabs).

Development workflow

There is no build step. Serve the project root with any HTTP server and open html/main_menu.html in a browser:

cd /home/v1staz/workspace/TH/GreedyCave3.0
python -m http.server 8000
# Open http://localhost:8000/html/main_menu.html

Assets are loaded from relative paths like ../source/Artwok/..., so the HTML files must be served from the project root. Opening them directly (file://) will break asset loading.

PixiJS 7.4.0 is loaded from CDN in the <script> tag — no npm install needed.

Architecture (HTML5 game — active development)

The entire game lives in a single file: html/game.html (~2100 lines). It is structured as a set of factory functions rather than modules:

• BattleEngine — Core simulation loop. Rewinds two independent timeline cycles per dt tick (60 FPS), checks trigger points, computes rock-paper-scissors damage (defense halves damage, attacking a unit in attack state deals +50%). Mirrors the logic in prototype/timeline_battle.py.
• Timeline Editor (buildTimeline) — Drag-and-drop segments on a track with snap-to-grid and magnetic edge snapping. Segments have start, duration, and triggerOffset (the precise moment inside the segment when the effect fires).
• Segment Inventory (buildPalette) — Scrollable palette of available ATK/DEF/R segments to drag onto the timeline.
• Map View (buildMapView, generateTree) — Procedural tree generator (depth 3–4, 2–4 branches per node). Rendered with fog of war: only current node and direct children are visible.
• DFS Auto-Exploration — When entering explore mode, runs depth-first search to visit all reachable nodes, then builds a route from current position to the door (random leaf node) via LCA pathfinding.

State machine:

edit → explore(battle/moving) → win → explore(next node) → ... → door → next floor
                                ↘ lose

Set state.mode to control interaction: in edit mode the timeline editor is interactive; in explore mode it's locked and the battle/movement engine runs.

UI layout: Three panels using PixiJS containers — left panel (timeline editor + palette), right panel (battle view with hero/enemy timelines), map panel (tree visualization on the far right).

UI language constraint: All game UI text must be in English (no Chinese characters).

Python prototypes (reference only)

python prototype/timeline_battle.py   # CLI simulation
python prototype/timeline_ui.py       # Pygame visualization (requires pygame)

The Python timeline_battle.py is the canonical reference for the damage formula and simulation loop. When debugging the HTML5 battle engine, compare against this file.

Unity project (not actively developed)

source/ contains a Unity UI toolkit project. C# scripts under source/Scripts/UI/ use the DarkPixelRPGUI.Scripts namespace with reusable components (tooltips, sliders, dropdowns). Open source/ as a Unity project to work with it.

Dev documentation

Write development docs in dev_md/<date>/ (e.g., dev_md/26.5.3/). These track milestones, prompts, and known bugs.

Known bugs

1. Exiting the dungeon restarts from the current floor instead of the first floor.
2. Many sprite assets from source/Artwok/ are unused in the game — buttons may be too small to accommodate them.