ECHO Content Graph

The .ECHO Content Graph is a runtime-neutral, portable semantic model of ECHO modules, addons, and the gameplay content they contain. It lets launchers, runtimes, review tools, and public documentation agree on what a module ships without depending on any single runtime implementation.

Why It Exists

• Launcher transparency: Players and support tools can see how many modules, nodes, edges, features, and Hytale export blockers are present in an installed pack.
• Runtime evidence: Native, NeoForge, and standalone runtimes can load the same graph as optional input for registry planning, AdapterCore bridges, and parity checks.
• Review gates: Module and addon entries in the Release Index must index a content-graph artifact, and new ECHO module releases publish content-graph-evidence.json as the canonical aggregate evidence artifact.

What a Release Contains

Every module release generates:

<module>-<version>-content-graph.json       # Release-Index sidecar
content-graph-evidence.json                 # aggregate release evidence
.echo/content-graph/
  content-graph.json                         # canonical graph
  content-graph.md                           # human summary
  features.json                              # derived feature list
  provenance.json                            # generation provenance
  unresolved-references.json                 # optional reference audit
  export-plans/neoforge.json
  export-plans/echo_native.json
  export-plans/echo_runtime_standalone.json
  export-plans/hytale.json

The .echo/content-graph/ tree is also embedded inside each runtime archive (.echo-addon, -neoforge.jar, -standalone.jar). Consumers that need summary cards should prefer content-graph-evidence.json when it is indexed, then fall back to per-module content-graph sidecars.

Schema Family

| Schema | Purpose | | --- | --- | | content-graph.schema.json | Top-level graph document | | content-graph-node.schema.json | Typed node envelope (block, item, recipe, mission, UI intent, etc.) | | content-graph-edge.schema.json | Typed relationship | | content-graph-export-plan.schema.json | Per-runtime export planning | | content-feature-list.schema.json | Human-facing feature list | | content-graph-evidence.schema.json | Release/workspace evidence summary |

Canonical schemas live in ECHO-SDK. See the SDK reference for full JSON examples, node/edge kinds, runtime hints, and export-plan semantics.

Consumers

• ECHO-Modules generates and validates graphs, then embeds them into module releases.
• ECHO-Release-Index enforces the content-graph artifact role for every module and addon entry and validates the content-graph-evidence role when present.
• ECHO-Native-Platform reads per-module graphs during dry-run planning and compares loaded counts against canonical release evidence when present.
• ECHO-Standalone-Runtime loads graphs from module roots via EchoContentGraphLoader and compares smoke counts against canonical release evidence when present.
• ECHO-Launcher extracts embedded graphs during native handoff and shows installed evidence metrics plus Hytale blockers in the Library pack detail drawer.
• Website and Mobile Studio prefer canonical release evidence counts from content-graph-evidence.json, with sidecar fallback for older releases.

Hytale Boundary

Hytale export statuses are planning evidence only. direct, adapter_required, fallback, and blocked do not mean Hytale runtime assets exist, and no UI should present those statuses as playable support until a Hytale adapter/codegen contract and separate runtime validation gate exist.

Quick Start

Generate graphs for every module:

node scripts/generate-content-graph.mjs --all --write

Validate them:

node scripts/validate-content-graph.mjs --strict --sdk-root ../ECHO-SDK

Run the standalone smoke harness:

./gradlew runStandaloneContentGraphLoadSmoke -PechoModulesRepoRoot=/path/to/ECHO-Modules