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
Revise README for clarity and updated project details
Refactor README to improve clarity and structure, including updates to sections on Echo's functionality, advantages, and project status.
Signed-off-by: James Ross <[email protected]>
> _Echo is a recursive metagraph (RMG) simulation engine that treats _everything_–code, data, and time itself—as one big living graph.
19
+
> It’s built so every change can branch, merge, and replay perfectly.
18
20
19
-
> _Echo is a recursive metagraph (RMG) simulation engine that executes and rewrites typed graphs deterministically across branching timelines and merges them through confluence._
**Echo is an ambitious, mind-bending, radically different computational model for game engines and other interactive simulations.** The RMG is a powerful mathematical tool that brings the full weight of textbook category theory to interactive computational experiences.
24
26
25
27
Most game engines are object-oriented state machines. Unity, Unreal, Godot all maintain mutable object hierarchies that update every frame. Echo says: "No, everything is a graph, and the engine rewrites that graph deterministically using typed transformation rules."
26
28
27
-
## Snapshot Hashes
28
-
29
-
Echo records two hashes during a commit:
30
-
-`state_root`: deterministic hash of the reachable graph state under the current root.
31
-
-`commit hash` (commit_id): hash of a canonical header including `state_root`, parents, and deterministic digests for plan/decisions/rewrites.
32
-
33
-
See `docs/spec-merkle-commit.md` for the precise encoding and invariants.
34
-
35
29
Echo is fundamentally **built different**.
36
30
37
31
RMG provides atomic, in-place edits of recursive meta-graphs with deterministic local scheduling and snapshot isolation.
38
32
39
33
It’s the core of the Echo engine: runtime, assets, networking, and tools all operate on the same living graph of graphs.
40
34
41
-
## Developer: Running Benchmarks
42
-
43
-
- Command: `cargo bench -p rmg-benches`
44
-
- Purpose: Runs Criterion micro-benchmarks for the benches crate (`crates/rmg-benches`).
45
-
- Docs: see `crates/rmg-benches/benches/README.md` for details, tips, and report paths.
46
-
47
35
### Core Principles
48
36
49
37
| Principle | Description |
@@ -60,20 +48,13 @@ It’s the core of the Echo engine: runtime, assets, networking, and tools all o
60
48
61
49
---
62
50
63
-
##**tl;dr:**
51
+
### What's Echo?
64
52
65
-
> ECHO is a game engine that treats _everything_—code, data, and time itself—as one big living graph.
66
-
> It’s built so every change can branch, merge, and replay perfectly.
67
-
68
-
---
69
-
70
-
### The short pitch
71
-
72
-
ECHO runs on something called an **RMG (Recursive Meta-Graph)**. Think of it as a graph-based operating system. Everything in the engine (worlds, entities, physics, shaders, even the tools) lives inside that graph.
53
+
Echo runs on something called an **RMG (Recursive Meta-Graph)**. Think of it as a graph-based operating system. Everything in the engine (worlds, entities, physics, shaders, even the tools) lives inside that graph.
73
54
74
55
Echo doesn’t “update objects.” It _rewrites_ parts of the graph using a set of deterministic rules. That’s what “graph rewriting” means.
75
56
76
-
### Why this is cool
57
+
### Why Echo's Cool
77
58
78
59
-**Deterministic:** same inputs = same world every time.
79
60
-**Branching:** you can fork reality, change it, and merge it back without chaos.
@@ -90,7 +71,7 @@ You can pause time, fork a copy of reality, try out a new idea, and merge the ti
90
71
91
72
## Advantages
92
73
93
-
> *"Things are only impossible until they're not."* — Jean-Luc Picard
74
+
> _"Things are only impossible until they're not." — Jean-Luc Picard_
94
75
95
76
Can your game engine do...
96
77
@@ -105,7 +86,7 @@ Same input graph + same rules = same output, always. This is huge for:
105
86
106
87
### Branching Timelines
107
88
108
-
> “All we have to decide is what to do with the time that is given to us.” — _Gandalf, The Lord of the Rings_
89
+
> _“All we have to decide is what to do with the time that is given to us.” — Gandalf, The Lord of the Rings_
109
90
110
91
The Git metaphor is accurate. Fork reality, try something, merge back. This enables:
111
92
@@ -132,17 +113,69 @@ Rules are graphs. Systems are graphs. The whole runtime is a graph. This gives y
132
113
133
114
---
134
115
135
-
## Current Status
116
+
| Principle | Vision | Implementation |
117
+
| :--- | :--- | :--- |
118
+
|**Determinism (The "Replay")**| Same input graph + same rules = same output graph. Always. This is huge for networked multiplayer (no desync), perfect replays, and reproducible bug testing. | Achieved via an $O(n)$ deterministic scheduler. Pending graph rewrites are sorted using a stable radix sort (not a comparison-based sort) based on their scope, rule ID, and nonce. Combined with a deterministic math module (Vec3, Quat, PRNG), this ensures identical inputs always produce identical execution order and final state. |
119
+
|**Branching & Confluence (The "Time Travel")**| Fork reality, try something, and merge it back like a Git branch. Independent, non-conflicting changes converge to the same canonical state, guaranteed. | The engine's Timeline Tree (modeling Chronos, Kairos, and Aion) allows for branching realities. The engine's core transaction model (begin, apply, commit) and footprint-based independence checks (MWMR) allow for safe, parallel execution and deterministic, conflict-free merges. |
120
+
|**Snapshot Isolation (The "Commit")**| Snapshots are emitted from the live graph; append-only history is optional. This enables save/load, time-travel debugging, and collaborative editing. | Each commit produces two Merkle hashes derived from 256-bit BLAKE3: <ul><li><code>state_root</code>: deterministic hash of the reachable graph state under the current root.</li><li><code>commit hash</code> (commit_id): hash of a canonical header including <code>state_root</code>, parents, and deterministic digests for plan/decisions/rewrites.</li></ul> See <code>docs/spec-merkle-commit.md</code> for the precise encoding and invariants. |
121
+
|**Everything-is-a-Graph (The "Substrate")**| Nodes, edges, systems, assets, and even rewrite rules are all graphs. Graphs can contain subgraphs recursively. | The engine operates on typed, directed graphs. All identifiers (NodeId, TypeId, EdgeId) are domain-separated BLAKE3 hashes. Rewrite Rules are defined with a matcher, executor, and compute_footprint function, allowing the engine to deterministically transform the graph. |
122
+
|**Hexagonal Architecture (The "Ports")**| A core engine that is pure logic, completely decoupled from the outside world (rendering, input, networking). | Echo uses a Ports & Adapters design. The core engine (rmg-core) knows nothing of pixels, sockets, or key presses. It exposes narrow interfaces ("Ports") that external crates ("Adapters") implement. This allows swapping renderers (e.g., WebGPU, SDL) or physics engines without changing the core simulation logic. |
136
123
137
-
Echo is in **active development**. We're currently:
124
+
---
138
125
139
-
- ✅ Formal proofs of confluence (tick-level determinism proven)
140
-
- ✅ [C implementation](http://github.com/meta-graph/core) of independence checks and footprint calculus
Echo is a Rust workspace organized into a multi-crate setup. The core engine is pure, dependency-free Rust (#![no_std] capable) with I/O isolated to adapter crates.
0 commit comments