From 66666defcb22cdc2093ae886b88fd3261a70fa24 Mon Sep 17 00:00:00 2001 From: Michele Rossi Date: Thu, 7 May 2026 23:00:51 +0200 Subject: [PATCH] Update AGENTS.md --- AGENTS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 48 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f4a619f..a7f7515 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,23 +5,61 @@ Godot 4.6 idle-game; code is GDScript + `.tscn` scenes. Use `GODOT_BIN` for your local editor binary (e.g. `godot`, `godot4`, or full path). Run project: `"$GODOT_BIN" --path .` Headless smoke/lint parse: `"$GODOT_BIN" --headless --path . --quit` -Script syntax check (single script): `"$GODOT_BIN" --headless --check-only --script res://big_number.gd` -Tests: no test framework is currently committed (`tests/` and `addons/gut` are absent). -Single-test command: N/A right now; if GUT is added, use `"$GODOT_BIN" --headless --path . -s res://addons/gut/gut_cmdln.gd -gtest=res://tests/.gd`. +Script syntax check (single script): `./scripts/check_syntax.sh ` (e.g. `./scripts/check_syntax.sh res://core/level_game_state.gd`) +Run single test: `./scripts/run_test.sh res://tests/.gd` +Run all tests: `./scripts/run_all.sh` +Tests are custom headless scripts in `tests/` using `LevelGameState` simulation (no GUT). ## Architecture And Structure -`project.godot` defines autoload singletons: `GameState` (runtime currency state + save/load) and `CurrencyGeneratorDatabase` (loads `generator_data.json`). -`big_number.gd` (`class_name BigNumber`) is the internal numeric API for huge-value math, comparisons, formatting, and serialization. -`big_number_museum.tscn` + `big_number_museum.gd` is the current main playable scene/prototype UI. -`currency_generator.gd`, `currency_label.gd`, and `big_number_progress_bar.gd` are UI/gameplay adapters that react to `GameState` signals. -Persistence is local JSON only: `user://idle_save.json`; there is no external DB/server/backend. + +### No Autoloads +There are **no autoload singletons**. All state lives in scene nodes. The project was fully decoupled from globals. + +### Main Scene +`run/main_scene` points to `docs/gyms/tiny_sword/tiny_sword.tscn` (uid `dadeowsvaywpp`). This is the canonical playable scene. `docs/museums/big_number_museum.tscn` is a secondary prototype/testing scene. + +### Core Systems (`core/`) +- **`core/big_number.gd`** — `class_name BigNumber`: numeric API for huge-value math, comparisons, formatting, and serialization (`{m: float, e: int}` scientific notation). +- **`core/level_game_state.gd`** — `class_name LevelGameState` (extends `Node`): the central runtime state node. Owns all currency balances, generator states, buff levels, goal completion, research XP, prestige buff unlocks, and save/load. Assigned catalogue resources via `@export`: + - `currency_catalogue` → `CurrencyCatalogue` (defines all currencies) + - `buff_catalogue` → `BuffCatalogue` (generator buffs) + - `goal_catalogue` → `GoalCatalogue` (achievement goals) + - `research_catalogue` → `ResearchCatalogue` (research tracks) + - `prestige_buff_catalogue` → `PrestigeBuffCatalogue` (permanent prestige upgrades) +- **`core/edge_scroll_camera.gd`** — camera with edge-scrolling and zoom. + +### Subsystems (`core//`) +Each subsystem has its own directory with a `README.md`: +- **`core/currency/`** — `Currency` resource, `CurrencyCatalogue` resource, `currency_panel.gd` UI. +- **`core/generator/`** — `CurrencyGenerator` (production node), `CurrencyGeneratorData` (balancing resource), `GeneratorBuffData` (upgrades), `ResearchBuffCalculator` (static utility), `generator_container.gd` UI. +- **`core/goals/`** — `GoalData` (achievement resource), `GoalRequirementData` (individual criteria), `current_goal_panel.gd` UI. +- **`core/prestige/`** — `PrestigeManager` (child node of `LevelGameState` managing resets + multipliers), `PrestigeConfig`, `PrestigeBuffNode` (DAG graph node), `PrestigeBuffCatalogue`, UI panels (`prestige_panel`, `prestige_progress_bar`, `prestige_buff_graph_panel` with tiles). +- **`core/research/`** — `ResearchData` resource (XP thresholds, production multipliers per level), `ResearchCatalogue`, `research_panel.gd` + `research_row.gd` UI. + +### Content Is Data-Driven (`docs/gyms/`) +All gameplay content (currencies, generators/buildings, buffs, goals, research, prestige config) is defined as `.tres` resource files under `docs/gyms/tiny_sword/` and composed in `tiny_sword.tscn`. No hardcoded JSON data files. + +### Root-Level UI Helpers +- `currency_label.gd`, `currency_tile.tscn` — reusable currency display components. +- `big_number_progress_bar.gd` / `.tscn` — progress bar for BigNumber values. +- `generator_buff_tile.gd` / `.tscn` — individual buff upgrade tile. +- `goals_debug_ui.gd` / `.tscn` — debug overlay for goal state. + +### Persistence +Local JSON only: `LevelGameState` saves to the path set in its `save_file_path` export (e.g. `user://tiny_sword_save.json`). No external DB/server/backend. Save format version is currently 8. + +### Testing +Custom headless test scripts in `tests/` that instantiate `LevelGameState` directly (no scene tree needed). Helper scripts in `scripts/`: +- `check_syntax.sh` — single-file Godot syntax check. +- `run_test.sh` — run a single test script headless. +- `run_all.sh` — run all tests. ## Code Style And Conventions Prefer typed GDScript (`var x: Type`, `func f() -> void`) and keep shared models/components as `class_name` scripts. Naming: `snake_case` for vars/functions/signals, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants. Follow existing Godot style: tabs/consistent indentation, early returns, and short functions grouped by purpose. When reading files/JSON, always guard `FileAccess.open(...)` and validate parsed types before indexing. -Use signals (already in `GameState`) for UI updates instead of polling or cross-node direct mutation. +Use signals (emitted by `LevelGameState`) for UI updates instead of polling or cross-node direct mutation. No Cursor/Claude/Windsurf/Cline/Goose/Copilot rule files were found in this repository, so this file is the canonical agent guidance. Avoid trivial one-line wrapper/helper functions that only forward or repack data. Inline the logic at the real call site unless the wrapper adds meaningful abstraction or is reused enough to justify it. -Resource type safety: Use the specific resource. Avoid as much as possible explicit `Resource` usage. +Resource type safety: Use the specific resource type. Avoid the bare `Resource` type. Prefer `Currency`, `CurrencyGeneratorData`, `GeneratorBuffData`, `GoalData`, `ResearchData`, `PrestigeBuffNode`, etc.