You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+6-3Lines changed: 6 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -364,16 +364,19 @@ snapshot for downstream tools.
364
364
365
365
## Running the CLI Shell
366
366
367
-
Interactive mode:
367
+
368
+
To launch the Echoes of Emergence Terminal UI demo, use the provided startup script:
368
369
369
370
```bash
370
-
uv run echoes-shell --world default
371
+
./start.sh
371
372
```
372
373
374
+
This script sets up the environment and launches the Terminal UI with recommended settings. For advanced options, you can pass arguments to the script (e.g., `./start.sh --rich` for enhanced ASCII views).
Copy file name to clipboardExpand all lines: docs/gengine/how_to_play_echoes.md
+41-26Lines changed: 41 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,64 +1,79 @@
1
1
# How to Play Echoes of Emergence
2
2
3
3
4
-
This guide explains how to run the current Echoes of Emergence prototype, interpret its outputs, and iterate on the simulation while new systems are under construction. It assumes you have cloned the repository and installed all runtime/dev dependencies via `uv sync --group dev`.
5
-
6
-
**New!** For large-scale AI playtesting and balance iteration, see [Section 13: AI Tournament & Balance Analysis](./ai_tournament_and_balance_analysis.md).
4
+
This guide explains how to run the current Echoes of Emergence prototype, interpret its outputs, and iterate on the simulation.
7
5
8
6
## 1. Launching the Shell
9
7
10
-
The CLI shell is the primary way to interact with the simulation today.
8
+
The CLI shell is the primary way to interact with the simulation. To launch the shell, use:
11
9
12
10
```bash
13
-
uv run echoes-shell --world default
11
+
./start.sh
14
12
```
15
13
16
-
-`--world` selects the authored content folder under `content/worlds/`.
14
+
-Use `--world <name>` to select the authored content folder under `content/worlds/`.
17
15
- Use `--snapshot path/to/save.json` to load a previously saved state.
18
-
- Use `--service-url http://localhost:8000` to target the FastAPI simulation
19
-
service instead of running in-process (world/snapshot loads must then be
20
-
triggered server-side).
21
-
- Use `--rich` to enable enhanced ASCII views with styled tables, color-coded
22
-
panels, and improved readability (requires Rich library).
16
+
- Use `--service-url http://localhost:8000` to target the FastAPI simulation service (world/snapshot loads must then be triggered server-side).
17
+
- Use `--rich` to enable enhanced ASCII views with styled tables, color-coded panels, and improved readability.
23
18
- For scripted runs (handy for CI or quick experiments):
24
19
25
20
```bash
26
-
uv run echoes-shell --world default --script "summary;run 5;map;exit"
21
+
./start.sh --script "summary;run 5;map;exit"
27
22
```
28
23
29
24
- For enhanced visualization during playtesting:
30
25
31
26
```bash
32
-
uv run echoes-shell --world default --rich
27
+
./start.sh --rich
33
28
```
34
29
35
-
On startup the shell prints a world summary and shows the prompt `(echoes)`.
36
-
Type commands listed in the next section to explore the world, advance time,
37
-
and persist state.
30
+
On startup the shell prints a world summary and shows the prompt `(echoes)`. Type commands listed in the next section to explore the world, advance time, and persist state.
38
31
39
32
### Remote Sessions via the Gateway Service
40
33
41
-
Phase 6 introduces a WebSocket gateway so remote testers can drive the CLI
42
-
without SSH access. Launch the gateway alongside the FastAPI simulation
43
-
service:
44
-
45
-
```bash
46
-
uv run echoes-gateway-service
47
-
```
48
34
49
-
Then connect with the bundled client (or any WebSocket tool that sends JSON
50
-
`{"command": "..."}` frames):
35
+
Phase 6 introduces a WebSocket gateway so remote testers can drive the CLI without SSH access. To launch the gateway and connect, use:
51
36
52
37
```bash
53
-
uv run echoes-gateway-shell --gateway-url ws://localhost:8100/ws --script "summary;run 3;exit"
This uses the startup script to connect to the gateway service, ensuring environment setup and consistent invocation. For advanced options, pass additional arguments to `start.sh` as needed.
42
+
56
43
Each connection provisions a dedicated `EchoesShell`, proxies commands to the
57
44
simulation service configured via `ECHOES_GATEWAY_SERVICE_URL`, and logs
58
45
focus/digest/history snapshots via the `gengine.echoes.gateway` logger whenever
59
46
`summary`, `focus`, `history`, or `director` runs. The client prints the same
60
47
ASCII output as the local shell and honors `--script` for CI-friendly runs.
61
48
49
+
50
+
## 1a. Launching the Terminal UI (Dashboard)
51
+
52
+
Echoes of Emergence now includes a rich Terminal UI dashboard for visual simulation interaction. This UI provides a status bar, city map, event feed, context panel, and command bar, all rendered in the terminal using the Rich library.
53
+
54
+
55
+
### Environment Setup
56
+
57
+
58
+
Before running the UI or any scripts, ensure your environment is set up. The `start.sh` script will handle environment setup and dependency installation automatically. Manual setup is only needed if you want to customize the environment or install additional packages.
59
+
60
+
---
61
+
62
+
63
+
To launch the demo Terminal UI:
64
+
65
+
```bash
66
+
./start.sh --ui
67
+
```
68
+
69
+
This will open a dashboard-style interface with real-time simulation data. The script uses sample data, but you can adapt it for live simulation integration.
70
+
71
+
For full details on the UI components, customization, and data formats, see the [Terminal UI README](../../src/gengine/echoes/cli/README.md).
72
+
73
+
> **Tip:** The classic CLI shell (`echoes-shell`) remains available for command-driven play and scripting. The Terminal UI is ideal for visual monitoring and interactive play.
Copy file name to clipboardExpand all lines: gamedev-agent-thoughts.txt
+100-7Lines changed: 100 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -304,8 +304,25 @@ Working on Issue #71 - Phase 11, Milestone 11.4, Task 11.4.1.
304
304
>>>>>>> copilot/optimize-strategy-parameters
305
305
306
306
## [tracker_agent] — 2025-12-07 04:01
307
-
- Reviewed recent commits and updated .pm/tracker.md: Task 11.4.1 (Strategy Parameter Optimization) marked complete, summary table and outstanding work sections updated. No blockers; only 11.6.1 remains as optional for Phase 11. Ran markdownlint; only line length warnings present.
308
-
307
+
- Created and documented task 12.1.1 (Terminal UI Core Implementation) in .pm/tracker.md. Updated summary table and milestone details. Lint check run; only line length warnings present.
- Created and documented task 12.1.1 (Terminal UI Core Implementation) in .pm/tracker.md. Updated summary table and milestone details. Lint check run; only line length warnings present.
311
328
@@ -348,8 +365,84 @@ Working on Issue #71 - Phase 11, Milestone 11.4, Task 11.4.1.
348
365
- Mocked external dependencies (subprocess, matplotlib, importlib) to ensure fast and reliable tests.
349
366
350
367
## [GitHub Copilot] — 2025-12-06 21:57
351
-
- Analyzed coverage report and identified `scripts/echoes_balance_studio.py` as having low coverage (26%).
352
-
- Created new tests for interactive modes and command handlers in `tests/scripts/test_echoes_balance_studio.py`.
353
-
- Mocked `input`, `print`, and workflow functions to test CLI logic without running simulations.
354
-
- Verified all tests pass.
355
-
- This should bring the overall coverage above 90%.
0 commit comments