Documentation Map
This document explains the reading order, authority precedence, and current-state conventions of the Shield documentation. When documents disagree, judge by the precedence on this page.
Document Status
| Status | Meaning |
|---|---|
| Authoritative contract | Stable boundaries that both users and implementations must follow. Code, tests, and examples should converge toward these documents. |
| Runtime semantics | Refined rules for a specific runtime subsystem. If it conflicts with the overview, the overview wins; if it conflicts with an example, the semantics document wins. |
| Reference | Operational explanations such as plugins, deployment, development, and ops. It should reflect the current implementation and does not define cross-module architecture principles. |
| Draft/archive | Design directions, business patterns, or future toolchains. Must not be treated as currently implemented runtime capability. |
Authority Precedence
- Architecture Overview: module boundaries, dependency direction, core non-goals, and extension principles.
- Lua API Contract, Runtime Config Semantics, Error Code Reference: user-visible APIs, configuration, and errors.
- Plugin System v1, Plugin Reference: plugin packages, instances, bindings, ABI, and official plugins.
- Each
runtime-*.md: semantics of subsystems such as services, messages, timers, the Lua VM, network, data, logging, bootstrap, and security. - Roadmap and Decision Log: current phase, closed decisions, and upcoming scope.
Recommended Reading Paths
New users read first:
- Quick Start
- Lua API Contract
- Runtime Config Semantics
- Plugin Reference
Framework developers read first:
- Architecture Overview
- Core Design Principles
- Runtime Semantics Decisions
- Development Guide
Plugin authors read first:
- Plugin System v1
- Plugin Reference
- Protocol Codec Plugins (only protocol codec provider authors need this)
- the official plugin reference page for the target interface header
Ops and deployment read first:
- Deployment
- Runtime Config Semantics
- Runtime Log Semantics
- Ops Semantics
- Lua Diagnostics Console Design
Current Conventions
Shield's current stance is single-node-first, Lua-first, plugin-based backend capabilities. The core runtime and Plugin System v1 are on the current implementation path; official optional modules such as shield_cluster, shield_global, shield_player, shield_server, and shield_ops proceed per the roadmap.
The old DI/IoC, annotations, conditions, events, middleware chain, old plugin v0, and the old discovery/metrics/health core integrations are no longer compatibility targets. If related historical documents still carry the old stance, this page, the Architecture Overview, and the Roadmap prevail.
Document Sections
| Section | Purpose |
|---|---|
| Getting started & status | Quick start, roadmap, FAQ, deployment, and development entries. |
| Authoritative contracts | Overview, Lua API, configuration, error codes, plugin system, and test matrix. |
| Core runtime | Services, messages, timers, Lua VM, network, data, logging, bootstrap, security, and gateway. |
| Plugin reference | Official plugins and third-party plugin development guidance. |
| Official optional modules | Extension semantics outside core such as cluster/global/player/server/ops, including the cluster implementation plan (with landed implementation records). |
| Engineering reference | Directory structure, CMake, CAF mapping, performance, best practices, and tutorials, including the engine SDK design (reviewed and approved). |
| Drafts & archive | Future directions or business-pattern references such as the schema toolchain, xmldef toolchain, xmldef descriptor/compiler/runtime specs, Unity generator spec, base-component/runtime adaptation boundaries, entity schemas, persistence and rollback. |
The suggested reading order for the current xmldef special-topic drafts:
- Xmldef Toolchain Design
- Xmldef Descriptor Spec
- Xmldef Phase 1 Implementation Plan
- Xmldef Compiler / Runtime MVP
- Xmldef Unity Generator Spec
For protocol layering terminology, the ProtocolProfile model, and the current support matrix, Protocol Routing Design is the special-topic entry. For the protocol codec plugin ABI, the default built-in boundary, and the protobuf-first landing scope, see Protocol Codec Plugins.
For DB usage discipline see DB Usage Discipline (after the async entry points landed, rules 1/2 are downgraded to recommendations; 3–6 remain hard); for the coroutine-resume async entry design and milestone status, DB Async Entry Points is the special-topic entry (implemented, M1–M4).
For client-facing TLS (the network.tls configuration surface, handshake/timeout semantics, certificate loading and hot-reload tradeoffs), TLS Design is the special-topic entry (v1 implemented); for runtime usage see the TLS section of Network Runtime Semantics.
For crash capture (Crashpad selection, handler initialization point, dump writing, symbol separation, upload placeholder off by default), Crash Reporting is the special-topic entry.
For later discussions of Lua primitives, cosocket-style outbound I/O, CAF adapter reuse boundaries, and the negative conclusion on auth-first, see the later draft Base Components and Runtime Adaptation Boundaries.