This README is the one indexed from the repository at its latest ref, not from the tag for this version.

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

---

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.