UI Integration

Role

ECHO UI integration lets modules contribute player-facing information without forking the whole interface.

The main integration surfaces today are Terminal, Index, Lens, and HoloMap. Public addon work should contribute data, service providers, or optional integrations to those surfaces instead of taking over presentation.

Descriptor Requirements

Declare the UI surface a module provides or consumes in META-INF/echo.mod.json:

{
  "schema": "echo.mod.v1",
  "id": "echoindex",
  "requires": ["echoadaptercore", "echocore", "echonetcore"],
  "optional": ["echoholomap", "echolens", "echomissioncore", "echoterminal", "echothemecore"],
  "provides": ["index.recipes", "index.inventory_overlay", "echoindex:inventory_overlay"],
  "permissions": ["index.recipes", "index.inventory_overlay", "ui.overlays", "inventory.overlay", "ui.screens"],
  "apiStability": "beta"
}

Use optional dependencies when the UI can disappear safely. Use required dependencies only when the feature cannot operate without that surface.

Design Rule

Do not make every module design its own unrelated UI. If a shared ECHO interface can carry the information, integrate with it.

Good UI integrations are:

• Concise.
• State-aware.
• Connected to real gameplay.
• Honest about locked or unknown information.
• Owned by the module that understands the data.
• Rendered by the ECHO surface that owns presentation.

Terminal

Use Terminal for missions, route state, intel, inbox entries, rewards, diagnostics, and addon dashboards.

Data-driven Terminal pages can be published as pack resources:

{
  "id": "echo_template_full_ashfall:ashfall_showcase_dashboard",
  "title": "Ashfall Field Dashboard",
  "summary": "Next step: open the active mission, read Index, scan wreckage, pin the low-risk field marker, then return before the weather warning peaks.",
  "nextSteps": [
    "Open Index: Ashfall Showcase Flow.",
    "Scan drop-pod wreckage with Lens.",
    "Pin HoloMap marker: First Field Objective.",
    "Track MissionCore: Ashfall Showcase Opening."
  ],
  "theme": "ashfall",
  "styleTokenSet": "ashfall_cyberglass"
}

The module owns the meaning. Terminal owns layout, navigation, and presentation.

Index

Use Index for recipes, item usage, archives, recovered records, technology descriptions, and progression knowledge.

Index entries should include unlock context and stable cross-links when possible:

{
  "id": "echo_template_full_ashfall:overview",
  "category": "echo_template_full_ashfall:starter",
  "title": "Full Ashfall Overview",
  "subtitle": "The official Ashfall pack profile with Ashfall theme, docs, metadata, and export checks.",
  "summary": "The official Ashfall profile starter for ECHO Launcher exports, preserving Ashfall as Official ECHO Pack #1 and keeping its content isolated from generic templates.",
  "tags": ["Official Pack", "template", "creator"]
}

Avoid dumping every hidden entry into Index at the start of a playthrough. Locked, rumored, and discovered states should be deliberate.

Lens

Use Lens for scan data on blocks, entities, machines, hazards, fluids, resources, and hidden clues.

Lens scan profiles can link to Index entries, missions, HoloMap markers, route links, and tutorial hints:

{
  "id": "echo_template_full_ashfall:ashfall_showcase_scans",
  "title": "Ashfall Opening Scans",
  "rows": [
    {
      "target": "drop_pod_terminal",
      "text": "Terminal wake signal detected. Index entry unlocked: Showcase Flow.",
      "indexEntry": "echo_template_full_ashfall:showcase_flow",
      "mission": "echo_template_full_ashfall:ashfall_showcase_flow",
      "holomapMarker": "echo_template_full_ashfall:drop_pod_terminal",
      "routeLink": "echo_template_full_ashfall:ashfall_depot_bridge"
    }
  ]
}

If the player has not unlocked enough context, return a limited result instead of leaking hidden progression.

HoloMap

Use HoloMap for markers, routes, hazards, relays, bases, missions, anomaly regions, and world overlays.

HoloMap layers should provide category and state metadata so filters remain useful:

{
  "id": "echo_template_full_ashfall:showcase_flow",
  "name": "Ashfall Showcase Flow",
  "description": "Opening route markers for the Ashfall official profile only.",
  "visibleByDefault": true,
  "markerStyle": "ashfall_cyberglass",
  "markers": [
    {
      "id": "echo_template_full_ashfall:drop_pod_terminal",
      "label": "Drop Pod Terminal",
      "kind": "terminal",
      "description": "First Terminal dashboard and Index handoff.",
      "icon": "ashfall_terminal",
      "riskLabel": "safe return point",
      "routeLink": "echo_template_full_ashfall:ashfall_depot_bridge",
      "missionId": "echo_template_full_ashfall:ashfall_showcase_flow",
      "indexEntry": "echo_template_full_ashfall:showcase_flow"
    }
  ]
}

HoloMap decides how markers render. The module describes what they mean and when they are visible.

Optional Service Integration

For code-driven integration, guard optional surfaces:

Optional<IndexService> index = EchoOptionalServices.index();
index.ifPresent(service -> service.registerProvider(myDocsProvider));

The matching module descriptor should list echoindex in optional and declare the consumed surface in consumes or permissions.

Integration Checklist

• The module uses the shared ECHO surface that best fits the information.
• The integration has a stable resource, provider, tab, or marker ID.
• Visibility respects progression and unlock state.
• The provider reads through services, not raw storage.
• UI mutation paths validate on the server through NetCore when gameplay state changes.
• The UI can explain locked, unknown, unavailable, and unsupported states.
• Related Index, Lens, Terminal, and HoloMap entries reference each other where useful.

Common Mistakes

• Building a custom screen for data that belongs in Terminal, Index, Lens, or HoloMap.
• Returning debug text directly to players.
• Revealing hidden progression through scanner or archive data.
• Making a UI provider mutate gameplay state without server validation.
• Duplicating the same information across surfaces without shared services.
• Declaring a UI permission without a matching resource, provider, or service path.

Related Docs

• Terminal
• Index
• Lens
• HoloMap
• Service Contracts
• Networking

Next Step

Choose one surface and implement the provider or resource shape first. If the integration triggers gameplay changes, define the server action in Networking. If it displays saved state, confirm ownership in Data Storage.