Skip to content

Commit fa87911

Browse files
CopilotSorraTheOrc
andcommitted
feat: Add Designer Feedback Loop and Tooling (Issue #70, Task 11.6.1)
- Add echoes-balance-studio CLI tool with 7 guided workflows - Implement config overlay system for testing tuning changes - Create interactive HTML report viewer with filtering/sorting - Add designer-focused documentation and case studies - Include 28 tests covering CLI, overlays, and reports Co-authored-by: SorraTheOrc <250240+SorraTheOrc@users.noreply.github.com>
1 parent 5aa9283 commit fa87911

File tree

7 files changed

+2564
-3
lines changed

7 files changed

+2564
-3
lines changed
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Example Tuning Overlay for Echoes of Emergence
2+
# ================================================
3+
#
4+
# This file demonstrates how to create configuration overlays for balance testing.
5+
# Overlays merge with the base simulation.yml, allowing you to test parameter
6+
# changes without modifying the base configuration.
7+
#
8+
# Usage:
9+
# echoes-balance-studio test-tuning --overlay content/config/overlays/example_tuning.yml
10+
#
11+
# Structure:
12+
# Only include the settings you want to change. Missing settings will use
13+
# base configuration values. Nested sections are deep-merged.
14+
15+
# Metadata (optional) - helps document what this overlay is testing
16+
_meta:
17+
name: "Example Tuning Overlay"
18+
description: "Demonstrates adjusting economy and environment parameters"
19+
author: "Balance Team"
20+
created: "2025-12-05"
21+
hypothesis: "Increasing regen_scale should improve stability without making the game too easy"
22+
23+
# Economy adjustments
24+
# Hypothesis: Slightly faster resource regeneration helps new players
25+
# without trivializing resource management
26+
economy:
27+
# Increase base regeneration by 25% (0.8 -> 1.0)
28+
regen_scale: 1.0
29+
# Slightly reduce the threshold for shortages to trigger earlier warnings
30+
shortage_threshold: 0.25
31+
# Allow prices to fluctuate more for interesting market dynamics
32+
price_max_boost: 0.6
33+
34+
# Environment adjustments
35+
# Hypothesis: Softer scarcity pressure gives players more recovery time
36+
environment:
37+
# Reduce how much scarcity affects unrest
38+
scarcity_unrest_weight: 0.00003
39+
# Allow biodiversity to recover faster
40+
biodiversity_recovery_rate: 0.05
41+
42+
# Director adjustments (optional)
43+
# Hypothesis: Longer quiet periods between story seeds reduces overwhelm
44+
# director:
45+
# global_quiet_ticks: 6
46+
# seed_quiet_ticks: 8

docs/gengine/ai_tournament_and_balance_analysis.md

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -251,9 +251,32 @@ A nightly CI workflow automatically runs tournaments and batch sweeps, archiving
251251
- Use `--verbose` during development to monitor sweep progress.
252252
- Use reproducible seeds for regression testing.
253253

254+
## Designer Feedback Loop and Tooling
255+
256+
For designer-friendly workflows that make balance iteration accessible without deep engineering knowledge, see the [Designer Balance Guide](./designer_balance_guide.md). This guide covers:
257+
258+
- Running exploratory parameter sweeps with `echoes-balance-studio`
259+
- Creating and testing config overlays
260+
- Diagnosing dominant strategies
261+
- Iterating on action costs and narrative pacing
262+
- Example workflows with case studies
263+
264+
Quick start:
265+
```bash
266+
# Run the balance studio
267+
uv run echoes-balance-studio sweep --strategies balanced aggressive --ticks 50
268+
269+
# Test a tuning change
270+
uv run echoes-balance-studio test-tuning --overlay content/config/overlays/example_tuning.yml
271+
272+
# View historical reports
273+
uv run echoes-balance-studio history --days 30
274+
```
275+
254276
## See Also
277+
- [Designer Balance Guide](./designer_balance_guide.md) - Designer-focused balance workflows
255278
- [How to Play Echoes](./how_to_play_echoes.md)
256279
- [Implementation Plan](../simul/emergent_story_game_implementation_plan.md)
257280
- [README](../../README.md)
258-
- [Testing Guide](./testing_guide.md)
259-
- [Content Designer Workflow](./content_designer_workflow.md)
281+
- [Testing Guide](./testing_guide.md)
282+
- [Content Designer Workflow](./content_designer_workflow.md)

0 commit comments

Comments
 (0)