jmp-games/idle
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update READMEs

Browse Source
This commit is contained in:
Michele Rossi
2026-04-15 18:40:59 +02:00
parent 5284911ace
commit 2bc81a73fd
6 changed files with 130 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
README.md
View File

@@ -22,20 +22,22 @@ A modular idle/incremental game prototype featuring a decoupled buff system, mul
| System | Location | Purpose | | System | Location | Purpose |
|--------|----------|---------| |--------|----------|---------|
| **BigNumber** | `core/big_number.gd` | Handles huge numbers (mantissa + exponent) for idle game math | | **BigNumber** | `core/big_number.gd` | Handles huge numbers (mantissa + exponent) for idle game math |
| **Currency** | `core/currency/`, `core/currency_database.gd` | Catalog system for all in-game currencies | | **Currency** | `core/currency/`, `core/currency_catalogue.gd` | Catalog system for all in-game currencies |
| **GameState** | `core/game_state.gd` | Central state authority (currencies, generators, buffs, persistence) | | **LevelGameState** | `core/level_game_state.gd` | Central state authority (currencies, generators, buffs, persistence, research) |
| **Generators** | `core/generator/` | Production mechanics (auto cycles, clicks, purchases) | | **Generators** | `core/generator/` | Production mechanics (auto cycles, clicks, purchases) |
| **Buffs** | `core/generator/generator_buff_data.gd` | Global multipliers with multi-target support | | **Buffs** | `core/generator/generator_buff_data.gd` | Global multipliers with multi-target support |
| **Goals** | `core/goals/` | Unlock conditions for generators and buffs | | **Goals** | `core/goals/` | Unlock conditions for generators and buffs |
| **Prestige** | `core/prestige/` | Reset-with-bonus mechanics | | **Prestige** | `core/prestige/` | Reset-with-bonus mechanics |
| **Research** | `core/research/` | XP-based progression with production multipliers |
### Autoload Singletons ### Key Nodes
| Autoload | Script | Description | | Node | Script | Description |
|----------|--------|-------------| |------|--------|-------------|
| `GameState` | `core/game_state.gd` | Central state management, save/load | | `LevelGameState` | `core/level_game_state.gd` | Central state management, save/load |
| `CurrencyDatabase` | `core/currency_database.gd` | Currency catalog discovery | | `CurrencyCatalogue` | `core/currency_catalogue.gd` | Currency catalog resource |
| `PrestigeManager` | `core/prestige/prestige_manager.gd` | Prestige system | | `PrestigeManager` | `core/prestige/prestige_manager.gd` | Prestige system |
| `ResearchXPTracker` | `core/research/research_xp_tracker.gd` | Research XP accumulation |
### Data Directory Structure ### Data Directory Structure
@@ -90,21 +92,29 @@ GameState.get_effective_multiplier(generator_id, kind) -> float
## Save Format ## Save Format
**Version 2 (current):** **Version 5 (current):**
```json ```json
{ {
"save_format_version": 2, "save_format_version": 5,
"currencies": { ... }, "currencies": {
"<currency_id>": {
"current": {"m": float, "e": int},
"total": {"m": float, "e": int},
"all_time": {"m": float, "e": int}
}
},
"generator_states": { ... }, "generator_states": { ... },
"buff_definitions": { ... },
"buff_levels": { "farm_flux": 5 }, "buff_levels": { "farm_flux": 5 },
"buff_unlocked": { "farm_flux": true }, "buff_unlocked": { "farm_flux": true },
"buff_active": { "farm_flux": true }, "buff_active": { "farm_flux": true },
"goals": { "completed": ["goal_id"] },
"research_xp": { "<research_id>": {"m": float, "e": int} },
"research_levels": { "<research_id>": int },
"last_save_time": 1234567890 "last_save_time": 1234567890
} }
``` ```
**Note**: Breaking change from v1 - old saves are incompatible. **Note**: Save format version 5 includes research XP as BigNumber serialization.
## Development ## Development
@@ -113,7 +123,7 @@ GameState.get_effective_multiplier(generator_id, kind) -> float
**New Currency:** **New Currency:**
1. Create `res://sandbox/currencies/<name>.tres` (Currency resource) 1. Create `res://sandbox/currencies/<name>.tres` (Currency resource)
2. Set `id`, `display_name`, `icon` 2. Set `id`, `display_name`, `icon`
3. Auto-discovered at runtime 3. Add to `CurrencyCatalogue` resource
**New Generator:** **New Generator:**
1. Create `res://sandbox/generators/<name>.tres` (CurrencyGeneratorData) 1. Create `res://sandbox/generators/<name>.tres` (CurrencyGeneratorData)
@@ -125,7 +135,13 @@ GameState.get_effective_multiplier(generator_id, kind) -> float
1. Create `res://sandbox/buffs/<name>.tres` (GeneratorBuffData) 1. Create `res://sandbox/buffs/<name>.tres` (GeneratorBuffData)
2. Set `target_ids` (e.g., `["farm", "forestry"]` or `["*"]`) 2. Set `target_ids` (e.g., `["farm", "forestry"]` or `["*"]`)
3. Configure effect, cost, unlock goal 3. Configure effect, cost, unlock goal
4. Auto-registered at runtime 4. Add to `BuffCatalogue` resource
**New Research:**
1. Create `res://sandbox/research/<name>.tres` (ResearchData)
2. Link to generator via `generator_id`
3. Configure XP and multiplier parameters
4. Add to `ResearchCatalogue` resource
### Testing ### Testing
@@ -140,24 +156,17 @@ GameState.get_effective_multiplier(generator_id, kind) -> float
## Known Issues / TODOs ## Known Issues / TODOs
- [ ] Manual save triggers not implemented (auto-save needed) - [ ] Manual save triggers not implemented (auto-save needed)
- [ ] `CurrencyTile` references `GameState.GOLD_CURRENCY_ID` (constant missing)
- [ ] `GeneratorPanel` has missing `mouse_entered`/`mouse_exited` handlers - [ ] `GeneratorPanel` has missing `mouse_entered`/`mouse_exited` handlers
- [ ] Some buffs configured locked with no unlock path - [ ] Some buffs configured locked with no unlock path
- [ ] No automated test suite - [ ] No automated test suite
## Refactoring Status ## Current Status
See `REFACTORING.md` for: Research system fully implemented with:
- Complete refactoring plan (8 phases) - XP-based progression tied to production
- Implementation timeline (15-23 hours estimated) - Auto-leveling with BigNumber support
- Testing checklist - Buff multipliers for XP gain
- Rollback procedures - Save format version 5 with research persistence
### Completed Phases
- Phase 1: GeneratorBuffData with target_ids support
### Pending Phases
- Phase 2-8: GameState extension, save format update, data migration
## Technical Details ## Technical Details

42
core/README.md
View File

@@ -5,42 +5,45 @@
The `core/` directory contains the fundamental systems for the idle game. It provides: The `core/` directory contains the fundamental systems for the idle game. It provides:
- **Numeric Foundation**: `BigNumber` for handling huge idle game values - **Numeric Foundation**: `BigNumber` for handling huge idle game values
- **Game State Management**: `GameState` autoload for all persistent state - **Game State Management**: `LevelGameState` for all persistent state
- **Currency System**: Database and tracking for multiple currency types - **Currency System**: `CurrencyCatalogue` and tracking for multiple currency types
- **Generator System**: Automated resource production with scaling costs - **Generator System**: Automated resource production with scaling costs
- **Buff System**: Upgrades that modify generator behavior - **Buff System**: Upgrades that modify generator behavior
- **Goal System**: Achievement tracking and unlock triggers - **Goal System**: Achievement tracking and unlock triggers
- **Prestige System**: Rebirth mechanics with permanent multipliers - **Prestige System**: Rebirth mechanics with permanent multipliers
- **Research System**: XP-based progression with production multipliers
## Architecture ## Architecture
``` ```
core/ core/
├── big_number.gd # Core numeric API ├── big_number.gd # Core numeric API
├── game_state.gd # Main state management autoload ├── level_game_state.gd # Main state management (Node)
├── buff_database.gd # Buff registration system ├── currency/ # Currency data structures + CurrencyCatalogue
├── currency_database.gd # Currency registration system ├── currency_catalogue.gd # Currency catalogue resource
├── currency/ # Currency data structures ├── buff_catalogue.gd # Buff catalogue resource
├── goal_catalogue.gd # Goal catalogue resource
├── generator/ # Generator logic and data ├── generator/ # Generator logic and data
├── goals/ # Goal/achievement system ├── goals/ # Goal/achievement system
└── prestige/ # Prestige/rebirth system ├── prestige/ # Prestige/rebirth system
└── research/ # Research XP and progression
``` ```
## Data Flow ## Data Flow
1. **Game Start**: `GameState._ready()` initializes currencies, loads save 1. **Game Start**: `LevelGameState._ready()` initializes currencies, loads save
2. **Player Action**: Generator bought → `GameState` updated → signals emitted 2. **Player Action**: Generator bought → `LevelGameState` updated → signals emitted
3. **UI Reaction**: Listeners respond to signals → update display 3. **UI Reaction**: Listeners respond to signals → update display
4. **Goal Check**: Currency changed → goals evaluated → buffs unlocked 4. **Goal Check**: Currency changed → goals evaluated → buffs unlocked
5. **Save**: `GameState.save_game()` → JSON to `user://idle_save.json` 5. **Save**: `LevelGameState.save_game()` → JSON to `user://level_save.json`
## Save Format ## Save Format
**Version**: 3 **Version**: 5
```json ```json
{ {
"save_format_version": 3, "save_format_version": 5,
"currencies": { "currencies": {
"<currency_id>": { "<currency_id>": {
"current": {"m": float, "e": int}, "current": {"m": float, "e": int},
@@ -68,6 +71,12 @@ core/
"goals": { "goals": {
"completed": ["<goal_id>", ...] "completed": ["<goal_id>", ...]
}, },
"research_xp": {
"<research_id>": {"m": float, "e": int}
},
"research_levels": {
"<research_id>": int
},
"last_save_time": unix_timestamp "last_save_time": unix_timestamp
} }
``` ```
@@ -97,7 +106,7 @@ var restored = BigNumber.deserialize(dict)
### Adding a New Currency ### Adding a New Currency
1. Create `res://sandbox/currencies/<name>.tres` extending `Currency` 1. Create `res://sandbox/currencies/<name>.tres` extending `Currency`
2. Set `id`, `display_name`, and `icon` 2. Set `id`, `display_name`, and `icon`
3. Auto-discovered by `CurrencyDatabase` 3. Add to `CurrencyCatalogue` resource assigned to `LevelGameState`
### Adding a New Generator ### Adding a New Generator
1. Create `res://sandbox/generators/<name>.tres` extending `CurrencyGeneratorData` 1. Create `res://sandbox/generators/<name>.tres` extending `CurrencyGeneratorData`
@@ -107,7 +116,12 @@ var restored = BigNumber.deserialize(dict)
### Adding a New Buff ### Adding a New Buff
1. Create `res://sandbox/buffs/<name>.tres` extending `GeneratorBuffData` 1. Create `res://sandbox/buffs/<name>.tres` extending `GeneratorBuffData`
2. Set `target_ids`, `kind`, `effect_increment`, and `cost` 2. Set `target_ids`, `kind`, `effect_increment`, and `cost`
3. Auto-discovered by `BuffDatabase` 3. Add to `BuffCatalogue` resource assigned to `LevelGameState`
### Adding New Research
1. Create `res://sandbox/research/<name>.tres` extending `ResearchData`
2. Link to a generator via `generator_id`
3. Add to `ResearchCatalogue` resource assigned to `LevelGameState`
## See Also ## See Also

63
core/currency/README.md
View File

@@ -41,21 +41,17 @@ icon = ExtResource("uid://...")
### Accessing Currencies ### Accessing Currencies
Currencies are defined in a `CurrencyCatalogue` resource that holds an array of `Currency` resources.
```gdscript ```gdscript
# Get all known currencies # Get all known currency IDs from the catalogue
var currencies: Array[Currency] = CurrencyDatabase.get_known_currencies() var ids: Array[StringName] = currency_catalogue.get_all_ids()
# Get currency by ID # Get currency resource by ID
var gold: Currency = CurrencyDatabase.get_currency_resource(&"gold") var gold: Currency = currency_catalogue.get_currency_by_id(&"gold")
# Check if currency exists
var is_valid: bool = CurrencyDatabase.is_known_currency_id(&"gems")
# Get display name
var name: String = CurrencyDatabase.get_currency_name(&"gold")
``` ```
## Integration with GameState ## Integration with LevelGameState
Currencies are tracked in three ways: Currencies are tracked in three ways:
1. **current**: Current balance (resets on prestige) 1. **current**: Current balance (resets on prestige)
@@ -64,21 +60,52 @@ Currencies are tracked in three ways:
```gdscript ```gdscript
# Add currency # Add currency
GameState.add_currency(gold_resource, BigNumber.new(100.0, 0)) level_game_state.add_currency(gold_resource, BigNumber.new(100.0, 0))
# Add by ID
level_game_state.add_currency_by_id(&"gold", BigNumber.new(100.0, 0))
# Get balance # Get balance
var balance: BigNumber = GameState.get_currency_amount_by_id(&"gold") var balance: BigNumber = level_game_state.get_currency_amount_by_id(&"gold")
# Spend currency (returns false if insufficient) # Spend currency (returns false if insufficient)
var success: bool = GameState.spend_currency_by_id(&"gold", BigNumber.new(50.0, 0)) var success: bool = level_game_state.spend_currency_by_id(&"gold", BigNumber.new(50.0, 0))
# Check if currency exists
var is_valid: bool = level_game_state.is_known_currency_id(&"gems")
# Get currency resource
var gold: Currency = level_game_state.get_currency_resource(&"gold")
# Get display name
var name: String = level_game_state.get_currency_name(&"gold")
``` ```
## Auto-Discovery ## CurrencyCatalogue Class
`CurrencyDatabase` automatically scans `res://sandbox/currencies/` for `.tres` and `.res` files on startup. ```gdscript
class_name CurrencyCatalogue
extends Resource
@export var currencies: Array[Currency] = []
func get_currency_by_id(id: StringName) -> Currency
func get_all_ids() -> Array[StringName]
```
The `CurrencyCatalogue` is a resource that holds all defined currencies and is assigned to `LevelGameState` via the `currency_catalogue` export variable.
## Signals
`LevelGameState` emits `currency_changed(currency_id: StringName, new_amount: BigNumber)` whenever a currency balance changes.
## See Also ## See Also
- `core/game_state.gd` - Currency state management - `core/level_game_state.gd` - Currency state management
- `core/big_number.gd` - Large number handling - `core/big_number.gd` - Large number handling
- `generator/currency_generator_data.gd` - Generator purchase currency - `core/currency/currency_catalogue.gd` - Currency catalogue resource
- `core/generator/currency_generator_data.gd` - Generator purchase currency
</content>
<parameter=filePath>
/home/mikymod/work/jmp/idle/core/currency/README.md

17
core/generator/README.md
View File

@@ -190,14 +190,14 @@ UI component showing generator information.
## Goal-Based Unlock ## Goal-Based Unlock
Generators with `unlock_goal` automatically listen to `GameState.goal_completed` signal: Generators with `unlock_goal` automatically listen to `LevelGameState.goal_completed` signal:
- When goal completes, generator unlocks automatically - When goal completes, generator unlocks automatically
- Goal's `unlock_behavior` (AUTOMATIC/MANUAL) controls when goal completes - Goal's `unlock_behavior` (AUTOMATIC/MANUAL) controls when goal completes
- Manual goals require player to click "Unlock" button first - Manual goals require player to click "Unlock" button first
```gdscript ```gdscript
# In CurrencyGenerator._ready(): # In CurrencyGenerator._ready():
GameState.goal_completed.connect(_on_goal_completed) level_game_state.goal_completed.connect(_on_goal_completed)
func _on_goal_completed(goal_id: StringName) -> void: func _on_goal_completed(goal_id: StringName) -> void:
if data.has_unlock_goal() and data.get_unlock_goal_id() == goal_id: if data.has_unlock_goal() and data.get_unlock_goal_id() == goal_id:
@@ -211,14 +211,15 @@ Generators automatically apply prestige multipliers:
effective_multiplier = run_multiplier * buff_multiplier * prestige_multiplier effective_multiplier = run_multiplier * buff_multiplier * prestige_multiplier
``` ```
On prestige: On prestige via `LevelGameState.reset_for_prestige()`:
1. `reset_runtime_state_for_prestige()` called 1. Current currencies reset to 0
2. `cycle_progress_seconds` reset 2. `cycle_progress_seconds` reset
3. Buff levels reset to 0 3. Buff levels reset to 0
4. Unlocks re-evaluated from goals 4. Goal completion state cleared and re-initialized
5. Research XP and levels reset to 0
## See Also ## See Also
- `core/game_state.gd` - Generator state storage - `core/level_game_state.gd` - Generator state storage
- `goals/goal_data.gd` - Unlock conditions - `core/goals/goal_data.gd` - Unlock conditions
- `prestige/prestige_manager.gd` - Multiplier application - `core/prestige/prestige_manager.gd` - Multiplier application

20
core/goals/README.md
View File

@@ -43,7 +43,7 @@ func is_valid() -> bool # Has valid id and requirements
func get_requirements() -> Array[GoalRequirementData] # Access requirements func get_requirements() -> Array[GoalRequirementData] # Access requirements
``` ```
**Note:** State-dependent methods (`is_met()`, `get_progress()`, `get_summary_text()`) have been moved to `LevelGameState` for proper decoupling. **Note:** State-dependent methods (`is_goal_met()`, `get_goal_progress()`, `get_goal_requirement_summary()`) are implemented in `LevelGameState` for proper decoupling.
## GoalRequirementData ## GoalRequirementData
@@ -68,7 +68,7 @@ func get_amount() -> BigNumber # Required amount
func has_valid_amount() -> bool # Amount is non-negative func has_valid_amount() -> bool # Amount is non-negative
``` ```
**Note:** State-dependent methods (`is_met()`, `get_progress()`, `get_summary_text()`) have been moved to `LevelGameState` for proper decoupling. **Note:** State-dependent methods (`is_met()`, `get_progress()`, `get_summary_text()`) are implemented in `LevelGameState` for proper decoupling.
### Progress Calculation ### Progress Calculation
@@ -93,7 +93,7 @@ This means reaching 50% progress on a 1e100 goal requires ~1e50 currency.
```gdscript ```gdscript
func _on_currency_changed(currency_id, new_amount): func _on_currency_changed(currency_id, new_amount):
game_state.evaluate_all_goals() evaluate_all_goals()
``` ```
### Completion Flow ### Completion Flow
@@ -167,8 +167,8 @@ signal goal_progress_changed(goal_id: StringName, progress: float)
## Integration Points ## Integration Points
### With GameState ### With LevelGameState
- Goals auto-discovered from `res://sandbox/goals/` - Goals registered from `GoalCatalogue` assigned to `LevelGameState`
- Completion state saved to JSON - Completion state saved to JSON
- Buff unlock goals checked automatically - Buff unlock goals checked automatically
@@ -178,15 +178,15 @@ signal goal_progress_changed(goal_id: StringName, progress: float)
@export var unlock_goal: GoalData @export var unlock_goal: GoalData
# When goal completes, buff auto-unlocks: # When goal completes, buff auto-unlocks:
GameState._try_unlock_buff_from_goal(buff) level_game_state._try_unlock_buff_from_goal(buff)
``` ```
### With Prestige ### With Prestige
- Goal completion state persists through prestige - Goal completion state persists through prestige
- Reset via `GameState.reset_for_prestige()` - Reset via `LevelGameState.reset_for_prestige()`
## See Also ## See Also
- `core/game_state.gd` - Goal state management - `core/level_game_state.gd` - Goal state management
- `generator/currency_generator_data.gd` - Generator unlock goals - `core/generator/currency_generator_data.gd` - Generator unlock goals
- `generator/generator_buff_data.gd` - Buff unlock goals - `core/generator/generator_buff_data.gd` - Buff unlock goals

4
core/prestige/README.md
View File

@@ -292,6 +292,6 @@ multiplier_per_prestige = 0.05
## See Also ## See Also
- `core/game_state.gd` - State persistence - `core/level_game_state.gd` - State persistence
- `generator/currency_generator.gd` - Multiplier application - `core/generator/currency_generator.gd` - Multiplier application
- `core/big_number.gd` - Large number math - `core/big_number.gd` - Large number math