Change project organization
This commit is contained in:
197
core/generator-unlock-goals/TECH_SPEC.md
Normal file
197
core/generator-unlock-goals/TECH_SPEC.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Goal-Based Generator Unlocks - Technical Specification
|
||||
|
||||
## Document Status
|
||||
- Version: 1.0
|
||||
- Date: 2026-03-14
|
||||
- Scope: Unlock generators when goal thresholds are reached using one or more currencies.
|
||||
- Context sources: Amp threads `T-019ce93a-d410-70ad-aaa0-4697dafb0148` and `T-019c846f-2556-75bc-a1aa-fb26cd9ff52a`.
|
||||
|
||||
## Problem Statement
|
||||
The project already supports generator state (`unlocked` + `available`) in `GameState`, but unlock
|
||||
transitions are currently configured only by static defaults (`starts_unlocked`, `starts_available`).
|
||||
|
||||
We need progression goals so that a locked generator becomes usable only after the player reaches
|
||||
specific currency quantities. Goals must support one or more currencies per objective.
|
||||
|
||||
## Current Baseline
|
||||
1. Generator state is persisted in `GameState.generator_states` with keys `owned`, `purchased_count`,
|
||||
`unlocked`, `available`.
|
||||
2. `CurrencyGenerator` already exposes `is_unlocked`, `is_available`, and `is_available_to_player()`
|
||||
and uses them to gate click, auto-production, and purchases.
|
||||
3. `GeneratorContainer` listens to `GameState.generator_state_changed` and updates button enabled/disabled state.
|
||||
4. Save/load sanitization already handles generator state schema evolution safely.
|
||||
|
||||
This means the unlock feature can be added without changing core purchase/production mechanics.
|
||||
|
||||
## Goals And Non-Goals
|
||||
|
||||
## Goals
|
||||
|
||||
1. Define unlock goals that depend on one or multiple currency thresholds.
|
||||
2. Evaluate goals automatically when relevant currency values change.
|
||||
3. Unlock and make target generator available exactly once when a goal is met.
|
||||
4. Keep behavior deterministic after save/load.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
1. Adding quests, timed objectives, or repeatable missions.
|
||||
2. Adding reward types other than generator unlock/availability.
|
||||
3. Rebalancing generator economy values in this feature.
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
1. A goal targets exactly one generator (`target_generator_id`).
|
||||
2. A goal contains one or more currency requirements (`requirements[]`).
|
||||
3. Goal completion rule is logical AND across requirements (all thresholds must be met).
|
||||
4. Supported currencies must map to existing `GameState.CurrencyType` values (`gold`, `gems`).
|
||||
5. When completed, a goal sets both:
|
||||
- `GameState.set_generator_unlocked(target, true)`
|
||||
- `GameState.set_generator_available(target, true)`
|
||||
6. Goal completion must be idempotent (re-evaluating does not re-apply side effects).
|
||||
7. Goal checks must run:
|
||||
- at runtime on `currency_changed`
|
||||
- once at startup after loading save data
|
||||
8. Invalid goal entries (unknown currency, missing target id, malformed amount) must be ignored with a warning,
|
||||
not a crash.
|
||||
|
||||
## Data Model
|
||||
|
||||
## New Config File
|
||||
|
||||
Add a root JSON file:
|
||||
- `res://generator_unlock_goals.json`
|
||||
|
||||
Schema (v1):
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"goals": [
|
||||
{
|
||||
"id": "unlock_gems_generator",
|
||||
"target_generator_id": "Gems",
|
||||
"requirements": [
|
||||
{
|
||||
"currency": "gold",
|
||||
"amount": { "m": 1.0, "e": 3 }
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
1. `amount` uses existing `BigNumber` serialization (`m`, `e`) to avoid float precision/overflow issues.
|
||||
2. `id` must be unique and stable.
|
||||
3. `requirements` must contain at least one entry.
|
||||
|
||||
## Runtime Structures (GDScript)
|
||||
|
||||
Recommended internal structs/classes:
|
||||
|
||||
1. `UnlockGoalRequirement`
|
||||
- `currency: GameState.CurrencyType`
|
||||
- `amount: BigNumber`
|
||||
2. `UnlockGoal`
|
||||
- `id: StringName`
|
||||
- `target_generator_id: StringName`
|
||||
- `requirements: Array[UnlockGoalRequirement]`
|
||||
|
||||
No persistent `completed_goals` storage is required for v1 because completion is derived from generator unlock state.
|
||||
|
||||
## System Design
|
||||
|
||||
## New Runtime Component
|
||||
|
||||
Add a scene-level controller script (recommended name: `generator_unlock_system.gd`) responsible for:
|
||||
|
||||
1. Loading + validating `generator_unlock_goals.json`.
|
||||
2. Subscribing to currency change signals.
|
||||
3. Evaluating pending goals.
|
||||
4. Triggering generator unlock transitions.
|
||||
|
||||
Placement options:
|
||||
|
||||
1. Attach to the main gameplay scene root (preferred for prototype).
|
||||
2. Promote to autoload later if multiple gameplay scenes require shared unlock logic.
|
||||
|
||||
## Evaluation Flow
|
||||
|
||||
1. On `_ready()`:
|
||||
- load goals
|
||||
- connect to `GameState.currency_changed`
|
||||
- run `evaluate_all_goals()` once
|
||||
2. On currency change:
|
||||
- run `evaluate_all_goals()` (or an optimized subset)
|
||||
3. For each goal:
|
||||
- skip if target generator already unlocked and available
|
||||
- verify all requirement thresholds
|
||||
- if satisfied, unlock target generator and emit debug/info log
|
||||
|
||||
## Pseudocode
|
||||
|
||||
```gdscript
|
||||
func _evaluate_goal(goal: UnlockGoal) -> bool:
|
||||
if GameState.is_generator_unlocked(goal.target_generator_id) and GameState.is_generator_available(goal.target_generator_id):
|
||||
return false
|
||||
|
||||
for requirement in goal.requirements:
|
||||
var current: BigNumber = _get_currency_amount(requirement.currency)
|
||||
if current.is_less_than(requirement.amount):
|
||||
return false
|
||||
|
||||
GameState.set_generator_unlocked(goal.target_generator_id, true)
|
||||
GameState.set_generator_available(goal.target_generator_id, true)
|
||||
return true
|
||||
```
|
||||
|
||||
## UI/UX Behavior
|
||||
|
||||
1. Existing `GeneratorContainer` behavior already prevents interaction while locked.
|
||||
2. Optional v1.1 enhancement: show a compact "Unlock requirement" line for locked generators.
|
||||
3. On unlock, UI updates automatically through existing `generator_state_changed` signal path.
|
||||
|
||||
## Error Handling And Validation
|
||||
1. File open failure: log warning and disable unlock processing for that session.
|
||||
2. JSON parse failure or wrong root type: log warning and disable unlock processing.
|
||||
3. Invalid goal entries: skip only invalid entries, continue loading valid ones.
|
||||
4. Duplicate goal IDs: keep first entry, ignore duplicates with warning.
|
||||
5. Unknown `target_generator_id`: allow config load, but warn when evaluation cannot find/resolve state.
|
||||
|
||||
## Save/Load Behavior
|
||||
|
||||
1. Unlock result persists naturally via existing generator state persistence.
|
||||
2. On load, if a goal was completed previously, no duplicate effect occurs because state is already unlocked.
|
||||
3. If config thresholds are reduced in future versions, startup evaluation can unlock additional generators from existing balances.
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
1. v1 can safely evaluate all goals on every currency change (small goal count).
|
||||
2. If goals scale up, add currency-to-goal index to evaluate only affected goals.
|
||||
3. BigNumber comparisons are lightweight for this usage profile.
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
1. Add `generator_unlock_goals.json` with initial goals.
|
||||
2. Implement `generator_unlock_system.gd` loader/validator/evaluator.
|
||||
3. Attach unlock system to gameplay scene (`generator_museum.tscn` or current active scene).
|
||||
4. Configure at least one generator as initially locked (`starts_unlocked = false`, `starts_available = false`) in its `.tres` data.
|
||||
5. Add runtime logs for unlock events and invalid config entries.
|
||||
6. Run headless project parse smoke check.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. A locked generator becomes usable immediately after all configured currency thresholds are reached.
|
||||
2. Goals with multiple requirements unlock only when every requirement is satisfied.
|
||||
3. Unlock state persists after save/load and app restart.
|
||||
4. No crashes occur when goals file is missing or malformed.
|
||||
5. Existing generator purchase/production behavior is unchanged for already unlocked generators.
|
||||
|
||||
## Manual Test Cases
|
||||
|
||||
1. Start with a generator configured as locked; verify buy buttons are disabled.
|
||||
2. Grant required currency via debug controls; verify automatic unlock and enabled buttons.
|
||||
3. Save/restart; verify generator remains unlocked.
|
||||
4. Use a multi-currency goal; verify partial progress does not unlock.
|
||||
5. Corrupt one goal entry in JSON; verify warning is logged and other valid goals still work.
|
||||
Reference in New Issue
Block a user