Docs::J_FIRST_CLASS_CRYSTAL_SCRIPTS

J. First-Class Crystal Scripts (.cr) in Godot

LibGodot establishes .cr (Crystal) script files as first-class citizens in the Godot 4 Editor, matching the native workflow of GDScript and C#.

Architecture Overview

Component	Implementation	Purpose
CrystalLanguage	Godot::CrystalLanguage < ScriptLanguageExtension	Registers language name, extension, templates, and code completion in ScriptServer
CrystalScript	Godot::CrystalScript < ScriptExtension	Represents .cr files as Godot Script resources, exposing Inspector properties
ResourceFormatLoader	Godot::ResourceFormatLoaderCrystal	Enables Godot's FileSystem dock and ResourceLoader to load .cr files directly
ResourceFormatSaver	Godot::ResourceFormatSaverCrystal	Persists modifications in the Godot Script Editor back to .cr files on disk (Ctrl+S)
CrystalSyntaxHighlighter	Godot::CrystalHighlighter < EditorSyntaxHighlighter	High-performance, zero-dependency tokenizer coloring keywords, types, annotations, symbols, and comments
LSP Worker	Godot::CrystalLSP	Sandboxed background bridge for optional Crystalline language server diagnostics

---

1. Built-in Script Editor Tab

Double-clicking any .cr file in the Godot FileSystem dock opens the file directly inside the engine's built-in Script workspace tab.

• Zero External Dependencies: Syntax highlighting operates independently of external daemons.
• Theme Integration: Highlights match the active Godot Editor theme colors.
• Instant Save: Pressing Ctrl+S in the script editor invokes ResourceFormatSaverCrystal, saving the file to disk.
• F5 Fast Build: Pressing F5 automatically compiles Crystal source code into game.dll and reloads.

---

2. Inspector Property Reflection

Nodes with attached .cr scripts display exported properties directly inside the Godot Inspector dock:

require "libgodot"

node Player < CharacterBody2D do
  @[Export(range: 50.0_f32..1000.0_f32, step: 10.0_f32)]
  property speed : Float32 = 300.0_f32

  @[Export(range: 10..500, step: 5)]
  property max_health : Int32 = 100

  signal health_changed(current : Int32, max_health : Int32)
  signal died
end

When selected in the scene tree:

• speed renders as a numeric slider clamped between 50 and 1000 with step 10.
• max_health renders as an integer spinner.
• health_changed and died appear in the Node Signals dock.

---

3. Sandboxed Language Server (Crystalline)

While built-in code completion and syntax highlighting function out-of-the-box, LibGodot includes an optional background bridge for crystalline:

• Auto-detects crystalline binary in PATH.
• Sandboxed in a protected background worker; if Crystalline crashes or errors, it fails gracefully without interrupting the editor.