Documents in docs/ are organized by subdirectory by purpose and audience.
Design & Planning (docs/plan/)
- Plan docs are current-state docs during implementation. Do not link to them from permanent docs or source code.
- Create a plan document here before implementation starts. When extending an existing feature, update the original plan doc instead of creating a new one.
- PLAN DOCUMENT STRUCTURE:
- Write a concise plan description (< 500 words) as the first section to prevent context drift.
- Use staged status (
not started,in progress,complete) when work spans multiple stages. Keep status updated in a table immediately after the description. - HANDOFFS: After implementation starts, include clear handoff instructions in a "Current State Handoff" section after the staged status. Keep handoffs current whenever status changes.
- Document each stage with checklists of specific tasks, and update them as work progresses so others can pick up where you left off.
- LESSONS LEARNED: Add a "Lessons Learned" section at the end of the plan doc with useful insights.
- Read the plan description, handoffs, and lessons learned before starting work to preserve context and continuity.
- Do not duplicate implementation details here; focus on high-level design, rationale, alternatives considered, and final decisions.
High-level Design Documentation (docs/manual/)
- admin.md: Admin guide for server operators - configuration options, logging, performance tuning.
- lpc.md: LPC language reference - syntax, semantics, standard libraries.
- efuns.md: Comprehensive efun reference manual, categorized by functionality.
- dev.md: Developer workflow and build system, testing patterns and git workflow.
- unit-tests.md: Guidelines for writing and organizing unit tests using GoogleTest.
- console-mode.md: Using the interactive console mode for debugging and live interaction.
- internals.md: Driver architecture overview. Links to docs/internals/ for deep dives into specific subsystems.
- trace.md: Debugging and tracing guide - how to enable and interpret trace logs.
- When extending an existing feature, update the original design doc instead of creating a new one.
- Keep these documents updated as the codebase evolves, with high-level architecture and terminology for current code.
- High-level concepts include features visible to mudlib developers (efuns, applies, object model, compiler behavior).
- For new features, create design docs in docs/plan/ first, then move to manual when implementation starts. Keep implementation status updated and link implementation details back to design docs.
Implementation Details (docs/internals/)
- Keep these documents focused on design decisions, technical specifications, and internal architecture such as C APIs and data structures.
- Update them as implementation details change. Link back to high-level design docs in docs/manual/internals.md.
- lpc-types.md: Complete LPC type system reference - lpc_type_t vs svalue_type_t, encoding schemes, compatibility checking, common pitfalls
- lpc-program.md: Complete LPC compiler memory block system, binary save/load format, pointer serialization, inheritance resolution
- int64-design.md: Platform-agnostic 64-bit integer implementation - runtime types, bytecode encoding, binary compatibility
- async-library.md: Async library design - queues, workers, runtime integration
- error-runtime-routing.md: Runtime error transport and routing internals - typed exceptions, catch/fatal boundaries, master apply dispatch
When working on compiler features, consult these documents for:
- Type system rules: lpc_type_t vs svalue_type_t domains, masking NAME_TYPE_MOD, array/class detection
- Integer handling: svalue_u.number is int64_t, use PRId64 for formatting, F_LONG opcode for large literals
- Memory block allocations and their data types
- Binary file format and version validation
- Function/variable/class indexing schemes
- Pointer conversion during serialization
- Switch table patching mechanics