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. |
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:
libgodot/docs.crlibgodot/docs/a_getting_started/a_installation.cr
libgodot/docs/a_getting_started/b_compilation.cr
libgodot/docs/a_getting_started/c_quick_start_tutorial.cr
libgodot/docs/a_getting_started/d_crystal_basics_for_godot.cr
libgodot/docs/b_lapis_cli_and_toolchain/a_overview.cr
libgodot/docs/b_lapis_cli_and_toolchain/b_doctor.cr
libgodot/docs/b_lapis_cli_and_toolchain/c_init_and_scaffold.cr
libgodot/docs/b_lapis_cli_and_toolchain/d_build_and_sync.cr
libgodot/docs/b_lapis_cli_and_toolchain/e_test_and_benchmarks.cr
libgodot/docs/b_lapis_cli_and_toolchain/f_clean_and_maintenance.cr
libgodot/docs/b_lapis_cli_and_toolchain/g_addon_and_shard_management.cr
libgodot/docs/b_lapis_cli_and_toolchain/h_ide_and_lsp.cr
libgodot/docs/b_lapis_cli_and_toolchain/i_packaging_and_distribution.cr
libgodot/docs/b_lapis_cli_and_toolchain/j_common_pitfalls_and_faq.cr
libgodot/docs/b_lapis_cli_and_toolchain/k_logging_and_telemetry.cr
libgodot/docs/b_lapis_cli_and_toolchain/l_compile_flags_and_optimization.cr
libgodot/docs/b_lapis_cli_and_toolchain/m_addon_store_and_security.cr
libgodot/docs/c_gameplay_and_declarative_dsl/a_node_dsl.cr
libgodot/docs/c_gameplay_and_declarative_dsl/b_exports_and_inspector.cr
libgodot/docs/c_gameplay_and_declarative_dsl/c_signals_and_events.cr
libgodot/docs/c_gameplay_and_declarative_dsl/d_low_latency_input.cr
libgodot/docs/c_gameplay_and_declarative_dsl/e_scene_tree_and_lifecycle.cr
libgodot/docs/c_gameplay_and_declarative_dsl/f_gameplay_logging_and_sensors.cr
libgodot/docs/c_gameplay_and_declarative_dsl/g_ergonomic_node_access.cr
libgodot/docs/c_gameplay_and_declarative_dsl/h_modules_and_mixins.cr
libgodot/docs/c_gameplay_and_declarative_dsl/i_multiplayer_and_networking.cr
libgodot/docs/c_gameplay_and_declarative_dsl/j_gdscript_to_crystal_cheatsheet.cr
libgodot/docs/d_concurrency_and_fibers/a_fibers_and_cooperative_await.cr
libgodot/docs/d_concurrency_and_fibers/b_os_threads_and_channels.cr
libgodot/docs/d_concurrency_and_fibers/c_main_thread_dispatch.cr
libgodot/docs/e_memory_safety_and_engine_internals/a_objectdb_and_monotonic_ids.cr
libgodot/docs/e_memory_safety_and_engine_internals/b_dead_pointer_protection.cr
libgodot/docs/e_memory_safety_and_engine_internals/c_boehm_gc_vs_refcounting.cr
libgodot/docs/f_scripting_and_interoperability/a_first_class_crystal_scripts.cr
libgodot/docs/f_scripting_and_interoperability/b_gdscript_interop.cr
libgodot/docs/f_scripting_and_interoperability/c_doc_comments_and_f1_help.cr
libgodot/docs/g_debugging_and_diagnostics/a_radare2_native_debugging.cr
libgodot/docs/g_debugging_and_diagnostics/b_crash_handler_and_watchpoints.cr
libgodot/docs/g_debugging_and_diagnostics/c_leak_and_dispatch_diagnostics.cr
libgodot/docs/h_testing_and_benchmarks/a_testing_framework.cr
libgodot/docs/h_testing_and_benchmarks/b_performance_benchmarks.cr
libgodot/docs/i_architecture_and_extensions/a_dual_paradigm_model.cr
libgodot/docs/i_architecture_and_extensions/b_cpp_bridge_loader.cr
libgodot/docs/i_architecture_and_extensions/c_addons_and_multi_plugin_isolation.cr
libgodot/docs/i_architecture_and_extensions/d_godot_version_upgrade.cr
libgodot/docs/j_modern_cli_and_tui/a_interactive_command_center.cr
libgodot/docs/j_modern_cli_and_tui/b_tui_hub_and_specialized_views.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
Quick-Start Commands: Essential commands for building, running, and testing.
Lapis Quick Start:
lapis doctor # Diagnose developer environment & dependencies
lapis new game # Scaffold brand new Crystal Godot game
make all # Compile bridge, test suites, examples, and sync
make test # Execute specs, in-editor tool tests, and runtime suites
make editor # Launch test project in Godot Editor
make docs # Build offline HTML documentation site in docs/
Learning Tracks & Reading Paths: Curated reading order from beginner to advanced.
Structured Learning Tracks
1. Getting started (A_GETTING_STARTED)
A_GETTING_STARTED::A_INSTALLATION: **Installation & System Prerequisites** — Complete step-by-step setup guide for Crystal, Godot, and Lapis CLI.A_GETTING_STARTED::B_COMPILATION: Building Lapis from Source — Compiling the C++ loader bridge, Crystal runtime libraries, and workspace synchronization.A_GETTING_STARTED::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.A_GETTING_STARTED::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)
B_LAPIS_CLI_AND_TOOLCHAIN::A_OVERVIEW: **CLI Architecture & Global Options** — Anatomy of the unified lapis executable, global flags, and shell autocompletion.B_LAPIS_CLI_AND_TOOLCHAIN::B_DOCTOR: Doctor Diagnostic Checker — Comprehensive environment audit checking compilers, runtimes, debuggers, and projects.B_LAPIS_CLI_AND_TOOLCHAIN::C_INIT_AND_SCAFFOLD: **Project Initialization & Scaffolding** — Using lapis init, lapis new game, lapis new addon, and lapis new example.B_LAPIS_CLI_AND_TOOLCHAIN::D_BUILD_AND_SYNC: **Build & Synchronization Commands** — Compiling game libraries, plugins, standalone executables, and syncing multi-target projects.B_LAPIS_CLI_AND_TOOLCHAIN::E_TEST_AND_BENCHMARKS: **Testing Framework & Benchmark Suite** — Running the unified multi-phase test runner, interactive ANSI TUI, and performance benchmarks.B_LAPIS_CLI_AND_TOOLCHAIN::F_CLEAN_AND_MAINTENANCE: **Workspace Cleaning & Disk Reclamation** — Using lapis clean, pruning shadow DLLs (--shadows), dry-runs, and directory safety.B_LAPIS_CLI_AND_TOOLCHAIN::G_ADDON_AND_SHARD_MANAGEMENT: **Addon & Shard Dependency Management** — Installing GDExtension addons and managing Crystal shards with lapis addon and lapis shard.B_LAPIS_CLI_AND_TOOLCHAIN::H_IDE_AND_LSP: **IDE Integration & Language Server (LSP)** — Configuring VS Code, Cursor, Zed, and Neovim with Crystalline LSP and radare2 debugging.B_LAPIS_CLI_AND_TOOLCHAIN::I_PACKAGING_AND_DISTRIBUTION: **Packaging & Release Distribution** — Exporting playable standalone games, zip archives, Windows installers, and Debian packages.B_LAPIS_CLI_AND_TOOLCHAIN::J_COMMON_PITFALLS_AND_FAQ: **Common CLI Pitfalls & Frequently Asked Questions** — Solutions to common command-line errors, file locking, path resolution, and developer FAQ.B_LAPIS_CLI_AND_TOOLCHAIN::K_LOGGING_AND_TELEMETRY: **Logging Framework & Telemetry** — Diagnostic logging with Godot.log, custom filters, BBCode console output, compile-time elision, and lapis log.B_LAPIS_CLI_AND_TOOLCHAIN::L_COMPILE_FLAGS_AND_OPTIMIZATION: **Compile-Time Flags & Optimization** — Stripping unused subsystems for lean binaries and enabling opt-in low-overhead diagnostics.B_LAPIS_CLI_AND_TOOLCHAIN::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)
C_GAMEPLAY_AND_DECLARATIVE_DSL::A_NODE_DSL: **Declarative Node DSL & Lifecycle** — Authoring Godot nodes with the node ClassName < ParentNode syntax and virtual methods.C_GAMEPLAY_AND_DECLARATIVE_DSL::B_EXPORTS_AND_INSPECTOR: **Export System & Inspector Integration** — Exposing properties, ranges, enums, file pickers, and tool buttons to the Godot Inspector.C_GAMEPLAY_AND_DECLARATIVE_DSL::C_SIGNALS_AND_EVENTS: **Signals & Event-Driven Architecture** — Declaring signals, synthesized emit helpers, GDScript connections, and cooperative awaiting.C_GAMEPLAY_AND_DECLARATIVE_DSL::D_LOW_LATENCY_INPUT: **Low-Latency Input & Controls** — Sub-frame mouse look, zero-allocation input queries, unhandled input, and input maps.C_GAMEPLAY_AND_DECLARATIVE_DSL::E_SCENE_TREE_AND_LIFECYCLE: **Scene Tree Manipulation & Node Lifecycle** — Creating nodes (Godot.create), hierarchy management, node ownership, and clean deletion.C_GAMEPLAY_AND_DECLARATIVE_DSL::F_GAMEPLAY_LOGGING_AND_SENSORS: **Gameplay Logging & Diagnostics DSL** — Integrating structured logging, gameplay metrics, and tag filters within Godot nodes.C_GAMEPLAY_AND_DECLARATIVE_DSL::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!).C_GAMEPLAY_AND_DECLARATIVE_DSL::H_MODULES_AND_MIXINS: Modular Node Mixins (gmodule) — Authoring reusable gameplay traits, interfaces, and component mixins with export properties, signals, and lifecycle hooks.C_GAMEPLAY_AND_DECLARATIVE_DSL::I_MULTIPLAYER_AND_NETWORKING: Multiplayer and Networking — High-performance multiplayer networking, declarative @[RPC] annotations, synchronization DSL, and Wireshark-style network testing harness.C_GAMEPLAY_AND_DECLARATIVE_DSL::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)
D_CONCURRENCY_AND_FIBERS::A_FIBERS_AND_COOPERATIVE_AWAIT: **Fibers & Cooperative Signal Awaiting** — Single-threaded scene loop orchestration, Fiber.yield, and non-blocking timers.D_CONCURRENCY_AND_FIBERS::B_OS_THREADS_AND_CHANNELS: **OS Threads & Actor Channels** — Offloading intensive computing with Thread.new and buffered Godot::Channel(T).D_CONCURRENCY_AND_FIBERS::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)
E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::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.E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::B_DEAD_POINTER_PROTECTION: **Dead-Pointer Protection & Access Violation Defense** — Defensive inspection (#alive?, #destroyed?, #check_alive!) and DisposedObjectError.E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::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)
F_SCRIPTING_AND_INTEROPERABILITY::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.F_SCRIPTING_AND_INTEROPERABILITY::B_GDSCRIPT_INTEROP: **GDScript Interoperability & Project Bindings** — Bidirectional calling between Crystal and GDScript, automated typed wrappers, and Variant marshaling.F_SCRIPTING_AND_INTEROPERABILITY::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)
G_DEBUGGING_AND_DIAGNOSTICS::A_RADARE2_NATIVE_DEBUGGING: **Native radare2 Debugging, Decompilation & Gutter Breakpoints** — Attaching radare2 to Godot processes, native pseudo-C decompilation (pdc), disassembly, and multiplayer lockstep.G_DEBUGGING_AND_DIAGNOSTICS::B_CRASH_HANDLER_AND_WATCHPOINTS: **Crash Diagnostics, Watchpoints & Memory Inspection** — Debugging segmentation faults (0xC0000005), hardware watchpoints, and dead-pointer forensics.G_DEBUGGING_AND_DIAGNOSTICS::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)
H_TESTING_AND_BENCHMARKS::A_TESTING_FRAMEWORK: **Unified Testing Framework & Leak Verification** — Writing test suites, assertions, frame-stepping, and zero memory leak validation (assert_no_leak).H_TESTING_AND_BENCHMARKS::B_PERFORMANCE_BENCHMARKS: **Performance Profiling & Benchmark Reports** — Running Crystal vs GDScript benchmarks, SVG chart generation, and CI tracking.
9. Architecture and extensions (I_ARCHITECTURE_AND_EXTENSIONS)
I_ARCHITECTURE_AND_EXTENSIONS::A_DUAL_PARADIGM_MODEL: The Dual-Paradigm Execution Model — Mode A (GDExtension In-Editor Tool) vs Mode B (Standalone LibGodot Host Executable).I_ARCHITECTURE_AND_EXTENSIONS::B_CPP_BRIDGE_LOADER: Native C++ Loader Bridge Architecture — Flat C-ABI mapping, GDExtension function pointers, memory layouts, and crash guards.I_ARCHITECTURE_AND_EXTENSIONS::C_ADDONS_AND_MULTI_PLUGIN_ISOLATION: **GDExtension Addons & Multi-Plugin Isolation** — ClassDB namespace isolation, inter-addon dependencies, and compilation topologies across Crystal addons.I_ARCHITECTURE_AND_EXTENSIONS::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)
J_MODERN_CLI_AND_TUI::A_INTERACTIVE_COMMAND_CENTER: **Interactive Terminal Command Center & Differential TUI** — High-density telemetry dashboard, split-pane layout, differential cell rendering, and keyboard shortcuts.J_MODERN_CLI_AND_TUI::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.
Master Table of Contents: Complete hierarchical topic index.
Complete Documentation Index
A_GETTING_STARTED
A_GETTING_STARTED::A_INSTALLATION: **Installation & System Prerequisites** — Complete step-by-step setup guide for Crystal, Godot, and Lapis CLI.A_GETTING_STARTED::B_COMPILATION: Building Lapis from Source — Compiling the C++ loader bridge, Crystal runtime libraries, and workspace synchronization.A_GETTING_STARTED::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.A_GETTING_STARTED::D_CRYSTAL_BASICS_FOR_GODOT: Crystal Syntax Guide for Game Developers — Essential Crystal syntax, static typing, nil-safety, blocks, and official style guides.
B_LAPIS_CLI_AND_TOOLCHAIN
B_LAPIS_CLI_AND_TOOLCHAIN::A_OVERVIEW: **CLI Architecture & Global Options** — Anatomy of the unified lapis executable, global flags, and shell autocompletion.B_LAPIS_CLI_AND_TOOLCHAIN::B_DOCTOR: Doctor Diagnostic Checker — Comprehensive environment audit checking compilers, runtimes, debuggers, and projects.B_LAPIS_CLI_AND_TOOLCHAIN::C_INIT_AND_SCAFFOLD: **Project Initialization & Scaffolding** — Using lapis init, lapis new game, lapis new addon, and lapis new example.B_LAPIS_CLI_AND_TOOLCHAIN::D_BUILD_AND_SYNC: **Build & Synchronization Commands** — Compiling game libraries, plugins, standalone executables, and syncing multi-target projects.B_LAPIS_CLI_AND_TOOLCHAIN::E_TEST_AND_BENCHMARKS: **Testing Framework & Benchmark Suite** — Running the unified multi-phase test runner, interactive ANSI TUI, and performance benchmarks.B_LAPIS_CLI_AND_TOOLCHAIN::F_CLEAN_AND_MAINTENANCE: **Workspace Cleaning & Disk Reclamation** — Using lapis clean, pruning shadow DLLs (--shadows), dry-runs, and directory safety.B_LAPIS_CLI_AND_TOOLCHAIN::G_ADDON_AND_SHARD_MANAGEMENT: **Addon & Shard Dependency Management** — Installing GDExtension addons and managing Crystal shards with lapis addon and lapis shard.B_LAPIS_CLI_AND_TOOLCHAIN::H_IDE_AND_LSP: **IDE Integration & Language Server (LSP)** — Configuring VS Code, Cursor, Zed, and Neovim with Crystalline LSP and radare2 debugging.B_LAPIS_CLI_AND_TOOLCHAIN::I_PACKAGING_AND_DISTRIBUTION: **Packaging & Release Distribution** — Exporting playable standalone games, zip archives, Windows installers, and Debian packages.B_LAPIS_CLI_AND_TOOLCHAIN::J_COMMON_PITFALLS_AND_FAQ: **Common CLI Pitfalls & Frequently Asked Questions** — Solutions to common command-line errors, file locking, path resolution, and developer FAQ.B_LAPIS_CLI_AND_TOOLCHAIN::K_LOGGING_AND_TELEMETRY: **Logging Framework & Telemetry** — Diagnostic logging with Godot.log, custom filters, BBCode console output, compile-time elision, and lapis log.B_LAPIS_CLI_AND_TOOLCHAIN::L_COMPILE_FLAGS_AND_OPTIMIZATION: **Compile-Time Flags & Optimization** — Stripping unused subsystems for lean binaries and enabling opt-in low-overhead diagnostics.B_LAPIS_CLI_AND_TOOLCHAIN::M_ADDON_STORE_AND_SECURITY: **Addon Store & Security Auditing** — Installing, vendoring, updating, and security auditing GDExtension addons.
C_GAMEPLAY_AND_DECLARATIVE_DSL
C_GAMEPLAY_AND_DECLARATIVE_DSL::A_NODE_DSL: **Declarative Node DSL & Lifecycle** — Authoring Godot nodes with the node ClassName < ParentNode syntax and virtual methods.C_GAMEPLAY_AND_DECLARATIVE_DSL::B_EXPORTS_AND_INSPECTOR: **Export System & Inspector Integration** — Exposing properties, ranges, enums, file pickers, and tool buttons to the Godot Inspector.C_GAMEPLAY_AND_DECLARATIVE_DSL::C_SIGNALS_AND_EVENTS: **Signals & Event-Driven Architecture** — Declaring signals, synthesized emit helpers, GDScript connections, and cooperative awaiting.C_GAMEPLAY_AND_DECLARATIVE_DSL::D_LOW_LATENCY_INPUT: **Low-Latency Input & Controls** — Sub-frame mouse look, zero-allocation input queries, unhandled input, and input maps.C_GAMEPLAY_AND_DECLARATIVE_DSL::E_SCENE_TREE_AND_LIFECYCLE: **Scene Tree Manipulation & Node Lifecycle** — Creating nodes (Godot.create), hierarchy management, node ownership, and clean deletion.C_GAMEPLAY_AND_DECLARATIVE_DSL::F_GAMEPLAY_LOGGING_AND_SENSORS: **Gameplay Logging & Diagnostics DSL** — Integrating structured logging, gameplay metrics, and tag filters within Godot nodes.C_GAMEPLAY_AND_DECLARATIVE_DSL::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!).C_GAMEPLAY_AND_DECLARATIVE_DSL::H_MODULES_AND_MIXINS: Modular Node Mixins (gmodule) — Authoring reusable gameplay traits, interfaces, and component mixins with export properties, signals, and lifecycle hooks.C_GAMEPLAY_AND_DECLARATIVE_DSL::I_MULTIPLAYER_AND_NETWORKING: Multiplayer and Networking — High-performance multiplayer networking, declarative @[RPC] annotations, synchronization DSL, and Wireshark-style network testing harness.C_GAMEPLAY_AND_DECLARATIVE_DSL::J_GDSCRIPT_TO_CRYSTAL_CHEATSHEET: GDScript to Crystal Migration Cheatsheet — Exhaustive side-by-side cheatsheet mapping GDScript syntax to Crystal for Lapis.
D_CONCURRENCY_AND_FIBERS
D_CONCURRENCY_AND_FIBERS::A_FIBERS_AND_COOPERATIVE_AWAIT: **Fibers & Cooperative Signal Awaiting** — Single-threaded scene loop orchestration, Fiber.yield, and non-blocking timers.D_CONCURRENCY_AND_FIBERS::B_OS_THREADS_AND_CHANNELS: **OS Threads & Actor Channels** — Offloading intensive computing with Thread.new and buffered Godot::Channel(T).D_CONCURRENCY_AND_FIBERS::C_MAIN_THREAD_DISPATCH: **Main Thread Queue & Thread-Safe Dispatch** — Modifying scenes from workers via Godot.on_main_thread, call_deferred, and thread asserts.
E_MEMORY_SAFETY_AND_ENGINE_INTERNALS
E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::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.E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::B_DEAD_POINTER_PROTECTION: **Dead-Pointer Protection & Access Violation Defense** — Defensive inspection (#alive?, #destroyed?, #check_alive!) and DisposedObjectError.E_MEMORY_SAFETY_AND_ENGINE_INTERNALS::C_BOEHM_GC_VS_REFCOUNTING: Boehm GC vs Godot Reference Counting — Bridging Crystal's garbage collector and Godot's atomic reference counter.
F_SCRIPTING_AND_INTEROPERABILITY
F_SCRIPTING_AND_INTEROPERABILITY::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.F_SCRIPTING_AND_INTEROPERABILITY::B_GDSCRIPT_INTEROP: **GDScript Interoperability & Project Bindings** — Bidirectional calling between Crystal and GDScript, automated typed wrappers, and Variant marshaling.F_SCRIPTING_AND_INTEROPERABILITY::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.
G_DEBUGGING_AND_DIAGNOSTICS
G_DEBUGGING_AND_DIAGNOSTICS::A_RADARE2_NATIVE_DEBUGGING: **Native radare2 Debugging, Decompilation & Gutter Breakpoints** — Attaching radare2 to Godot processes, native pseudo-C decompilation (pdc), disassembly, and multiplayer lockstep.G_DEBUGGING_AND_DIAGNOSTICS::B_CRASH_HANDLER_AND_WATCHPOINTS: **Crash Diagnostics, Watchpoints & Memory Inspection** — Debugging segmentation faults (0xC0000005), hardware watchpoints, and dead-pointer forensics.G_DEBUGGING_AND_DIAGNOSTICS::C_LEAK_AND_DISPATCH_DIAGNOSTICS: **Leak Tracking & Latency Profiling** — Using LeakTracker, TombstoneTracker, and DispatchProfiler for runtime introspection.
H_TESTING_AND_BENCHMARKS
H_TESTING_AND_BENCHMARKS::A_TESTING_FRAMEWORK: **Unified Testing Framework & Leak Verification** — Writing test suites, assertions, frame-stepping, and zero memory leak validation (assert_no_leak).H_TESTING_AND_BENCHMARKS::B_PERFORMANCE_BENCHMARKS: **Performance Profiling & Benchmark Reports** — Running Crystal vs GDScript benchmarks, SVG chart generation, and CI tracking.
I_ARCHITECTURE_AND_EXTENSIONS
I_ARCHITECTURE_AND_EXTENSIONS::A_DUAL_PARADIGM_MODEL: The Dual-Paradigm Execution Model — Mode A (GDExtension In-Editor Tool) vs Mode B (Standalone LibGodot Host Executable).I_ARCHITECTURE_AND_EXTENSIONS::B_CPP_BRIDGE_LOADER: Native C++ Loader Bridge Architecture — Flat C-ABI mapping, GDExtension function pointers, memory layouts, and crash guards.I_ARCHITECTURE_AND_EXTENSIONS::C_ADDONS_AND_MULTI_PLUGIN_ISOLATION: **GDExtension Addons & Multi-Plugin Isolation** — ClassDB namespace isolation, inter-addon dependencies, and compilation topologies across Crystal addons.I_ARCHITECTURE_AND_EXTENSIONS::D_GODOT_VERSION_UPGRADE: Godot Engine Version Upgrade Guide — Upgrading target Godot versions, dumping extension_api.json, and regenerating Crystal class bindings.
J_MODERN_CLI_AND_TUI
J_MODERN_CLI_AND_TUI::A_INTERACTIVE_COMMAND_CENTER: **Interactive Terminal Command Center & Differential TUI** — High-density telemetry dashboard, split-pane layout, differential cell rendering, and keyboard shortcuts.J_MODERN_CLI_AND_TUI::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.