Engine Developer Reference

Engine Developer Reference

Audience: Engine Developer Status: ✍️ Draft

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
• Command Parser & Targeting — parser, Diku targeting, act()
• Edge & Protocol — telos-gate, telnet/TLS/SSH, the Play gRPC stream, MCCP/NAWS
• 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

Intended contents

• Orientation to the codebase layout: cmd/ binaries, internal/ packages, api/proto
• How to read the rest of this section; the engine-vs-content pillar as an architectural invariant
• Contribution/verification norms: cite file paths so docs stay re-verifiable against the code

---

Scaffold page — full content pending the wiki build-out.