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
| Function | Signature | Description |
|---|---|---|
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
| Function | Signature | Description |
|---|---|---|
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 Command | Raylib Call | Notes |
|---|---|---|
CMD_RECTANGLE | DrawRectangleRec | Sharp corners |
CMD_RECTANGLE (radius > 0) | DrawRectangleRounded | Rounded corners |
CMD_TEXT | DrawTextEx | Uses font from font table |
CMD_BORDER (uniform) | DrawRectangleRoundedLinesEx | Outline with optional rounding |
CMD_BORDER (per-side) | 4x DrawRectangleRec | Thin filled rects per side |
CMD_IMAGE | DrawTexturePro | imageData cast to Texture* |
CMD_SCISSOR_START | BeginScissorMode | Clip region |
CMD_SCISSOR_END | EndScissorMode | End 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
u8Color with(unsigned char)value. - Rounded corners: Raylib’s
DrawRectangleRoundeduses a singleroundnessvalue (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