Clay Raylib Module

GX includes a clay_raylib module that renders Clay UI layouts using Raylib drawing functions. Instead of manually iterating render commands, you call a single function per frame to draw the entire UI.

Supports rectangles (with rounded corners), text (with multiple fonts), borders, images, and scissor clipping.

Prerequisites

Requires both the clay and raylib modules. Raylib must be installed with raylib.h and raylib.lib / libraylib.a.

Usage

import clay
import clay_raylib
import raylib.core
import raylib.text

Build with -I modules:

gx myapp.gx -I modules -o myapp.exe

Quick Example

import clay
import clay_raylib
import raylib.core
import raylib.input
import raylib.text
import raylib.colors

fn main() {
    InitWindow(800, 600, "Clay + Raylib")
    SetTargetFPS(60)

    var ctx = clay.gx_clay_init(800.0, 600.0)
    var font = GetFontDefault()
    clay_raylib.gx_clay_raylib_init(&font, 1)

    while (!WindowShouldClose()) {
        var dt = GetFrameTime()
        clay.gx_clay_set_pointer(GetMouseX(), GetMouseY(), IsMouseButtonDown(MOUSE_BUTTON_LEFT))

        clay.gx_clay_begin_layout()

        // Root panel
        clay.gx_clay_open_id("root")
        clay.gx_clay_config_full(
            clay.COLUMN,
            clay.SIZING_GROW, 0.0, 0.0,
            clay.SIZING_GROW, 0.0, 0.0,
            16, 16, 16, 16, 8,
            clay.ALIGN_LEFT, clay.ALIGN_TOP,
            40.0, 40.0, 45.0, 255.0,
            0.0, 0.0, 0.0, 0.0
        )
            clay.gx_clay_text("Hello Clay!", 255.0, 255.0, 255.0, 255.0, 0, 24)

            // Button with rounded corners
            clay.gx_clay_open_id("btn")
            clay.gx_clay_config_rect(80.0, 60.0, 200.0, 255.0, 8.0)
                clay.gx_clay_text("Play Game", 255.0, 255.0, 255.0, 255.0, 0, 18)
            clay.gx_clay_close()
        clay.gx_clay_close()

        var count: i32 = 0
        var cmds = clay.gx_clay_end_layout(dt, &count)

        BeginDrawing()
        ClearBackground(BLACK)
        clay_raylib.gx_clay_render_raylib(cmds, count)
        EndDrawing()
    }
    CloseWindow()
}

Initialization

FunctionSignatureDescription
gx_clay_raylib_init(*void, i32)Set font table + install text measurement

Call once after loading fonts. The first argument is a pointer to a Font array. The array index matches Clay’s font_id in text elements.

// Single font (font_id 0 = default)
var font = GetFontDefault()
clay_raylib.gx_clay_raylib_init(&font, 1)

Multiple Fonts

var fonts: Font[3]
fonts[0] = LoadFontEx("regular.ttf", 20, 0, 0)
fonts[1] = LoadFontEx("bold.ttf", 20, 0, 0)
fonts[2] = LoadFontEx("mono.ttf", 16, 0, 0)
clay_raylib.gx_clay_raylib_init(&fonts, 3)

// Use font_id to select:
clay.gx_clay_text("Normal", 255.0, 255.0, 255.0, 255.0, 0, 20)  // font 0
clay.gx_clay_text("Bold", 255.0, 255.0, 255.0, 255.0, 1, 20)    // font 1
clay.gx_clay_text("Code", 180.0, 180.0, 180.0, 255.0, 2, 16)    // font 2

gx_clay_raylib_init also installs the text measurement callback so Clay computes accurate text layouts using MeasureTextEx.

Rendering

FunctionSignatureDescription
gx_clay_render_raylib(*void, i32)Render all commands with Raylib

Call between BeginDrawing() and EndDrawing():

var count: i32 = 0
var cmds = clay.gx_clay_end_layout(dt, &count)

BeginDrawing()
ClearBackground(BLACK)
clay_raylib.gx_clay_render_raylib(cmds, count)
EndDrawing()

Render Command Mapping

Clay CommandRaylib CallNotes
CMD_RECTANGLEDrawRectangleRecSharp corners
CMD_RECTANGLE (radius > 0)DrawRectangleRoundedRounded corners
CMD_TEXTDrawTextExUses font from font table
CMD_BORDER (uniform)DrawRectangleRoundedLinesExOutline with optional rounding
CMD_BORDER (per-side)4x DrawRectangleRecThin filled rects per side
CMD_IMAGEDrawTextureProimageData cast to Texture*
CMD_SCISSOR_STARTBeginScissorModeClip region
CMD_SCISSOR_ENDEndScissorModeEnd clipping

Common Patterns

Game Menu with Hover Effects

// Build a menu button — change color on hover
clay.gx_clay_open_id("start_btn")
if (clay.gx_clay_hovered()) {
    clay.gx_clay_config_rect(100.0, 80.0, 220.0, 255.0, 6.0)
} else {
    clay.gx_clay_config_rect(70.0, 50.0, 180.0, 255.0, 6.0)
}
    clay.gx_clay_text("Start Game", 255.0, 255.0, 255.0, 255.0, 0, 20)
clay.gx_clay_close()

HUD Overlay

// Score display in top-right
clay.gx_clay_open_id("hud")
clay.gx_clay_config_full(
    clay.ROW,
    clay.SIZING_GROW, 0.0, 0.0,
    clay.SIZING_FIT, 0.0, 0.0,
    0, 0, 0, 0, 0,
    clay.ALIGN_RIGHT, clay.ALIGN_TOP,
    0.0, 0.0, 0.0, 0.0,
    0.0, 0.0, 0.0, 0.0
)
    clay.gx_clay_open_id("score_box")
    clay.gx_clay_config_rect(0.0, 0.0, 0.0, 150.0, 8.0)
        clay.gx_clay_text("Score: 9500", 255.0, 220.0, 50.0, 255.0, 0, 18)
    clay.gx_clay_close()
clay.gx_clay_close()

Platform Notes

  • Color convention: Clay uses 0-255 floats. The renderer converts to Raylib’s u8 Color with (unsigned char)value.
  • Rounded corners: Raylib’s DrawRectangleRounded uses a single roundness value (0.0-1.0), not per-corner radii. The renderer uses the maximum corner radius to compute roundness.
  • Text buffer: Text slices are copied to a 4KB stack buffer for null-termination. Strings longer than 4095 chars are truncated.
  • TCC: Supported — the renderer is header-only C.

Module Layout

modules/
  clay_raylib/
    c/
      gx_clay_render_raylib.h   Render loop, font table, text measurement
    gx/
      clay_raylib.gx             Module: 2 extern functions