CRShader

CRShader is a high-performance shader trans-compiler and live runtime development toolchain for Godot Engine 4.8+, powered by Crystal and Lapis. It introduces a declarative, type-safe Crystal shader DSL that transpiles down to optimized Godot GDShader (4.x) and GLSL compute kernels with native machine speed (~1.1ms transpilation, >100,000 LOC/s).

Architecture

CRShader bridges compile-time Crystal syntax with Godot's runtime rendering pipeline:

graph TD
    subgraph CRShader Toolchain Pipeline
        SRC[".crshader Source File"] --> LEX[Lexer & AST Parser]
        LEX --> AST[Typed Shader AST]
        AST --> GEN_GD[GDShader 4.x Transpiler Backend]
        AST --> GEN_GLSL[GLSL Compute Transpiler Backend]
        GEN_GD --> GD_OUT[Target .gdshader]
        GEN_GLSL --> GLSL_OUT[Target .glsl]
    end

    subgraph Godot Engine Integration
        RFL[ResourceFormatLoaderCRShader] -->|Transparent In-Memory Load| RES[Godot Shader Resource]
        RES --> MAT[ShaderMaterial]
        MAT --> GPU[Godot Vulkan / D3D12 / Metal Pipeline]
        PLUG[CRShaderPlugin] --> HIGHLIGHT[ScriptEditor Syntax Highlighter Hook]
        PLUG --> STUDIO[CRShader Studio Dock Panel]
    end

    SRC -->|Direct Engine Import| RFL

• Transparent In-Memory Loading: ResourceFormatLoaderCRShader registers with Godot's ResourceLoader, allowing .crshader files to be assigned directly to ShaderMaterial without requiring intermediate files on disk.
• In-Editor Syntax Highlighting: Hooks into Godot's ScriptEditor to dynamically provide full Crystal/Shader keyword and type highlighting for .crshader files.
• CRShader Studio: Embedded split-screen dock providing side-by-side live source editing and transpiled .gdshader / .glsl output preview.

Features

• Crystal Shader DSL: Author shaders using expressive Crystal constructs (shader_type :canvas_item, render_mode :unshaded, uniform, varying, stage :fragment).
• High-Speed Transpiler: Compiles complex spatial and post-processing shaders in ~1.1ms at >100,000 lines of code per second.
• Transparent Godot Integration: Full GDExtension plugin loaded via crystal_bridge.dll / .so without requiring end-users to have Crystal installed.
• Mirrored Godot Documentation: Complete offline API documentation generated under CRShader::Language capturing every Godot 4 built-in function, stage variable, and preprocessor macro.
• Interactive Shader Viewer: Bundled standalone showcase viewer allowing real-time inspection, shader parameter tweaking, and hot-reloading across a rich gallery of 20+ shaders.

Performance Benchmarks

CRShader includes a quantitative compiler benchmark measuring lexical parsing, AST construction, and transpilation throughput:

Run benchmarks locally:

make benchmark
# or directly via Lapis CLI:
lapis benchmarks run html

View the latest automated Interactive Benchmark Report deployed live on GitHub Pages.

DSL Comparison

shader_type :canvas_item
render_mode :unshaded
# Uniform parameters
uniform tint : vec4 = vec4(0.2, 0.6, 1.0, 1.0)
uniform speed : float = 1.5
# Fragment stage
stage :fragment do
  uv = UV + vec2(TIME * speed * 0.1, 0.0)
  col = texture(TEXTURE, uv) * tint
  COLOR = col
end

shader_type canvas_item;
render_mode unshaded;
// Uniform parameters
uniform vec4 tint = vec4(0.2, 0.6, 1.0, 1.0);
uniform float speed = 1.5;
// Fragment stage
void fragment() {
    vec2 uv = UV + vec2(TIME * speed * 0.1, 0.0);
    vec4 col = texture(TEXTURE, uv) * tint;
    COLOR = col;
}

Quickstart

1. Installation

Add crshader as a dependency in your shard.yml:

dependencies:
  crshader:
    github: sol-vin/crshader
    branch: master

Run shards install.

2. Command Line Tool (crshader)

Build the standalone CLI compiler:

make
crystal build src/cli.cr -o bin/crshader

3. Godot Editor Integration

1. Launch Godot Editor:

   make editor

2. Enable the plugin in Project Settings -> Plugins -> CRShader.
3. Create or drag any .crshader file into the res:// directory.
4. Open the CRShader Studio bottom panel to inspect, recompile, and preview transpiled output in real time.

Standalone Shader Applications

1. Interactive Shader Viewer

CRShader provides an interactive standalone viewer showcasing 20+ procedural shaders (animated water, CRT scanlines, Kuwahara filter, PSX retro, fire particles, tonemapping, compute kernels) across multiple 3D polygon meshes (Cube, Sphere, Cylinder, Torus, Prism, Plane), screen-space quad post-processing, camera compositor passes, and dynamic uniform tweaking:

make viewer

Packaged standalone viewer executables are available on the Releases page under viewer-windows.zip and viewer-linux.zip.

2. Live Shader Sandbox

CRShader includes a split-screen live coding environment allowing side-by-side editing in Crystal DSL with real-time viewport preview:

• Rich syntax highlighting for keywords, built-ins, and types.
• Reference sample gallery: open, edit, and experiment with any of our 20+ bundled .crshader shaders.
• 2D, 3D (with mesh selection), screen-space quad, and compute modes.
• Background pattern/color switcher and texture input slots (uniform sampler2D).
• Real-time uniform parameter tweaking.

make sandbox

Packaged standalone sandbox executables are available on the Releases page under sandbox-windows.zip and sandbox-linux.zip.

Development & Testing

License

MIT License. Copyright (c) Ian Rash and Sol-Vin contributors.