Search is available after the production docs build.

Browse Docs
DocsDevelopersNetworking

Developers

Networking

Packets, server actions, sync, rate limiting, and debug expectations for ECHO systems.

Role

Networking connects player actions, server state, UI updates, and synchronized gameplay systems. ECHO networking should prioritize server authority, clear ownership, rate limiting, and debug-friendly behavior.

NetCore is the current networking backbone for first-party modules that declare custom packets. SDK docs also expose the public Native contract names EchoNetService, PacketDescriptor, and EchoPacket for addon authors targeting the Native API.

When To Use Networking

Use networking when a module needs to:

  • Send a player action from UI to server authority.
  • Synchronize mission, scan, map, or unlock state.
  • Notify a client that data changed.
  • Request a server-owned calculation.
  • Confirm that an interaction is allowed.

Do not use networking to bypass service contracts. A packet should usually call into the service that owns the behavior.

Descriptor Requirements

Declare NetCore and packet permissions in META-INF/echo.mod.json:

{
  "schema": "echo.mod.v1",
  "id": "my_networked_addon",
  "requires": ["echoadaptercore", "echocore", "echonetcore"],
  "consumes": ["echo.core", "echo.net"],
  "permissions": ["network.payloads"],
  "runtimeTargets": ["echo_native", "neoforge", "echo_runtime_standalone"]
}

If networking is optional, move echonetcore to optional and make every send path no-op when the service is unavailable.

Public SDK Shape

The Native API reference exposes this service family:

EchoNetService.registerPacketDescriptor(PacketDescriptor desc);
EchoNetService.sendToPlayer(ServerPlayer player, EchoPacket packet);
EchoNetService.broadcastToDimension(ResourceKey<Level> dim, EchoPacket packet);

Packet records should implement EchoPacket, carry a stable channel or packet ID, and keep payloads compact.

First-Party NetCore Shape

First-party NeoForge-compatible modules use NetCore helpers around packet registration, send, debug, and rate-limit behavior:

  • EchoNetPayloads.optional(event)
  • EchoNetPayloads.serverboundAction(...)
  • EchoNetSend
  • EchoNetClientActions
  • EchoRateLimiter
  • EchoNetDebug

The same rules apply in either API surface: descriptors are registered up front, serverbound packets are requests, handlers validate authority before mutating state, and debug events record accepted and dropped packets.

Packet And Action Checklist

Every networked action should document:

  • Packet or action ID.
  • Direction of travel.
  • Owning module.
  • Required permission or progression state.
  • Server authority rules.
  • Rate-limit policy.
  • Validation failures.
  • Debug log fields.
  • Compatibility or migration concerns.

Server Authority

Player-facing UI can request actions, but gameplay state should be owned by the authoritative side. A Terminal button, Lens scan, or HoloMap action must not blindly mutate world state.

Use this flow:

  1. Client emits a small action packet with stable IDs.
  2. Server handler checks player, target, permission, progression, and runtime support.
  3. Server calls the owning service contract.
  4. Service mutates DataCore or gameplay state.
  5. NetCore sends a compact sync packet back to affected clients.

Failure Codes

Use explicit failure states that diagnostics and UI can explain:

  • invalid-payload
  • missing-provider
  • not-unlocked
  • target-unloaded
  • rate-limited
  • unsupported-runtime
  • permission-denied

Avoid retries without a rate limit. Avoid logging sensitive payload data.

Sync Patterns

Prefer small, owned updates. For DataCore-backed state, synchronize keys or changed records instead of dumping entire world state into a UI packet.

A sync packet should identify:

  • Scope: player, world, team, route, mission, or module.
  • Owner ID.
  • Revision or version.
  • Changed keys or compact payload.
  • Whether the payload is a full snapshot or delta.

Terminal, Index, Lens, and HoloMap should receive the data they need, not every internal field a module stores.

Debugging

Networking code should make support easier. Useful logs include:

  • Packet or action ID.
  • Direction.
  • Player.
  • Target system.
  • Validation result.
  • Failure reason.
  • Runtime adapter.
  • Module version.

NetCore debug events should be easy to correlate with user reports and release QA. Keep debug packet handlers permissioned.

Common Mistakes

  • Trusting client UI state as proof that an action is allowed.
  • Sending large payloads when an ID and revision would work.
  • Mutating save data directly from packet code.
  • Retrying failed actions without a rate limit.
  • Hiding errors that should become launcher, support, or diagnostics signals.
  • Declaring network.payloads without documenting packet IDs.

Related Docs

Next Step

After defining the action, document the state it reads or writes in Data Storage. If it updates a player surface, connect that behavior through UI Integration.