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.cr
libgodot/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

Class Method Detail

def self.topic_01_quick_start : Nil #

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/

def self.topic_02_reading_paths : Nil #

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

Structured Learning Tracks

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)

def self.topic_03_table_of_contents : Nil #

Master Table of Contents: Complete hierarchical topic index.

Complete Documentation Index

A_GETTING_STARTED
B_LAPIS_CLI_AND_TOOLCHAIN
C_GAMEPLAY_AND_DECLARATIVE_DSL
D_CONCURRENCY_AND_FIBERS
E_MEMORY_SAFETY_AND_ENGINE_INTERNALS
F_SCRIPTING_AND_INTEROPERABILITY
G_DEBUGGING_AND_DIAGNOSTICS
H_TESTING_AND_BENCHMARKS
I_ARCHITECTURE_AND_EXTENSIONS
J_MODERN_CLI_AND_TUI