module Lapis::Docs

Overview

The Lapis::Docs module is the authoritative technical reference and documentation guide.

Learning Tracks & Topic Index

The documentation is paced into 10 distinct tracks:

1. Getting started (`A_GETTING_STARTED`)

Submodule	Title	Description
`A_INSTALLATION`	Installation & System Prerequisites	Complete step-by-step setup guide for Crystal, Godot, and Lapis CLI.
`B_COMPILATION`	Building Lapis from Source	Compiling the C++ loader bridge, Crystal runtime libraries, and workspace synchronization.
`C_QUICK_START_TUTORIAL`	First Game Tutorial (Zero to Hero)	Beginner-friendly step-by-step tutorial: create a project, write a Player node, run, and export.
`D_CRYSTAL_BASICS_FOR_GODOT`	Crystal Syntax Guide for Game Developers	Essential Crystal syntax, static typing, nil-safety, blocks, and official style guides.

2. Lapis cli and toolchain (`B_LAPIS_CLI_AND_TOOLCHAIN`)

Submodule	Title	Description
`A_OVERVIEW`	CLI Architecture & Global Options	Anatomy of the unified lapis executable, global flags, and shell autocompletion.
`B_DOCTOR`	Doctor Diagnostic Checker	Comprehensive environment audit checking compilers, runtimes, debuggers, and projects.
`C_INIT_AND_SCAFFOLD`	Project Initialization & Scaffolding	Using lapis init, lapis new game, lapis new addon, and lapis new example.
`D_BUILD_AND_SYNC`	Build & Synchronization Commands	Compiling game libraries, plugins, standalone executables, and syncing multi-target projects.
`E_TEST_AND_BENCHMARKS`	Testing Framework & Benchmark Suite	Running the unified multi-phase test runner, interactive ANSI TUI, and performance benchmarks.
`F_CLEAN_AND_MAINTENANCE`	Workspace Cleaning & Disk Reclamation	Using lapis clean, pruning shadow DLLs (--shadows), dry-runs, and directory safety.
`G_ADDON_AND_SHARD_MANAGEMENT`	Addon & Shard Dependency Management	Installing GDExtension addons and managing Crystal shards with lapis addon and lapis shard.
`H_IDE_AND_LSP`	IDE Integration & Language Server (LSP)	Configuring VS Code, Cursor, Zed, and Neovim with Crystalline LSP and radare2 debugging.
`I_PACKAGING_AND_DISTRIBUTION`	Packaging & Release Distribution	Exporting playable standalone games, zip archives, Windows installers, and Debian packages.
`J_COMMON_PITFALLS_AND_FAQ`	Common CLI Pitfalls & Frequently Asked Questions	Solutions to common command-line errors, file locking, path resolution, and developer FAQ.
`K_LOGGING_AND_TELEMETRY`	Logging Framework & Telemetry	Diagnostic logging with Godot.log, custom filters, BBCode console output, compile-time elision, and lapis log.
`L_COMPILE_FLAGS_AND_OPTIMIZATION`	Compile-Time Flags & Optimization	Stripping unused subsystems for lean binaries and enabling opt-in low-overhead diagnostics.
`M_ADDON_STORE_AND_SECURITY`	Addon Store & Security Auditing	Installing, vendoring, updating, and security auditing GDExtension addons.

3. Gameplay and declarative dsl (`C_GAMEPLAY_AND_DECLARATIVE_DSL`)

Submodule	Title	Description
`A_NODE_DSL`	Declarative Node DSL & Lifecycle	Authoring Godot nodes with the node ClassName < ParentNode syntax and virtual methods.
`B_EXPORTS_AND_INSPECTOR`	Export System & Inspector Integration	Exposing properties, ranges, enums, file pickers, and tool buttons to the Godot Inspector.
`C_SIGNALS_AND_EVENTS`	Signals & Event-Driven Architecture	Declaring signals, synthesized emit helpers, GDScript connections, and cooperative awaiting.
`D_LOW_LATENCY_INPUT`	Low-Latency Input & Controls	Sub-frame mouse look, zero-allocation input queries, unhandled input, and input maps.
`E_SCENE_TREE_AND_LIFECYCLE`	Scene Tree Manipulation & Node Lifecycle	Creating nodes (Godot.create), hierarchy management, node ownership, and clean deletion.
`F_GAMEPLAY_LOGGING_AND_SENSORS`	Gameplay Logging & Diagnostics DSL	Integrating structured logging, gameplay metrics, and tag filters within Godot nodes.
`G_ERGONOMIC_NODE_ACCESS`	Ergonomic Node & Path Access	Type-safe node retrieval, subscript indexers ([]), operator overloads (/ and %), path prefixes ($ and %), and bare macros (n! and u!).
`H_MODULES_AND_MIXINS`	Modular Node Mixins (gmodule)	Authoring reusable gameplay traits, interfaces, and component mixins with export properties, signals, and lifecycle hooks.
`I_MULTIPLAYER_AND_NETWORKING`	Multiplayer and Networking	High-performance multiplayer networking, declarative @[RPC] annotations, synchronization DSL, and Wireshark-style network testing harness.
`J_GDSCRIPT_TO_CRYSTAL_CHEATSHEET`	GDScript to Crystal Migration Cheatsheet	Exhaustive side-by-side cheatsheet mapping GDScript syntax to Crystal for Lapis.

4. Concurrency and fibers (`D_CONCURRENCY_AND_FIBERS`)

Submodule	Title	Description
`A_FIBERS_AND_COOPERATIVE_AWAIT`	Fibers & Cooperative Signal Awaiting	Single-threaded scene loop orchestration, Fiber.yield, and non-blocking timers.
`B_OS_THREADS_AND_CHANNELS`	OS Threads & Actor Channels	Offloading intensive computing with Thread.new and buffered Godot::Channel(T).
`C_MAIN_THREAD_DISPATCH`	Main Thread Queue & Thread-Safe Dispatch	Modifying scenes from workers via Godot.on_main_thread, call_deferred, and thread asserts.

5. Memory safety and engine internals (`E_MEMORY_SAFETY_AND_ENGINE_INTERNALS`)

Submodule	Title	Description
`A_OBJECTDB_AND_MONOTONIC_IDS`	Godot ObjectDB & Monotonic Instance IDs	Mapping native C++ heap pointers to 64-bit monotonic instance IDs to prevent pointer reuse.
`B_DEAD_POINTER_PROTECTION`	Dead-Pointer Protection & Access Violation Defense	Defensive inspection (#alive?, #destroyed?, #check_alive!) and DisposedObjectError.
`C_BOEHM_GC_VS_REFCOUNTING`	Boehm GC vs Godot Reference Counting	Bridging Crystal's garbage collector and Godot's atomic reference counter.

6. Scripting and interoperability (`F_SCRIPTING_AND_INTEROPERABILITY`)

Submodule	Title	Description
`A_FIRST_CLASS_CRYSTAL_SCRIPTS`	First-Class Crystal Scripts in Godot Editor	Writing .cr files directly inside Godot Script Editor with native syntax highlighting and Crystalline LSP.
`B_GDSCRIPT_INTEROP`	GDScript Interoperability & Project Bindings	Bidirectional calling between Crystal and GDScript, automated typed wrappers, and Variant marshaling.
`C_DOC_COMMENTS_AND_F1_HELP`	Doc Comments & Godot In-Editor F1 Help	Compile-time doc comment harvesting, DocData XML synthesis, and Godot offline documentation.

7. Debugging and diagnostics (`G_DEBUGGING_AND_DIAGNOSTICS`)

Submodule	Title	Description
`A_RADARE2_NATIVE_DEBUGGING`	Native radare2 Debugging, Decompilation & Gutter Breakpoints	Attaching radare2 to Godot processes, native pseudo-C decompilation (pdc), disassembly, and multiplayer lockstep.
`B_CRASH_HANDLER_AND_WATCHPOINTS`	Crash Diagnostics, Watchpoints & Memory Inspection	Debugging segmentation faults (0xC0000005), hardware watchpoints, and dead-pointer forensics.
`C_LEAK_AND_DISPATCH_DIAGNOSTICS`	Leak Tracking & Latency Profiling	Using LeakTracker, TombstoneTracker, and DispatchProfiler for runtime introspection.

8. Testing and benchmarks (`H_TESTING_AND_BENCHMARKS`)

Submodule	Title	Description
`A_TESTING_FRAMEWORK`	Unified Testing Framework & Leak Verification	Writing test suites, assertions, frame-stepping, and zero memory leak validation (assert_no_leak).
`B_PERFORMANCE_BENCHMARKS`	Performance Profiling & Benchmark Reports	Running Crystal vs GDScript benchmarks, SVG chart generation, and CI tracking.
`C_TESTING_ARCHITECTURE`	Exhaustive Multi-Tier Test Suite Inventory & Phase Guide	Comprehensive directory of all 6 test phases, 84 modular runtime suites, 70 engine specs, 19 CLI specs, in-editor tool runners, and zero-leak invariants.

9. Architecture and extensions (`I_ARCHITECTURE_AND_EXTENSIONS`)

Submodule	Title	Description
`A_DUAL_PARADIGM_MODEL`	The Dual-Paradigm Execution Model	Mode A (GDExtension In-Editor Tool) vs Mode B (Standalone LibGodot Host Executable).
`B_CPP_BRIDGE_LOADER`	Native C++ Loader Bridge Architecture	Flat C-ABI mapping, GDExtension function pointers, memory layouts, and crash guards.
`C_ADDONS_AND_MULTI_PLUGIN_ISOLATION`	GDExtension Addons & Multi-Plugin Isolation	ClassDB namespace isolation, inter-addon dependencies, and compilation topologies across Crystal addons.
`D_GODOT_VERSION_UPGRADE`	Godot Engine Version Upgrade Guide	Upgrading target Godot versions, dumping extension_api.json, and regenerating Crystal class bindings.

10. Modern cli and tui (`J_MODERN_CLI_AND_TUI`)

Submodule	Title	Description
`A_INTERACTIVE_COMMAND_CENTER`	Interactive Terminal Command Center & Differential TUI	High-density telemetry dashboard, split-pane layout, differential cell rendering, and keyboard shortcuts.
`B_TUI_HUB_AND_SPECIALIZED_VIEWS`	Interactive TUI Hub & Domain Workspaces	Operational guide to lapis cli hub, folder-picker new/editor wizards, context-aware package forms, r2 crash forensics, and benchmark analytics.

Defined in:

lib/lapis/src/libgodot/docs.cr
lib/lapis/src/libgodot/docs/a_getting_started/a_installation.cr
lib/lapis/src/libgodot/docs/a_getting_started/b_compilation.cr
lib/lapis/src/libgodot/docs/a_getting_started/c_quick_start_tutorial.cr
lib/lapis/src/libgodot/docs/a_getting_started/d_crystal_basics_for_godot.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/a_overview.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/b_doctor.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/c_init_and_scaffold.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/d_build_and_sync.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/e_test_and_benchmarks.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/f_clean_and_maintenance.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/g_addon_and_shard_management.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/h_ide_and_lsp.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/i_packaging_and_distribution.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/j_common_pitfalls_and_faq.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/k_logging_and_telemetry.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/l_compile_flags_and_optimization.cr
lib/lapis/src/libgodot/docs/b_lapis_cli_and_toolchain/m_addon_store_and_security.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/a_node_dsl.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/b_exports_and_inspector.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/c_signals_and_events.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/d_low_latency_input.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/e_scene_tree_and_lifecycle.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/f_gameplay_logging_and_sensors.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/g_ergonomic_node_access.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/h_modules_and_mixins.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/i_multiplayer_and_networking.cr
lib/lapis/src/libgodot/docs/c_gameplay_and_declarative_dsl/j_gdscript_to_crystal_cheatsheet.cr
lib/lapis/src/libgodot/docs/d_concurrency_and_fibers/a_fibers_and_cooperative_await.cr
lib/lapis/src/libgodot/docs/d_concurrency_and_fibers/b_os_threads_and_channels.cr
lib/lapis/src/libgodot/docs/d_concurrency_and_fibers/c_main_thread_dispatch.cr
lib/lapis/src/libgodot/docs/e_memory_safety_and_engine_internals/a_objectdb_and_monotonic_ids.cr
lib/lapis/src/libgodot/docs/e_memory_safety_and_engine_internals/b_dead_pointer_protection.cr
lib/lapis/src/libgodot/docs/e_memory_safety_and_engine_internals/c_boehm_gc_vs_refcounting.cr
lib/lapis/src/libgodot/docs/f_scripting_and_interoperability/a_first_class_crystal_scripts.cr
lib/lapis/src/libgodot/docs/f_scripting_and_interoperability/b_gdscript_interop.cr
lib/lapis/src/libgodot/docs/f_scripting_and_interoperability/c_doc_comments_and_f1_help.cr
lib/lapis/src/libgodot/docs/g_debugging_and_diagnostics/a_radare2_native_debugging.cr
lib/lapis/src/libgodot/docs/g_debugging_and_diagnostics/b_crash_handler_and_watchpoints.cr
lib/lapis/src/libgodot/docs/g_debugging_and_diagnostics/c_leak_and_dispatch_diagnostics.cr
lib/lapis/src/libgodot/docs/h_testing_and_benchmarks/a_testing_framework.cr
lib/lapis/src/libgodot/docs/h_testing_and_benchmarks/b_performance_benchmarks.cr
lib/lapis/src/libgodot/docs/h_testing_and_benchmarks/c_testing_architecture.cr
lib/lapis/src/libgodot/docs/i_architecture_and_extensions/a_dual_paradigm_model.cr
lib/lapis/src/libgodot/docs/i_architecture_and_extensions/b_cpp_bridge_loader.cr
lib/lapis/src/libgodot/docs/i_architecture_and_extensions/c_addons_and_multi_plugin_isolation.cr
lib/lapis/src/libgodot/docs/i_architecture_and_extensions/d_godot_version_upgrade.cr
lib/lapis/src/libgodot/docs/j_modern_cli_and_tui/a_interactive_command_center.cr
lib/lapis/src/libgodot/docs/j_modern_cli_and_tui/b_tui_hub_and_specialized_views.cr
docs.cr
docs/general/charting.cr
docs/general/game_helpers.cr
docs/general/nodes.cr
docs/general/overview.cr
docs/general/pipeline.cr
docs/general/primitives.cr

Class Method Summary

.topic_01_quick_start : Nil
Quick-Start Commands: Essential commands for building, running, and testing.
.topic_02_reading_paths : Nil
Learning Tracks & Reading Paths: Curated reading order from beginner to advanced.
.topic_03_table_of_contents : Nil
Master Table of Contents: Complete hierarchical topic index.

Class Method Detail

def self.topic_01_quick_start : Nil #

Quick-Start Commands: Essential commands for building, running, and testing.

Docs Quick Start:

make docs        # Build offline HTML documentation site in docs/
make test        # Execute specifications and test suites
make all         # Build and verify all targets

def self.topic_02_reading_paths : Nil #

Learning Tracks & Reading Paths: Curated reading order from beginner to advanced.

Structured Learning Tracks

1. General (`GENERAL`)

GENERAL::OVERVIEW: **Diorite Overview & Getting Started** — Diorite is a high-performance 2D and 3D debug drawing plugin and frame DSL for Godot Engine 4.8+ powered by the Lapis Crystal toolchain.
GENERAL::PRIMITIVES: Diorite Primitives Reference — Complete guide to all 26 procedural 2D and 3D debug drawing primitives supported by Diorite.
GENERAL::NODES: Diorite Scene Node System — Using Diorite's exported Node3D and Node2D classes for in-editor placement and persistent hierarchy visualization.
GENERAL::CHARTING: Data Visualization and Charting — Complete guide to 2D and 3D Pie charts, Bar charts, Radial gauges, and multi-series telemetry graphs.
GENERAL::GAME_HELPERS: Game Spatial Helpers and UX Controls — Comprehensive guide to swept shape casts, splines, actor cards, channels, transform stacks, and freeze mode.
GENERAL::PIPELINE: **Diorite Render Architecture & Zero-Alloc Pipeline** — Architecture of Diorite's batch renderer, priority layering, immediate meshes, and zero-allocation memory recycling.

def self.topic_03_table_of_contents : Nil #

Master Table of Contents: Complete hierarchical topic index.

Complete Documentation Index

`GENERAL`

GENERAL::OVERVIEW: **Diorite Overview & Getting Started** — Diorite is a high-performance 2D and 3D debug drawing plugin and frame DSL for Godot Engine 4.8+ powered by the Lapis Crystal toolchain.
GENERAL::PRIMITIVES: Diorite Primitives Reference — Complete guide to all 26 procedural 2D and 3D debug drawing primitives supported by Diorite.
GENERAL::NODES: Diorite Scene Node System — Using Diorite's exported Node3D and Node2D classes for in-editor placement and persistent hierarchy visualization.
GENERAL::CHARTING: Data Visualization and Charting — Complete guide to 2D and 3D Pie charts, Bar charts, Radial gauges, and multi-series telemetry graphs.
GENERAL::GAME_HELPERS: Game Spatial Helpers and UX Controls — Comprehensive guide to swept shape casts, splines, actor cards, channels, transform stacks, and freeze mode.
GENERAL::PIPELINE: **Diorite Render Architecture & Zero-Alloc Pipeline** — Architecture of Diorite's batch renderer, priority layering, immediate meshes, and zero-allocation memory recycling.

diorite

module Lapis::Docs

Overview

Learning Tracks & Topic Index

1. Getting started (A_GETTING_STARTED)

2. Lapis cli and toolchain (B_LAPIS_CLI_AND_TOOLCHAIN)

3. Gameplay and declarative dsl (C_GAMEPLAY_AND_DECLARATIVE_DSL)

4. Concurrency and fibers (D_CONCURRENCY_AND_FIBERS)

5. Memory safety and engine internals (E_MEMORY_SAFETY_AND_ENGINE_INTERNALS)

6. Scripting and interoperability (F_SCRIPTING_AND_INTEROPERABILITY)

7. Debugging and diagnostics (G_DEBUGGING_AND_DIAGNOSTICS)

8. Testing and benchmarks (H_TESTING_AND_BENCHMARKS)

9. Architecture and extensions (I_ARCHITECTURE_AND_EXTENSIONS)

10. Modern cli and tui (J_MODERN_CLI_AND_TUI)