Engine Developer Reference

Audience: Engine Developer Status: ✅ Ready

The exhaustive guide to the TelosMUD engine: every component, every algorithm, and how they fit together — with the why. This landing page is a concepts index that links each deep-dive below. Pages carry the relevant classes/algorithms/APIs and message-flow + sequence diagrams (mermaid) where they clarify behavior.

Concepts index

• Architecture Overview — services, process model, data flow
• Entity Component Model — the entity/component substrate, prototypes, flyweight-COW
• Zone Runtime & Actor Model — actor-per-zone single-writer runtime
• Instanced Zones — runtime-minted private zone copies, the anchor, isolation
• Command Parser & Targeting — parser, Diku targeting, act()
• Edge & Protocol — telos-gate, plain/TLS telnet, the Play gRPC stream, GMCP
• GMCP Reference — the base GMCP surface and how to extend it
• Persistence & Durability — schema, durability ladder, state_version
• Content Loading & Hot Reload — pack tree load, coordinated reload
• Abilities & Effects — the ability/effect framework
• Combat System — the combat loop and reproducibility
• Loot, Spawns & Crafting — loot resolver, spawns, recipes
• Accounts & Auth Internals — telos-account, assertions, trust tiers
• Orchestration & Directors — directors, scopes, placement
• Scoped Event Bus — the event substrate
• Cross-Shard Handoff — the handoff + exactly-once substrate
• Lua Sandbox Internals — the gopher-lua fork, sandbox, determinism
• Distributed Systems Model — consistency, single-writer, scaling
• RPC & Protobuf — the proto/buf surface and service RPCs

How to read this section

Start with the Architecture Overview for the service map, the process model, and the codebase layout, then follow the concepts index above in roughly that order — the substrate pages (entity/component, zone runtime, persistence) ground the domain pages (abilities, combat, loot) and the distribution pages (handoff, directors, the event bus, the distributed-systems model).

Two conventions run through every page:

• The source is the authority. Pages cite file:line so they stay re-verifiable against the code. Any in-repo *.md is treated as stale and ignored in favor of the Go source.
• Gaps are stated honestly. Where a surface is reserved, stubbed, or defined-but-unwired (e.g. skill lag is logged-only, zoneGen is never bumped, the persistent-world-object write side is unwired, region-director scripts are not yet deployed), the page says so rather than describing the aspiration as if it shipped.

---

Table of contents

• Architecture Overview
• Entity Component Model
• Zone Runtime & Actor Model
• Instanced Zones
• Command Parser & Targeting
• Edge & Protocol
• GMCP Reference
• Persistence & Durability
• Content Loading & Hot Reload
• Abilities & Effects
• Combat System
• Loot, Spawns & Crafting
• Accounts & Auth Internals
• Orchestration & Directors
• Scoped Event Bus
• Cross-Shard Handoff
• Lua Sandbox Internals
• Distributed Systems Model
• RPC & Protobuf