GitHub C Weekly Trending Repositories

opa334/Dopamine

Dopamine is a semi-untethered jailbreak for iOS 15 to 26(.0.1)

Dopamine

A rootless semi-untethered jailbreak for iOS 15.0 - 17.3.1 (arm64e), iOS 15.0 - 18.7.1, 26.0 - 26.0.1 (A12/A13) and iOS 15.0 - 18.7.1 (arm64). More details will follow here soon.

Please note that all issues related to version support will be deleted without response.

Official website / download: https://ellekit.space/dopamine/

meshcore-dev/MeshCore

A new lightweight, hybrid routing mesh protocol for packet radios

About MeshCore

MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.

🔍 What is MeshCore?

MeshCore now supports a range of LoRa devices, allowing for easy flashing without the need to compile firmware manually. Users can flash a pre-built binary using tools like Adafruit ESPTool and interact with the network through a serial console. MeshCore provides the ability to create wireless mesh networks, similar to Meshtastic and Reticulum but with a focus on lightweight multi-hop packet routing for embedded projects. Unlike Meshtastic, which is tailored for casual LoRa communication, or Reticulum, which offers advanced networking, MeshCore balances simplicity with scalability, making it ideal for custom embedded solutions, where devices (nodes) can communicate over long distances by relaying messages through intermediate nodes. This is especially useful in off-grid, emergency, or tactical situations where traditional communication infrastructure is unavailable.

⚡ Key Features

Multi-Hop Packet Routing
- Devices can forward messages across multiple nodes, extending range beyond a single radio's reach.
- Supports up to a configurable number of hops to balance network efficiency and prevent excessive traffic.
- Nodes use fixed roles where "Companion" nodes are not repeating messages at all to prevent adverse routing paths from being used.
Supports LoRa Radios – Works with Heltec, RAK Wireless, and other LoRa-based hardware.
Decentralized & Resilient – No central server or internet required; the network is self-healing.
Low Power Consumption – Ideal for battery-powered or solar-powered devices.
Simple to Deploy – Pre-built example applications make it easy to get started.

🎯 What Can You Use MeshCore For?

Off-Grid Communication: Stay connected even in remote areas.
Emergency Response & Disaster Recovery: Set up instant networks where infrastructure is down.
Outdoor Activities: Hiking, camping, and adventure racing communication.
Tactical & Security Applications: Military, law enforcement, and private security use cases.
IoT & Sensor Networks: Collect data from remote sensors and relay it back to a central location.

🚀 How to Get Started

Watch the MeshCore QuickStart Playlist by The Comms Channel
Watch the MeshCore Technical Presentation by Liam Cottle.
Read through our Frequently Asked Questions and Documentation.
Flash the MeshCore firmware on a supported device.
Connect with a supported client.

For developers:

Install PlatformIO in Visual Studio Code.
Clone and open the MeshCore repository in Visual Studio Code.
See the example applications you can modify and run:
- Companion Radio - For use with an external chat app, over BLE, USB or Wi-Fi.
- KISS Modem - Serial KISS protocol bridge for host applications. (protocol docs)
- Simple Repeater - Extends network coverage by relaying messages.
- Simple Room Server - A simple BBS server for shared Posts.
- Simple Secure Chat - Secure terminal based text communication between devices.
- Simple Sensor - Remote sensor node with telemetry and alerting.

The Simple Secure Chat example can be interacted with through the Serial Monitor in Visual Studio Code, or with a Serial USB Terminal on Android.

⚡️ MeshCore Flasher

We have prebuilt firmware ready to flash on supported devices.

Launch https://meshcore.io/flasher
Select a supported device
Flash one of the firmware types:
- Companion, Repeater or Room Server
Once flashing is complete, you can connect with one of the MeshCore clients below.

📱 MeshCore Clients

Companion Firmware

The companion firmware can be connected to via BLE, USB or Wi-Fi depending on the firmware type you flashed.

Repeater and Room Server Firmware

The repeater and room server firmware can be set up via USB in the web config tool.

https://config.meshcore.io

They can also be managed via LoRa in the mobile app by using the Remote Management feature.

🛠 Hardware Compatibility

MeshCore is designed for devices listed in the MeshCore Flasher

📜 License

MeshCore is open-source software released under the MIT License. You are free to use, modify, and distribute it for personal and commercial projects.

Contributing

Please submit PR's using 'dev' as the base branch! For minor changes just submit your PR and we'll try to review it, but for anything more 'impactful' please open an Issue first and start a discussion. It is better to sound out what it is you want to achieve first, and try to come to a consensus on what the best approach is, especially when it impacts the structure or architecture of this codebase.

Here are some general principles you should try to adhere to:

Keep it simple. Please, don't think like a high-level lang programmer. Think embedded, and keep code concise, without any unnecessary layers.
No dynamic memory allocation, except during setup/begin functions.
Use the same brace and indenting style that's in the core source modules. (A .clang-format is probably going to be added soon, but please do NOT retroactively re-format existing code. This just creates unnecessary diffs that make finding problems harder)

Help us prioritize! Please react with thumbs-up to issues/PRs you care about most. We look at reaction counts when planning work.

Running unit tests

To run unit tests, run the following command:

pio test --environment native --verbose

Road-Map / To-Do

There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In very rough chronological order:

📞 Get Support

Report bugs and request features on the GitHub Issues page.
Find additional guides and components on my site.
Join MeshCore Discord to chat with the developers and get help from the community.

nicbarker/clay

High performance UI layout library in C.

Clay, A UI Layout Library

Clay (short for C Layout) is a high performance 2D UI layout library.

Major Features

Microsecond layout performance
Flex-box like layout model for complex, responsive layouts including text wrapping, scrolling containers and aspect ratio scaling
Transition API for easy layout animations
Single 4.8k LOC clay.h file with zero dependencies (including no standard library linking)
Wasm support: compile with clang to a 15kb uncompressed .wasm file for use in the browser
Static arena based memory use with no malloc / free, and low total memory overhead (e.g. ~3.5mb for 8192 layout elements).
React-like nested declarative syntax
Renderer agnostic: outputs a sorted list of rendering primitives that can be easily composited in any 3D engine, and even compiled to HTML (examples provided)

Take a look at the clay website for an example of clay compiled to wasm and running in the browser, or others in the examples directory.

You can also watch the introduction video for an overview of the motivation behind Clay's development and a short demo of its usage.

An example GUI application built with clay

Quick Start

Download or clone clay.h and include it after defining CLAY_IMPLEMENTATION in one file.

// Must be defined in one file, _before_ #include "clay.h"
#define CLAY_IMPLEMENTATION
#include "../../clay.h"

const Clay_Color COLOR_LIGHT = (Clay_Color) {224, 215, 210, 255};
const Clay_Color COLOR_RED = (Clay_Color) {168, 66, 28, 255};
const Clay_Color COLOR_ORANGE = (Clay_Color) {225, 138, 50, 255};

void HandleClayErrors(Clay_ErrorData errorData) {
    // See the Clay_ErrorData struct for more information
    printf("%s", errorData.errorText.chars);
    switch(errorData.errorType) {
        // etc
    }
}

// Example measure text function
static inline Clay_Dimensions MeasureText(Clay_StringSlice text, Clay_TextElementConfig *config, uintptr_t userData) {
    // Clay_TextElementConfig contains members such as fontId, fontSize, letterSpacing etc
    // Note: Clay_String->chars is not guaranteed to be null terminated
    return (Clay_Dimensions) {
            .width = text.length * config->fontSize, // <- this will only work for monospace fonts, see the renderers/ directory for more advanced text measurement
            .height = config->fontSize
    };
}

// Layout config is just a struct that can be declared statically, or inline
Clay_ElementDeclaration sidebarItemConfig = (Clay_ElementDeclaration) {
    .layout = {
        .sizing = { .width = CLAY_SIZING_GROW(0), .height = CLAY_SIZING_FIXED(50) }
    },
    .backgroundColor = COLOR_ORANGE
};

// Re-useable components are just normal functions
void SidebarItemComponent() {
    CLAY(id, sidebarItemConfig) {
        // children go here...
    }
}

int main() {
    // Note: malloc is only used here as an example, any allocator that provides
    // a pointer to addressable memory of at least totalMemorySize will work
    uint64_t totalMemorySize = Clay_MinMemorySize();
    Clay_Arena arena = Clay_CreateArenaWithCapacityAndMemory(totalMemorySize, malloc(totalMemorySize));

    // Note: screenWidth and screenHeight will need to come from your environment, Clay doesn't handle window related tasks
    Clay_Initialize(arena, (Clay_Dimensions) { screenWidth, screenHeight }, (Clay_ErrorHandler) { HandleClayErrors });

    while(renderLoop()) { // Will be different for each renderer / environment
        // Optional: Update internal layout dimensions to support resizing
        Clay_SetLayoutDimensions((Clay_Dimensions) { screenWidth, screenHeight });
        // Optional: Update internal pointer position for handling mouseover / click / touch events - needed for scrolling & debug tools
        Clay_SetPointerState((Clay_Vector2) { mousePositionX, mousePositionY }, isMouseDown);
        // Optional: Update internal pointer position for handling mouseover / click / touch events - needed for scrolling and debug tools
        Clay_UpdateScrollContainers(true, (Clay_Vector2) { mouseWheelX, mouseWheelY }, deltaTime);

        // All clay layouts are declared between Clay_BeginLayout and Clay_EndLayout
        Clay_BeginLayout();

        // An example of laying out a UI with a fixed width sidebar and flexible width main content
        CLAY(CLAY_ID("OuterContainer"), { .layout = { .sizing = {CLAY_SIZING_GROW(0), CLAY_SIZING_GROW(0)}, .padding = CLAY_PADDING_ALL(16), .childGap = 16 }, .backgroundColor = {250,250,255,255} }) {
            CLAY(CLAY_ID("SideBar"), {
                .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .sizing = { .width = CLAY_SIZING_FIXED(300), .height = CLAY_SIZING_GROW(0) }, .padding = CLAY_PADDING_ALL(16), .childGap = 16 },
                .backgroundColor = COLOR_LIGHT
            }) {
                CLAY(CLAY_ID("ProfilePictureOuter"), { .layout = { .sizing = { .width = CLAY_SIZING_GROW(0) }, .padding = CLAY_PADDING_ALL(16), .childGap = 16, .childAlignment = { .y = CLAY_ALIGN_Y_CENTER } }, .backgroundColor = COLOR_RED }) {
                    CLAY(CLAY_ID("ProfilePicture"), { .layout = { .sizing = { .width = CLAY_SIZING_FIXED(60), .height = CLAY_SIZING_FIXED(60) }}, .image = { .imageData = &profilePicture } }) {}
                    CLAY_TEXT(CLAY_STRING("Clay - UI Library"), { .fontSize = 24, .textColor = {255, 255, 255, 255} });
                }

                // Standard C code like loops etc work inside components
                for (int i = 0; i < 5; i++) {
                    SidebarItemComponent();
                }

                CLAY(CLAY_ID("MainContent"), { .layout = { .sizing = { .width = CLAY_SIZING_GROW(0), .height = CLAY_SIZING_GROW(0) } }, .backgroundColor = COLOR_LIGHT }) {}
            }
        }

        // All clay layouts are declared between Clay_BeginLayout and Clay_EndLayout
        Clay_RenderCommandArray renderCommands = Clay_EndLayout(deltaTime); // deltaTime is the time since the last frame, and is used for transitions

        // More comprehensive rendering examples can be found in the renderers/ directory
        for (int i = 0; i < renderCommands.length; i++) {
            Clay_RenderCommand *renderCommand = &renderCommands.internalArray[i];

            switch (renderCommand->commandType) {
                case CLAY_RENDER_COMMAND_TYPE_RECTANGLE: {
                    DrawRectangle(renderCommand->boundingBox, renderCommand->renderData.rectangle.backgroundColor);
                }
                // ... Implement handling of other command types
            }
        }
    }
}

The above example, rendered correctly will look something like the following:

In summary, the general order of steps is:

Clay_SetLayoutDimensions(dimensions)
Clay_SetPointerState(pointerPosition, isPointerDown)
Clay_UpdateScrollContainers(enableDragScrolling, scrollDelta, deltaTime)
Clay_BeginLayout()
Declare your layout with the provided Element Macros
Clay_EndLayout()
Render the results using the outputted Clay_RenderCommandArray

For help starting out or to discuss clay, considering joining the discord server.

Summary

High Level Documentation

Building UI Hierarchies

Clay UIs are built using the C macro CLAY(id, { configuration }). This macro creates a new empty element in the UI hierarchy, and supports modular customisation of layout, styling and functionality. The CLAY() macro can also be nested, similar to other declarative UI systems like HTML.

Child elements are added by opening a block: {} after calling the CLAY() macro (exactly like you would with an if statement or for loop), and declaring child components inside the braces.

// Parent element with 8px of padding
CLAY(CLAY_ID("parent"), { .layout = { .padding = CLAY_PADDING_ALL(8) } }) {
    // Child element 1
    CLAY_TEXT(CLAY_STRING("Hello World"), { .fontSize = 16 });
    // Child element 2 with red background
    CLAY((CLAY_ID("child"), { .backgroundColor = COLOR_RED }) {
        // etc
    }
}

However, unlike HTML and other declarative DSLs, this macro is just C. As a result, you can use arbitrary C code such as loops, functions and conditions inside your layout declaration code:

// Re-usable "components" are just functions that declare more UI
void ButtonComponent(Clay_String buttonText) {
    // Red box button with 8px of padding
    CLAY_AUTO_ID({ .layout = { .padding = CLAY_PADDING_ALL(8) }, .backgroundColor = COLOR_RED }) {
        CLAY_TEXT(buttonText, textConfig);
    }
}

// Parent element
CLAY(CLAY_ID("parent"), { .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM } }) {
    // Render a bunch of text elements
    for (int i = 0; i < textArray.length; i++) {
        CLAY_TEXT(textArray.elements[i], textConfig);
    }
    // Only render this element if we're on a mobile screen
    if (isMobileScreen) {
        CLAY(0) {
            // etc
        }
    }
    // Re-usable components
    ButtonComponent(CLAY_STRING("Click me!"));
    ButtonComponent(CLAY_STRING("No, click me!"));
});

Configuring Layout and Styling UI Elements

The layout and style of clay elements is configured with the Clay_ElementDeclaration struct passed to the CLAY() macro.

CLAY(CLAY_ID("box"), { .layout = { .padding = { 8, 8, 8, 8 }, .layoutDirection = CLAY_TOP_TO_BOTTOM } }) {
    // Children are 8px inset into parent, and laid out top to bottom
}

This macro isn't magic - all it's doing is wrapping the standard designated initializer syntax. e.g. (Clay_ElementDeclaration) { .layout = { .padding = { .left = 8, .right = 8 } ....

See the Clay_ElementDeclaration API for the full list of options.

A Clay_ElementDeclaration struct can be defined in file scope or elsewhere, and reused.

// Define a style in the global / file scope
Clay_ElementDeclaration reuseableStyle = (Clay_ElementDeclaration) {
    .layout = { .padding = { .left = 12 } },
    .backgroundColor = { 120, 120, 120, 255 },
    .cornerRadius = { 12, 12, 12, 12 }
};

CLAY(CLAY_ID("box"), reuseableStyle) {
    // ...
}

Element IDs

The Clay macro by default accepts an ID as its first argument, which is usually provided by the CLAY_ID() convenience macro. Elements can also be created with auto generated IDs, by using the CLAY_AUTO_ID() macro.

// Will always produce the same ID from the same input string
CLAY(CLAY_ID("OuterContainer"), { ...configuration }) {}

// Generates a unique ID that may not be the same between two layout calls
CLAY_AUTO_ID({ ...configuration }) {}

Element IDs have two main use cases. Firstly, tagging an element with an ID allows you to query information about the element later, such as its mouseover state or dimensions.

Secondly, IDs are visually useful when attempting to read and modify UI code, as well as when using the built-in debug tools.

To avoid having to construct dynamic strings at runtime to differentiate ids in loops, clay provides the CLAY_IDI(string, index) macro to generate different ids from a single input string. Think of IDI as "ID + Index"

// This is the equivalent of calling CLAY_ID("Item0"), CLAY_ID("Item1") etc
for (int index = 0; index < items.length; index++) {
    CLAY(CLAY_IDI("Item", index), { ..configuration }) {}
}

This ID will be forwarded to the final Clay_RenderCommandArray for use in retained mode UIs. Using duplicate IDs may cause some functionality to misbehave (i.e. if you're trying to attach a floating container to a specific element with ID that is duplicated, it may not attach to the one you expect)

Mouse, Touch and Pointer Interactions

Clay provides several functions for handling mouse and pointer interactions.

All pointer interactions depend on the function void Clay_SetPointerState(Clay_Vector2 position, bool isPointerDown) being called after each mouse position update and before any other clay functions.

During UI declaration

The function bool Clay_Hovered() can be called during element construction or in the body of an element, and returns true if the mouse / pointer is over the currently open element.

// An orange button that turns blue when hovered
CLAY(CLAY_ID("Button"), { .backgroundColor = Clay_Hovered() ? COLOR_BLUE : COLOR_ORANGE }) {
    bool buttonHovered = Clay_Hovered();
    CLAY_TEXT(buttonHovered ? CLAY_STRING("Hovered") : CLAY_STRING("Hover me!"), headerTextConfig);
}

The function void Clay_OnHover() allows you to attach a function pointer to the currently open element, which will be called if the mouse / pointer is over the element.

void HandleButtonInteraction(Clay_ElementId elementId, Clay_PointerData pointerInfo, void *userData) {
    ButtonData *buttonData = (ButtonData *)userData;
    // Pointer state allows you to detect mouse down / hold / release
    if (pointerInfo.state == CLAY_POINTER_DATA_PRESSED_THIS_FRAME) {
        // Do some click handling
        NavigateTo(buttonData->link);
    }
}

ButtonData linkButton = (ButtonData) { .link = "https://github.com/nicbarker/clay" };

// HandleButtonInteraction will be called for each frame the mouse / pointer / touch is inside the button boundaries
CLAY(CLAY_ID("Button"), { .layout = { .padding = CLAY_PADDING_ALL(8) } }) {
    Clay_OnHover(HandleButtonInteraction, &linkButton);
    CLAY_TEXT(CLAY_STRING("Button"), &headerTextConfig);
}

Before / After UI declaration

If you want to query mouse / pointer overlaps outside layout declarations, you can use the function bool Clay_PointerOver(Clay_ElementId id), which takes an element id and returns a bool representing whether the current pointer position is within its bounding box.

// Reminder: Clay_SetPointerState must be called before functions that rely on pointer position otherwise it will have no effect
Clay_Vector2 mousePosition = { x, y };
Clay_SetPointerState(mousePosition, mouseButtonDown(0));
// ...
// If profile picture was clicked
if (mouseButtonDown(0) && Clay_PointerOver(Clay_GetElementId("ProfilePicture"))) {
    // Handle profile picture clicked
}

Note that the bounding box queried by Clay_PointerOver is from the last frame. This generally shouldn't make a difference except in the case of animations that move at high speed. If this is an issue for you, performing layout twice per frame with the same data will give you the correct interaction the second time.

Scrolling Elements

Elements are configured as scrollable with the .clip configuration. Clipping instructs the renderer to not draw any pixels outside the clipped element's boundaries, and by specifying the .childOffset field, the clipped element's contents can be shifted around to provide "scrolling" behaviour.

You can either calculate scrolling yourself and simply provide the current offset each frame to .childOffset, or alternatively, Clay provides a built in mechanism for tracking and updating scroll container offsets, detailed below.

To make scroll containers respond to mouse wheel and scroll events, two functions need to be called before BeginLayout():

Clay_Vector2 mousePosition = { x, y };
// Reminder: Clay_SetPointerState must be called before Clay_UpdateScrollContainers otherwise it will have no effect
Clay_SetPointerState(mousePosition);
// Clay_UpdateScrollContainers needs to be called before Clay_BeginLayout for the position to avoid a 1 frame delay
Clay_UpdateScrollContainers(
    true, // Enable drag scrolling
    scrollDelta, // Clay_Vector2 scrollwheel / trackpad scroll x and y delta this frame
    float deltaTime, // Time since last frame in seconds as a float e.g. 8ms is 0.008f
);
// ...
// Clay internally tracks the scroll containers offset, and Clay_GetScrollOffset returns the x,y offset of the currently open element
CLAY(CLAY_ID("ScrollContainer"), { .clip = { .vertical = true, .childOffset = Clay_GetScrollOffset() } }) {
    // Scrolling contents
}
// .childOffset can be provided directly if you would prefer to manage scrolling outside of clay
CLAY(CLAY_ID("ScrollContainer"), { .clip = { .vertical = true, .childOffset = myData.scrollContainer.offset } }) {
    // Scrolling contents
}

More specific details can be found in the docs for Clay_UpdateScrollContainers, Clay_SetPointerState, Clay_ClipElementConfig and Clay_GetScrollOffset.

Floating Elements ("Absolute" Positioning)

All standard elements in clay are laid out on top of, and within their parent, positioned according to their parent's layout rules, and affect the positioning and sizing of siblings.

"Floating" is configured with the CLAY_FLOATING() macro. Floating elements don't affect the parent they are defined in, or the position of their siblings. They also have a z-index, and as a result can intersect and render over the top of other elements.

A classic example use case for floating elements is tooltips and modals.

// The two text elements will be laid out top to bottom, and the floating container
// will be attached to "Outer"
CLAY(CLAY_ID("Outer"), { .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM } }) {
    CLAY_TEXT(text, &headerTextConfig);
    CLAY(CLAY_ID("Tooltip"), { .floating = { .attachTo = CLAY_ATTACH_TO_PARENT } }) {}
    CLAY_TEXT(text, &headerTextConfig);
}

More specific details can be found in the full Floating API.

Laying Out Your Own Custom Elements

Clay only supports a simple set of UI element primitives, such as rectangles, text and images. Clay provides a singular API for layout out custom elements:

#include "clay.h"

typedef enum {
    CUSTOM_ELEMENT_TYPE_MODEL,
    CUSTOM_ELEMENT_TYPE_VIDEO
} CustomElementType;

// A rough example of how you could handle laying out 3d models in your UI
typedef struct {
    CustomElementType type;
    union {
        Model model;
        Video video;
        // ...
    };
} CustomElementData;

Model myModel = Load3DModel(filePath);
CustomElement modelElement = (CustomElement) { .type = CUSTOM_ELEMENT_TYPE_MODEL, .model = myModel }

typedef struct {
    void* memory;
    uintptr_t offset;
} Arena;

// During init
Arena frameArena = (Arena) { .memory = malloc(1024) };

// Custom elements only take a single pointer, so we need to store the data somewhere
CustomElementData *modelData = (CustomElementData *)(frameArena.memory + frameArena.offset);
*modelData = (CustomElementData) { .type = CUSTOM_ELEMENT_TYPE_MODEL, .model = myModel };
frameArena.offset += sizeof(CustomElementData);
CLAY(CLAY_ID("3DModelViewer"), { .custom = { .customData = modelData } }) {}

// Later during your rendering
switch (renderCommand->commandType) {
    // ...
    case CLAY_RENDER_COMMAND_TYPE_CUSTOM: {
        // Your extended struct is passed through
        CustomElementData *customElement = renderCommand->config.customElementConfig->customData;
        if (!customElement) continue;
        switch (customElement->type) {
            case CUSTOM_ELEMENT_TYPE_MODEL: {
                // Render your 3d model here
                break;
            }
            case CUSTOM_ELEMENT_TYPE_VIDEO: {
                // Render your video here
                break;
            }
            // ...
        }
        break;
    }
}

More specific details can be found in the full Custom Element API.

Transitions

Clay includes a "Transition" API, which allows you to smoothly animate / tween from one state to another. Both layout-affecting properties such as width and height, as well as non-layout properties such as backgroundColor are supported. See the transition documentation for more info.

// Note: for transitions to work, elements need a stable ID from one frame to the next - using loop indexes or CLAY_AUTO_ID will not work.
CLAY(CLAY_IDI("box", colors[index].id), {
    .layout.sizing = { CLAY_SIZING_GROW(), CLAY_SIZING_GROW() },
    .layout.childAlignment = { CLAY_ALIGN_X_CENTER, CLAY_ALIGN_Y_CENTER },
    .backgroundColor = boxColor,
    .overlayColor = Clay_Hovered() ? (Clay_Color) { 140, 140, 140, 80 } : (Clay_Color) { 255, 255, 255, 0 },
    // Transitions will activate once a handler function is defined.
    .transition = {
        .handler = Clay_EaseOut,
        .duration = 0.5f,
        // A "flag" enum is used to specify which properties to transition, use a bitwise OR (|) to construct the flags.
        .properties = CLAY_TRANSITION_PROPERTY_WIDTH | CLAY_TRANSITION_PROPERTY_POSITION | CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR | CLAY_TRANSITION_PROPERTY_BACKGROUND_COLOR,
        .enter = { .setInitialState = EnterExitSlideUp },
        .exit = { .setFinalState = EnterExitSlideUp },
    }
}) {
    Clay_OnHover(HandleCellButtonInteraction, (void*)(uint64_t)index);
    CLAY_TEXT(((Clay_String) { .length = 2, .chars = colors[index].stringId, .isStaticallyAllocated = true }), {
        .fontSize = 32,
        .textColor = colors[index].id > 29 ? (Clay_Color) {255, 255, 255, 255} : (Clay_Color) {154, 123, 184, 255 }
    });
}

An example of the transition API action can be found at examples/raylib-transitions

Retained Mode Rendering

Clay was originally designed for Immediate Mode rendering - where the entire UI is redrawn every frame. This may not be possible with your platform, renderer design or performance constraints.

There are some general techniques that can be used to integrate clay into a retained mode rendering system:

Clay_RenderCommand includes the uint32_t id that was used to declare the element. If unique ids are used, these can be mapped to persistent graphics objects across multiple frames / layouts.
Render commands are culled automatically to only currently visible elements, and Clay_RenderCommand is a small enough struct that you can simply compare the memory of two render commands with matching IDs to determine if the element is "dirty" and needs to be re-rendered or updated.

For a worked example, see the provided HTML renderer. This renderer converts clay layouts into persistent HTML documents with minimal changes per frame.

Visibility Culling

Clay provides a built-in visibility-culling mechanism that is enabled by default. It will only output render commands for elements that are visible - that is, at least one pixel of their bounding box is inside the viewport.

This culling mechanism can be disabled via the use of the #define CLAY_DISABLE_CULLING directive. See Preprocessor Directives for more information.

Preprocessor Directives

Clay supports C preprocessor directives to modulate functionality at compile time. These can be set either in code using #define CLAY_DISABLE_CULLING or on the command line when compiling using the appropriate compiler specific arguments, e.g. clang -DCLAY_DISABLE_CULLING main.c ...

The supported directives are:

CLAY_WASM - Required when targeting Web Assembly.
CLAY_DLL - Required when creating a .Dll file.

Bindings for non C

Clay is usable out of the box as a .h include in both C99 and C++20 with designated initializer support. There are also supported bindings for other languages, including:

Other implementations

Clay has also been implemented in other languages:

glay - Go line-by-line rewrite with readability as main goal.
totallygamerjet/clay - Port using cxgo, a C to Go transpiler.
goclay - Go line-by-line rewrite closely matching the reference.

Debug Tools

Clay includes built-in UI debugging tools, similar to the "inspector" in browsers such as Chrome or Firefox. These tools are included in clay.h, and work by injecting additional render commands into the output Clay_RenderCommandArray.

As long as the renderer that you're using works correctly, no additional setup or configuration is required to use the debug tools.

To enable the debug tools, use the function Clay_SetDebugModeEnabled(bool enabled). This boolean is persistent and does not need to be set every frame.

The debug tooling by default will render as a panel to the right side of the screen, compressing your layout by its width. The default width is 400 and is currently configurable via the direct mutation of the internal variable Clay__debugViewWidth, however this is an internal API and is potentially subject to change.

The official Clay website with debug tooling visible

Running more than one Clay instance

Clay allows you to run more than one instance in a program. To do this, Clay_Initialize returns a Clay_Context* reference. You can activate a specific instance using Clay_SetCurrentContext. If Clay_SetCurrentContext is not called, then Clay will default to using the context from the most recently called Clay_Initialize.

⚠ Important: Do not render instances across different threads simultaneously, as Clay does not currently support proper multi-threading.

// Define separate arenas for the instances.
Clay_Arena arena1, arena2;
// ... allocate arenas

// Initialize both instances, storing the context for each one.
Clay_Context* instance1 = Clay_Initialize(arena1, layoutDimensions, errorHandler);
Clay_Context* instance2 = Clay_Initialize(arena2, layoutDimensions, errorHandler);

// In the program's render function, activate each instance before executing clay commands and macros.
Clay_SetCurrentContext(instance1);
Clay_BeginLayout();
// ... declare layout for instance1
Clay_RenderCommandArray renderCommands1 = Clay_EndLayout(deltaTime);
render(renderCommands1);

// Switch to the second instance
Clay_SetCurrentContext(instance2);
Clay_BeginLayout();
// ... declare layout for instance2
Clay_RenderCommandArray renderCommands2 = Clay_EndLayout(deltaTime);
render(renderCommands2);

API

Naming Conventions

"CAPITAL_LETTERS()" are used for macros.
"Clay__" ("Clay" followed by double underscore) is used for internal functions that are not intended for use and are subject to change.
"Clay_" ("Clay" followed by single underscore) is used for external functions that can be called by the user.

Public Functions

Lifecycle for public functions

At startup / initialization time, run once Clay_MinMemorySize -> Clay_CreateArenaWithCapacityAndMemory -> Clay_Initialize -> Clay_SetMeasureTextFunction

Each Frame Clay_SetLayoutDimensions -> Clay_SetPointerState -> Clay_UpdateScrollContainers -> Clay_BeginLayout -> CLAY() etc... -> Clay_EndLayout

Clay_MinMemorySize

uint32_t Clay_MinMemorySize()

Returns the minimum amount of memory in bytes that clay needs to accommodate the current CLAY_MAX_ELEMENT_COUNT.

Clay_CreateArenaWithCapacityAndMemory

Clay_Arena Clay_CreateArenaWithCapacityAndMemory(size_t capacity, void *memory)

Creates a Clay_Arena struct with the given capacity and base memory pointer, which can be passed to Clay_Initialize.

Clay_SetMeasureTextFunction

void Clay_SetMeasureTextFunction(Clay_Dimensions (*measureTextFunction)(Clay_StringSlice text, Clay_TextElementConfig *config, void* userData), void* userData)

Takes a pointer to a function that can be used to measure the width, height dimensions of a string. Used by clay during layout to determine CLAY_TEXT element sizing and wrapping.

Note 1: This string is not guaranteed to be null terminated. Clay saves significant performance overhead by using slices when wrapping text instead of having to clone new null terminated strings. If your renderer does not support ptr, length style strings (e.g. Raylib), you will need to clone this to a new C string before rendering.

Note 2: It is essential that this function is as fast as possible. For text heavy use-cases this function is called many times, and despite the fact that clay caches text measurements internally, it can easily become the dominant overall layout cost if the provided function is slow. This is on the hot path!

Clay_ResetMeasureTextCache

void Clay_ResetMeasureTextCache(void)

Clay caches measurements from the provided MeasureTextFunction, and this will be sufficient for the majority of use-cases. However, if the measurements can depend on external factors that clay does not know about, like DPI changes, then the cached values may be incorrect. When one of these external factors changes, Clay_ResetMeasureTextCache can be called to force clay to recalculate all string measurements in the next frame.

Clay_SetMaxElementCount

void Clay_SetMaxElementCount(int32_t maxElementCount)

Sets the internal maximum element count that will be used in subsequent Clay_Initialize() and Clay_MinMemorySize() calls, allowing clay to allocate larger UI hierarchies.

Note: You will need to reinitialize clay, after calling Clay_MinMemorySize() to calculate updated memory requirements.

Clay_SetMaxMeasureTextCacheWordCount

void Clay_SetMaxMeasureTextCacheWordCount(int32_t maxMeasureTextCacheWordCount)

Sets the internal text measurement cache size that will be used in subsequent Clay_Initialize() and Clay_MinMemorySize() calls, allowing clay to allocate more text. The value represents how many separate words can be stored in the text measurement cache.

Note: You will need to reinitialize clay, after calling Clay_MinMemorySize() to calculate updated memory requirements.

Clay_Initialize

Clay_Context* Clay_Initialize(Clay_Arena arena, Clay_Dimensions layoutDimensions, Clay_ErrorHandler errorHandler)

Initializes the internal memory mapping, sets the internal dimensions for layout, and binds an error handler for clay to use when something goes wrong. Returns a Clay_Context* that can optionally be given to Clay_SetCurrentContext to allow running multiple instances of clay in the same program, and sets it as the current context. See Running more than one Clay instance.

Reference: Clay_Arena, Clay_ErrorHandler, Clay_SetCurrentContext

Clay_SetCurrentContext

void Clay_SetCurrentContext(Clay_Context* context)

Sets the context that subsequent clay commands will operate on. You can get this reference from Clay_Initialize or Clay_GetCurrentContext. See Running more than one Clay instance.

Clay_GetCurrentContext

Clay_Context* Clay_GetCurrentContext()

Returns the context that clay commands are currently operating on, or null if no context has been set. See Running more than one Clay instance.

Clay_SetLayoutDimensions

void Clay_SetLayoutDimensions(Clay_Dimensions dimensions)

Sets the internal layout dimensions. Cheap enough to be called every frame with your screen dimensions to automatically respond to window resizing, etc.

Clay_SetPointerState

void Clay_SetPointerState(Clay_Vector2 position, bool isPointerDown)

Sets the internal pointer position and state (i.e. current mouse / touch position) and recalculates overlap info, which is used for mouseover / click calculation (via Clay_PointerOver and updating scroll containers with Clay_UpdateScrollContainers. isPointerDown should represent the current state this frame, e.g. it should be true for the entire duration the left mouse button is held down. Clay has internal handling for detecting click / touch start & end.

Clay_UpdateScrollContainers

void Clay_UpdateScrollContainers(bool enableDragScrolling, Clay_Vector2 scrollDelta, float deltaTime)

This function handles scrolling of containers. It responds to both scrollDelta, which represents mouse wheel or trackpad scrolling this frame, as well as "touch scrolling" on mobile devices, or "drag scrolling" with a mouse or similar device.

Touch / drag scrolling only occurs if the enableDragScrolling parameter is true, and Clay_SetPointerState has been called this frame. As a result, you can simply always call it with false as the first argument if you want to disable touch scrolling.

deltaTime is the time in seconds since the last frame (e.g. 0.016 is 16 milliseconds), and is used to normalize & smooth scrolling across different refresh rates.

Clay_GetScrollOffset

Clay_Vector2 Clay_GetScrollOffset()

Returns the internally stored scroll offset for the currently open element.

Generally intended for use with clip elements and the .childOffset field to create scrolling containers.

See Scrolling Elements for more details.

// Create a horizontally scrolling container
CLAY(CLAY_ID("ScrollContainer"), {
    .clip = { .horizontal = true, .childOffset = Clay_GetScrollOffset() }
})

Clay_BeginLayout

void Clay_BeginLayout()

Prepares clay to calculate a new layout. Called each frame / layout before any of the Element Macros.

Clay_EndLayout

Clay_RenderCommandArray Clay_EndLayout()

Ends declaration of element macros and calculates the results of the current layout. Renders a Clay_RenderCommandArray containing the results of the layout calculation.

Clay_Hovered

bool Clay_Hovered()

Called during layout declaration, and returns true if the pointer position previously set with Clay_SetPointerState is inside the bounding box of the currently open element. Note: this is based on the element's position from the last frame.

Clay_OnHover

void Clay_OnHover(void (*onHoverFunction)(Clay_ElementId elementId, Clay_PointerData pointerData, void *userData), void *userData)

Called during layout declaration, this function allows you to attach a function pointer to the currently open element that will be called once per layout if the pointer position previously set with Clay_SetPointerState is inside the bounding box of the currently open element. See Clay_PointerData for more information on the pointerData argument.

void HandleButtonInteraction(Clay_ElementId elementId, Clay_PointerData pointerData, void *userData) {
    ButtonData *buttonData = (ButtonData *)userData;
    // Pointer state allows you to detect mouse down / hold / release
    if (pointerData.state == CLAY_POINTER_DATA_PRESSED_THIS_FRAME) {
        // Do some click handling
        NavigateTo(buttonData->link);
    }
}

ButtonData linkButton = (ButtonData) { .link = "https://github.com/nicbarker/clay" };

// HandleButtonInteraction will be called for each frame the mouse / pointer / touch is inside the button boundaries
CLAY(CLAY_ID("Button"), { .layout = { .padding = CLAY_PADDING_ALL(8) } }) {
    Clay_OnHover(HandleButtonInteraction, &buttonData);
    CLAY_TEXT(CLAY_STRING("Click me!"), &headerTextConfig);
}

Clay_PointerOver

bool Clay_PointerOver(Clay_ElementId id)

Returns true if the pointer position previously set with Clay_SetPointerState is inside the bounding box of the layout element with the provided id. Note: this is based on the element's position from the last frame. If frame-accurate pointer overlap detection is required, perhaps in the case of significant change in UI layout between frames, you can simply run your layout code twice that frame. The second call to Clay_PointerOver will be frame-accurate.

Clay_GetOpenElementId

Clay_ElementId Clay_GetOpenElementId()

Returns the Clay_ElementId of the currently open element. Useful for getting the ID of elements opened with CLAY_AUTO_ID.

Clay_GetScrollContainerData

Clay_ScrollContainerData Clay_GetScrollContainerData(Clay_ElementId id)

Returns Clay_ScrollContainerData for the scroll container matching the provided ID. This function allows imperative manipulation of scroll position, allowing you to build things such as scroll bars, buttons that "jump" to somewhere in a scroll container, etc.

Clay_GetElementData

Clay_ElementData Clay_GetElementData(Clay_ElementId id)

Returns Clay_ElementData for the element matching the provided ID. Used to retrieve information about elements such as their final calculated bounding box.

Clay_GetElementId

Clay_ElementId Clay_GetElementId(Clay_String idString)

Returns a Clay_ElementId for the provided id string, used for querying element info such as mouseover state, scroll container data, etc.

Element Macros

CLAY()

Usage

CLAY(...configuration) { ...children }

Lifecycle

Clay_BeginLayout() -> CLAY() -> Clay_EndLayout()

Notes

CLAY opens a generic empty container, that is configurable and supports nested children. CLAY requires a parameter, so if you want to create an element without any configuration, use CLAY(0).

Examples

// Define an element with 16px of x and y padding
CLAY(CLAY_ID("Outer"), { .layout = { .padding = CLAY_PADDING_ALL(16) } }) {
    // A nested child element
    CLAY(CLAY_ID("SideBar"), { .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .childGap = 16 } }) {
        // Children laid out top to bottom with a 16 px gap between them
    }
    // A vertical scrolling container with a colored background
    CLAY(CLAY_ID("ScrollContainer"), {
        .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .childGap = 16 },
        .backgroundColor = { 200, 200, 100, 255 },
        .cornerRadius = CLAY_CORNER_RADIUS(10),
        .clip = { .vertical = true, .childOffset = Clay_GetScrollOffset() }
    }) {
        // child elements
    }
}

CLAY_AUTO_ID()

A version of the core CLAY() element creation macro that generates an ID automatically instead of requiring it as the first argument.

Note that under the hood this ID is generated in the same way as CLAY_ID_LOCAL(), which is based on the element's position in the hierarchy, and may chance between layout calls if elements are added / removed from the hierarchy before the element is defined. As a result, for transitions & retained mode backends to work correctly, IDs should be specified.

// Note that CLAY_AUTO_ID only takes one argument: the configuration
CLAY_AUTO_ID({ .layout = { .padding = CLAY_PADDING_ALL(16) } }) {
    // A nested child element
    CLAY_AUTO_ID({ .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .childGap = 16 } }) {
        // Children laid out top to bottom with a 16 px gap between them
    }
    // A vertical scrolling container with a colored background
    CLAY_AUTO_ID({
        .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .childGap = 16 },
        .backgroundColor = { 200, 200, 100, 255 },
        .cornerRadius = CLAY_CORNER_RADIUS(10),
        .clip = { .vertical = true, .childOffset = Clay_GetScrollOffset() }
    }) {
        // child elements
    }
}

CLAY_TEXT()

Usage

CLAY_TEXT(Clay_String textContents, Clay_TextElementConfig *textConfig);

Lifecycle

Clay_BeginLayout() -> CLAY_TEXT() -> Clay_EndLayout()

Notes

TEXT is a measured, auto-wrapped text element. It uses Clay_TextElementConfig to configure text specific options.

Note that Clay_TextElementConfig uses uint32_t fontId. Font ID to font asset mapping is managed in user code and passed to render commands.

Struct API (Pseudocode)

// CLAY_TEXT(text, { .member = value }) supports these options
Clay_TextElementConfig {
    Clay_Color textColor {
        float r; float g; float b; float a;
    };
    uint16_t fontId;
    uint16_t fontSize;
    uint16_t letterSpacing;
    uint16_t lineHeight;
    Clay_TextElementConfigWrapMode wrapMode {
        CLAY_TEXT_WRAP_WORDS (default),
        CLAY_TEXT_WRAP_NEWLINES,
        CLAY_TEXT_WRAP_NONE,
    };
    Clay_TextAlignment textAlignment {
        CLAY_TEXT_ALIGN_LEFT (default),
        CLAY_TEXT_ALIGN_CENTER,
        CLAY_TEXT_ALIGN_RIGHT,
    };
    void *userData;
};

Fields

.textColor

CLAY_TEXT(text, { .textColor = {120, 120, 120, 255} })

Uses Clay_Color. Conventionally accepts rgba float values between 0 and 255, but interpretation is left up to the renderer and does not affect layout.

.fontId

CLAY_TEXT(text, { .fontId = FONT_ID_LATO })

It's up to the user to load fonts and create a mapping from fontId to a font that can be measured and rendered.

.fontSize

CLAY_TEXT(text, { .fontSize = 16 })

Font size is generally thought of as x pixels tall, but interpretation is left up to the user & renderer.

.letterSpacing

CLAY_TEXT(text, { .letterSpacing = 1 })

.letterSpacing results in horizontal white space between individual rendered characters.

.lineHeight

CLAY_TEXT(text, { .lineHeight = 20 })

.lineHeight - when non zero - forcibly sets the height of each wrapped line of text to .lineheight pixels tall. Will affect the layout of both parents and siblings. A value of 0 will use the measured height of the font.

.wrapMode

CLAY_TEXT(text, { .wrapMode = CLAY_TEXT_WRAP_NONE })

.wrapMode specifies under what conditions text should wrap.

Available options are:

CLAY_TEXT_WRAP_WORDS (default) - Text will wrap on whitespace characters as container width shrinks, preserving whole words.
CLAY_TEXT_WRAP_NEWLINES - will only wrap when encountering newline characters.
CLAY_TEXT_WRAP_NONE - Text will never wrap even if its container is compressed beyond the text measured width.

.textAlignment

CLAY_TEXT(text, { .textAlignment = CLAY_TEXT_ALIGN_CENTER })

.textAlignment controls how wrapping text lines are aligned. If you want to control the alignment of single lines of text, instead use the childAlignment property of the parent layout element.

Available options are:

CLAY_TEXT_ALIGN_LEFT (default)
CLAY_TEXT_ALIGN_CENTER
CLAY_TEXT_ALIGN_RIGHT

Examples

// Define a font somewhere in your code
const uint32_t FONT_ID_LATO = 3;
// ..
CLAY_TEXT(CLAY_STRING("John Smith"), { .fontId = FONT_ID_LATO, .fontSize = 24, .textColor = {255, 0, 0, 255} });
// Rendering example
Font fontToUse = LoadedFonts[renderCommand->renderData.text.fontId];

Rendering

Element is subject to culling. Otherwise, multiple Clay_RenderCommands with commandType = CLAY_RENDER_COMMAND_TYPE_TEXT may be created, one for each wrapped line of text.

Clay_RenderCommand.textContent will be populated with a Clay_String slice of the original string passed in (i.e. wrapping doesn't reallocate, it just returns a Clay_String pointing to the start of the new line with a length)

CLAY_ID()

Clay_ElementId CLAY_ID(STRING_LITERAL idString)

CLAY_ID() is used to generate and attach a Clay_ElementId to a layout element during declaration.

Note this macro only works with String literals and won't compile if used with a char* variable. To use a heap allocated char* string as an ID, use CLAY_SID.

To regenerate the same ID outside of layout declaration when using utility functions such as Clay_PointerOver, use the Clay_GetElementId function.

Examples

// Tag a button with the Id "Button"
CLAY(CLAY_ID("Button"), {
    .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .sizing = { .width = CLAY_SIZING_GROW(0) }, .padding = CLAY_PADDING_ALL(16), .childGap = 16 }
}) {
    // ...children
}

// Later on outside of layout code
bool buttonIsHovered = Clay_PointerOver(Clay_GetElementId("Button"));
if (buttonIsHovered && leftMouseButtonPressed) {
    // ... do some click handling
}

CLAY_SID()

Clay_ElementId CLAY_SID(Clay_String idString)

A version of CLAY_ID that can be used with heap allocated char * data. The underlying char data will not be copied internally and should live until at least the next frame.

CLAY_IDI()

Clay_ElementId CLAY_IDI(STRING_LITERAL idString, int32_t index)

An offset version of CLAY_ID. Generates a Clay_ElementId string id from the provided char *label, combined with the int index.

Used for generating ids for sequential elements (such as in a for loop) without having to construct dynamic strings at runtime.

Note this macro only works with String literals and won't compile if used with a char* variable. To use a heap allocated char* string as an ID, use CLAY_SIDI.

CLAY_SIDI()

Clay_ElementId CLAY_SIDI(Clay_String idString, int32_t index)

A version of CLAY_IDI that can be used with heap allocated char * data. The underlying char data will not be copied internally and should live until at least the next frame.

CLAY_ID_LOCAL()

Usage

Clay_ElementId CLAY_ID_LOCAL(STRING_LITERAL idString)

Lifecycle

Clay_BeginLayout() -> CLAY( -> CLAY_ID_LOCAL() -> ) -> Clay_EndLayout()

Notes

CLAY_ID_LOCAL() is used to generate and attach a Clay_ElementId to a layout element during declaration.

Unlike CLAY_ID which needs to be globally unique, a local ID is based on the ID of it's parent and only needs to be unique among its siblings.

As a result, local id is suitable for use in reusable components and loops.

Note this macro only works with String literals and won't compile if used with a char* variable. To use a heap allocated char* string as an ID, use CLAY_SID_LOCAL.

Examples

void RenderHeaderButton(ButtonData button) {
    CLAY({
        .id = CLAY_ID_LOCAL("HeaderButton"),
        .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .sizing = { .width = CLAY_SIZING_GROW(0) }, .padding = CLAY_PADDING_ALL(16), .childGap = 16 }
    }) {
        // ...children
    }
}

for (int i = 0; i < headerButtons.length; i++) {
    RenderHeaderButton(headerButtons.items[i]);
}

CLAY_SID_LOCAL()

Clay_ElementId CLAY_SID_LOCAL(Clay_String idString)

A version of CLAY_ID_LOCAL that can be used with heap allocated char * data. The underlying char data will not be copied internally and should live until at least the next frame.

CLAY_IDI_LOCAL()

Clay_ElementId CLAY_IDI_LOCAL(STRING_LITERAL idString, int32_t index)

An offset version of CLAY_ID_LOCAL. Generates a Clay_ElementId string id from the provided char *label, combined with the int index.

Used for generating ids for sequential elements (such as in a for loop) without having to construct dynamic strings at runtime.

Note this macro only works with String literals and won't compile if used with a char* variable. To use a heap allocated char* string as an ID, use CLAY_SIDI_LOCAL.

CLAY_SIDI_LOCAL()

Clay_ElementId CLAY_SIDI_LOCAL(Clay_String idString, int32_t index)

A version of CLAY_IDI_LOCAL that can be used with heap allocated char * data. The underlying char data will not be copied internally and should live until at least the next frame.

Data Structures & Definitions

Clay_ElementDeclaration

The Clay_ElementDeclaration struct is the only argument to the CLAY() macro and provides configuration options for layout elements.

typedef struct {
    Clay_LayoutConfig layout;
    Clay_Color backgroundColor;
    Clay_CornerRadius cornerRadius;
    Clay_AspectRatioElementConfig aspectRatio;
    Clay_ImageElementConfig image;
    Clay_FloatingElementConfig floating;
    Clay_CustomElementConfig custom;
    Clay_ClipElementConfig clip;
    Clay_BorderElementConfig border;
    void *userData;
} Clay_ElementDeclaration;

Fields

.layout - Clay_LayoutConfig

CLAY(CLAY_ID("Element"), { .layout = { .padding = { 16, 16, 12, 12 }, .layoutDirection = CLAY_TOP_TO_BOTTOM } })

Uses Clay_LayoutConfig. Controls various settings related to layout, which can be thought of as "the size and position of this element and its children".

.backgroundColor - Clay_Color

CLAY(CLAY_ID("Element"), { .backgroundColor = { 120, 120, 120, 255 } } })

Uses Clay_Color. Conventionally accepts rgba float values between 0 and 255, but interpretation is left up to the renderer and does not affect layout.

.overlayColor - Clay_Color

CLAY(CLAY_ID("Element"), { .overlayColor = { 255, 120, 120, 255 } } })

Uses Clay_Color. Conventionally accepts rgba float values between 0 and 255, but interpretation is left up to the renderer and does not affect layout.

Specifying .overlayColor will cause two new render commands to be emitted: OVERLAY_COLOR_BEGIN immediately, and OVERLAY_COLOR_END after this elements subtree has been emitted.

This instructs the renderer to begin applying a color overlay to this element, and all child elements. The color overlay effect is similar to glsl's mix(source, target, alpha). As a result, the strength of the color overlay is controlled by the .a channel of .overlayColor. Zero alpha means "all child colors remain the same", full alpha means "all child colours are replaced by the RGB overlayColor", and values in between mean "lerp from the child color to the overlay color by the alpha".

This can be used as a cheap replacement for alpha / opacity to "fade in / out", by applying (and potentially transitioning) an overlay color to the same color as the background with full alpha.

.cornerRadius - Clay_CornerRadius

CLAY(CLAY_ID("Element"), { .cornerRadius = { .topLeft = 16, .topRight = 16, .bottomLeft = 16, .bottomRight = 16 } })

Defines the radius in pixels for the arc of rectangle corners (0 is square, rectangle.width / 2 is circular).

Note that the CLAY_CORNER_RADIUS(radius) function-like macro is available to provide short hand for setting all four corner radii to the same value. e.g. CLAY_BORDER({ .cornerRadius = CLAY_CORNER_RADIUS(10) })

.aspectRatio - Clay_AspectRatioElementConfig

CLAY(CLAY_ID("Element"), { .aspectRatio = 1 })

Uses Clay_AspectRatioElementConfig. Configures the element as an aspect ratio scaling element. Especially useful for rendering images, but can also be used to enforce a fixed width / height ratio of other elements.

.image - Clay_ImageElementConfig

CLAY(CLAY_ID("Element"), { .image = { .imageData = &myImage } })

Uses Clay_ImageElementConfig. Configures the element as an image element. Causes a render command with type IMAGE to be emitted.

.floating - Clay_FloatingElementConfig

CLAY(CLAY_ID("Element"), { .floating = { .attachTo = CLAY_ATTACH_TO_PARENT } })

Uses Clay_FloatingElementConfig. Configures the element as an floating element, which allows it to stack "in front" and "on top" of other elements without affecting sibling or parent size or position.

.custom - Clay_CustomElementConfig

CLAY(CLAY_ID("Element"), { .custom = { .customData = &my3DModel } })

Uses Clay_CustomElementConfig. Configures the element as a custom element, which allows you to pass custom data through to the renderer. Causes a render command with type CUSTOM to be emitted.

.clip - Clay_ClipElementConfig

CLAY(CLAY_ID("Element"), { .clip = { .vertical = true, .childOffset = Clay_GetScrollOffset() } })

Uses Clay_ClipElementConfig. Configures the element as a clip element, which causes child elements to be clipped / masked if they overflow, and together with the functions listed in Scrolling Elements enables scrolling of child contents.

.border - Clay_BorderElementConfig

CLAY(CLAY_ID("Element"), { .border = { .width = { .left = 5 }, .color = COLOR_BLUE } })

Uses Clay_BorderElementConfig. Configures the element as a border element, which instructs the renderer to draw coloured border lines along the perimeter of this element's bounding box. Causes a render command with type BORDER to be emitted.

.userData - void *

CLAY(CLAY_ID("Element"), { .userData = &extraData })

Transparently passes a pointer through to the corresponding Clay_RenderCommandss generated by this element.

Examples

// Declare a reusable rectangle config, with a purple color and 10px rounded corners
Clay_RectangleElementConfig rectangleConfig = (Clay_RectangleElementConfig) { .color = { 200, 200, 100, 255 }, .cornerRadius = CLAY_CORNER_RADIUS(10) };
// Declare a rectangle element using a reusable config
CLAY(CLAY_ID("Box"), rectangleConfig) {}
// Declare a retangle element using an inline config
CLAY(CLAY_ID("BoxInline"), { .color = { 200, 200, 100, 255 }, .cornerRadius = CLAY_CORNER_RADIUS(10) })) {
    // child elements
}
// Declare a scrolling container with a colored background
CLAY(CLAY_ID("ScrollingContainer"), { 
    .backgroundColor = { 200, 200, 100, 255 }, 
    .cornerRadius = CLAY_CORNER_RADIUS(10)
    .clip = { .vertical = true, .childOffset = Clay_GetScrollOffset() }
) {
    // child elements
}

Element is subject to culling. Otherwise, a single Clay_RenderCommands with commandType = CLAY_RENDER_COMMAND_TYPE_RECTANGLE will be created, with renderCommand->renderData.rectangle containing a pointer to the element's Clay_RectangleElementConfig.

Clay_LayoutConfig

Clay_LayoutConfig is used for configuring layout options (i.e. options that affect the final position and size of an element, its parents, siblings, and children)

Struct API (Pseudocode)

// CLAY({ .layout = { ...fields } }) supports these options
Clay_LayoutConfig {
    Clay_LayoutDirection layoutDirection = CLAY_LEFT_TO_RIGHT (default) | CLAY_TOP_TO_BOTTOM;
    Clay_Padding padding {
        u16 left; u16 right; u16 top; u16 bottom; 
    };
    uint16_t childGap;
    Clay_ChildAlignment childAlignment {
        .x = CLAY_ALIGN_X_LEFT (default) | CLAY_ALIGN_X_CENTER | CLAY_ALIGN_X_RIGHT;
        .y = CLAY_ALIGN_Y_TOP (default) | CLAY_ALIGN_Y_CENTER | CLAY_ALIGN_Y_BOTTOM;
    };
    Clay_Sizing sizing { // Recommended to use the provided macros here - see #sizing for more in depth explanation
        .width = CLAY_SIZING_FIT(float min, float max) (default) | CLAY_SIZING_GROW(float min, float max) | CLAY_SIZING_FIXED(float width) | CLAY_SIZING_PERCENT(float percent)
        .height = CLAY_SIZING_FIT(float min, float max) (default) | CLAY_SIZING_GROW(float min, float max) | CLAY_SIZING_FIXED(float height) | CLAY_SIZING_PERCENT(float percent)
    }; // See CLAY_SIZING_GROW() etc for more details
};

Fields

.layoutDirection - Clay_LayoutDirection

CLAY(CLAY_ID("Element"), { .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM } })

Controls the axis / direction in which child elements are laid out. Available options are CLAY_LEFT_TO_RIGHT (default) and CLAY_TOP_TO_BOTTOM.

Did you know that "left to right" and "top to bottom" both have 13 letters?

.padding - Clay_Padding

CLAY(CLAY_ID("Element"), { .layout = { .padding = { .left = 16, .right = 16, .top = 8, .bottom = 8 } } })

Controls white-space "padding" around the outside of child elements.

.childGap - uint16_t

CLAY(CLAY_ID("Element"), { .layout = { .childGap = 16 } })

Controls the white-space between child elements as they are laid out. When .layoutDirection is CLAY_LEFT_TO_RIGHT (default), this will be horizontal space, whereas for CLAY_TOP_TO_BOTTOM it will be vertical space.

.childAlignment - Clay_ChildAlignment

CLAY(CLAY_ID("Element"), { .layout = { .childAlignment = { .x = CLAY_ALIGN_X_LEFT, .y = CLAY_ALIGN_Y_CENTER } } })

Controls the alignment of children relative to the height and width of the parent container. Available options are:

.x = CLAY_ALIGN_X_LEFT (default) | CLAY_ALIGN_X_CENTER | CLAY_ALIGN_X_RIGHT;
.y = CLAY_ALIGN_Y_TOP (default) | CLAY_ALIGN_Y_CENTER | CLAY_ALIGN_Y_BOTTOM;

.sizing - Clay_Sizing

CLAY(CLAY_ID("Element"), { .layout = { .sizing = { .width = CLAY_SIZING_FIXED(300), .height = CLAY_SIZING_PERCENT(0.5) } } })

Controls how final width and height of element are calculated. The same configurations are available for both the .width and .height axis. There are several options:

CLAY_SIZING_FIT(float min, float max) (default) - The element will be sized to fit its children (plus padding and gaps), up to max. If max is left unspecified, it will default to FLOAT_MAX. When elements are compressed to fit into a smaller parent, this element will not shrink below min.
CLAY_SIZING_GROW(float min, float max) - The element will grow to fill available space in its parent, up to max. If max is left unspecified, it will default to FLOAT_MAX. When elements are compressed to fit into a smaller parent, this element will not shrink below min.
CLAY_SIZING_FIXED(float fixed) - The final size will always be exactly the provided fixed value. Shorthand for CLAY_SIZING_FIT(fixed, fixed)
CLAY_SIZING_PERCENT(float percent) - Final size will be a percentage of parent size, minus padding and child gaps. percent is assumed to be a float between 0 and 1.

Example Usage

CLAY(CLAY_ID("Button"), { .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM, .sizing = { .width = CLAY_SIZING_GROW(0) }, .padding = CLAY_PADDING_ALL(16, .childGap = 16) } }) {
    // Children will be laid out vertically with 16px of padding around and between
}

Clay_ImageElementConfig

Usage

CLAY(CLAY_ID("Element"), { .image = { ...image config } }) {}

Clay_ImageElementConfig configures a clay element to render an image as its background.

Struct API (Pseudocode)

Clay_ImageElementConfig {
    void * imageData;
};

Fields

.imageData - void *

CLAY(CLAY_ID("Image"), { .image = { .imageData = &myImage } }) {}

.imageData is a generic void pointer that can be used to pass through image data to the renderer.

// Load an image somewhere in your code
YourImage profilePicture = LoadYourImage("profilePicture.png");
// Note that when rendering, .imageData will be void* type.
CLAY(CLAY_ID("Image"), { .image = { .imageData = &profilePicture } }) {}

Examples

// Load an image somewhere in your code
YourImage profilePicture = LoadYourImage("profilePicture.png");
// Declare a reusable image config
Clay_ImageElementConfig imageConfig = (Clay_ImageElementConfig) { .imageData = &profilePicture };
// Declare an image element using a reusable config
CLAY(CLAY_ID("Image"), { .image = imageConfig }) {}
// Declare an image element using an inline config
CLAY(CLAY_ID("ImageInline"), { .image = { .imageData = &profilePicture }, .aspectRatio = 16.0 / 9.0 }) {}
// Rendering example
YourImage *imageToRender = renderCommand->elementConfig.imageElementConfig->imageData;

Rendering

Element is subject to culling. Otherwise, a single Clay_RenderCommands with commandType = CLAY_RENDER_COMMAND_TYPE_IMAGE will be created. The user will need to access renderCommand->renderData.image.imageData to retrieve image data referenced during layout creation. It's also up to the user to decide how / if they wish to blend renderCommand->renderData.image.backgroundColor with the image.

Clay_AspectRatioElementConfig

Usage

CLAY(CLAY_ID("Aspect"), { .aspectRatio = 16.0 / 9.0 }) {}

Clay_AspectRatioElementConfig configures a clay element to enforce a fixed width / height ratio in its final dimensions. Mostly used for image elements, but can also be used for non image elements.

Struct API (Pseudocode)

Clay_AspectRatioElementConfig {
    float aspectRatio;
};

Fields

.aspectRatio - float

CLAY(CLAY_ID("Aspect"), { .aspectRatio = { .aspectRatio = 16.0 / 9.0 } }) {}

or alternatively, as C will automatically pass the value to the first nested struct field:

CLAY(CLAY_ID("Aspect"), { .aspectRatio = 16.0 / 9.0 }) {}

Examples

// Load an image somewhere in your code
YourImage profilePicture = LoadYourImage("profilePicture.png");
// Declare an image element that will grow along the X axis while maintaining its original aspect ratio
CLAY(CLAY_ID("ProfilePicture"), {
    .layout = { .width = CLAY_SIZING_GROW() },
    .aspectRatio = profilePicture.width / profilePicture.height,
    .image = { .imageData = &profilePicture },
}) {}

Clay_ImageElementConfig

Usage

CLAY(CLAY_ID("Image"), { .image = { ...image config } }) {}

Clay_ImageElementConfig configures a clay element to render an image as its background.

Struct API (Pseudocode)

Clay_ImageElementConfig {
    void * imageData;
};

Fields

.imageData - void *

CLAY(CLAY_ID("Image"), { .image = { .imageData = &myImage } }) {}

.imageData is a generic void pointer that can be used to pass through image data to the renderer.

// Load an image somewhere in your code
YourImage profilePicture = LoadYourImage("profilePicture.png");
// Note that when rendering, .imageData will be void* type.
CLAY(CLAY_ID("Image"), { .image = { .imageData = &profilePicture } }) {}

Note: for an image to maintain its original aspect ratio when using dynamic scaling, the .aspectRatio config option must be used.

Examples

// Load an image somewhere in your code
YourImage profilePicture = LoadYourImage("profilePicture.png");
// Declare a reusable image config
Clay_ImageElementConfig imageConfig = (Clay_ImageElementConfig) { .imageData = &profilePicture };
// Declare an image element using a reusable config
CLAY(CLAY_ID("Image"), { .image = imageConfig }) {}
// Declare an image element using an inline config
CLAY(CLAY_ID("ImageInline"), { .image = { .imageData = &profilePicture }, .aspectRatio = 16.0 / 9.0 }) {}
// Rendering example
YourImage *imageToRender = renderCommand->elementConfig.imageElementConfig->imageData;

Rendering

Clay_ClipElementConfig

Usage

CLAY(CLAY_ID("ScrollBox"), { .clip = { ...clip config } }) {}

Notes

Clay_ClipElementConfig configures the element as a clipping container, enabling masking of children that extend beyond its boundaries.

Note: In order to process scrolling based on pointer position and mouse wheel or touch interactions, you must call Clay_SetPointerState() and Clay_UpdateScrollContainers() before calling BeginLayout.

Struct Definition (Pseudocode)

Clay_ClipElementConfig {
    bool horizontal;
    bool vertical;
    Clay_Vector2 childOffset;
};

Fields

.horizontal - bool

CLAY(CLAY_ID("HorizontalScroll"), { .clip = { .horizontal = true } })

Enables or disables horizontal clipping for this container element.

.vertical - bool

CLAY(LAY_ID("VerticalScroll"), { .clip = { .vertical = true } })

Enables or disables vertical clipping for this container element.

.childOffset - Clay_Vector2

CLAY(LAY_ID("VerticalScroll"), { .clip = { .vertical = true, .childOffset = Clay_GetScrollOffset() } })

Controls the x/y offset for child elements of this clip container. Used to control scrolling. You can either provide the vector manually if you want to manage scrolling yourself, or you can use the built in Clay_GetScrollOffset function which will manage scrolling for you automatically.

Rendering

Enabling clip for an element will result in two additional render commands:

commandType = CLAY_RENDER_COMMAND_TYPE_SCISSOR_START, which should create a rectangle mask with its boundingBox and is not subject to culling
commandType = CLAY_RENDER_COMMAND_TYPE_SCISSOR_END, which disables the previous rectangle mask and is not subject to culling

Examples

CLAY(CLAY_ID("ScrollOuter"), { .clip = { .vertical = true } }) {
    // Create child content with a fixed height of 5000
    CLAY(CLAY_ID("ScrollInner"), { .layout = { .sizing = { .height = CLAY_SIZING_FIXED(5000) } } }) {}
}

Clay_BorderElementConfig

Usage

CLAY(CLAY_ID("Border"), { .border = { ...border config } }) {}

Notes

Clay_BorderElementConfig adds borders to the edges or between the children of elements. It uses Clay_BorderElementConfig to configure border specific options.

Struct Definition (Pseudocode)

typedef struct Clay_BorderElementConfig
{
    Clay_Color color {
        float r; float g; float b; float a;
    };
    Clay_BorderWidth width {
        uint16_t left;
        uint16_t right;
        uint16_t top;
        uint16_t bottom;
        uint16_t betweenChildren;  
    };
} Clay_BorderElementConfig;

Fields

.color - Clay_Color

CLAY(CLAY_ID("Border"), { .border = { .color = { 255, 0, 0, 255 } } })

Uses Clay_Color. Specifies the shared color for all borders configured by this element. Conventionally accepts rgba float values between 0 and 255, but interpretation is left up to the renderer and does not affect layout.

.width - Clay_BorderWidth

CLAY(CLAY_ID("Border"), { .border = { .width = { .left = 2, .right = 10 } } })

Indicates to the renderer that a border of .color should be draw at the specified edges of the bounding box, inset and overlapping the box contents by .width.

This means that border configuration does not affect layout, as the width of the border doesn't contribute to the total container width or layout position. Border containers with zero padding will be drawn over the top of child elements.

Note:

.width.betweenChildren

CLAY(CLAY_ID("Border"), { .border = { .width = { .betweenChildren = 2 } }, .color = COLOR_RED })

Configures the width and color of borders to be drawn between children. These borders will be vertical lines if the parent uses .layoutDirection = CLAY_LEFT_TO_RIGHT and horizontal lines if the parent uses CLAY_TOP_TO_BOTTOM. Unlike .left, .top etc, this option will generate additional rectangle render commands representing the borders between children. As a result, the renderer does not need to specifically implement rendering for these border elements.

Examples

// 300x300 container with a 1px red border around all the edges
CLAY(CLAY_ID("OuterBorder"), {
    .layout = { .sizing = { .width = CLAY_SIZING_FIXED(300), .height = CLAY_SIZING_FIXED(300) } },
    .border = { .width = { 1, 1, 1, 1, 0 }, .color = COLOR_RED }
}) {
    // ...
}

// Container with a 3px yellow bottom border
CLAY(CLAY_ID("OuterBorder"), {
    .border = { .width = { .bottom = 3 }, .color = COLOR_YELLOW }
}) {
    // ...
}

// Container with a 5px curved border around the edges, and a 5px blue border between all children laid out top to bottom
CLAY(CLAY_ID("OuterBorder"), {
    .layout = { .layoutDirection = CLAY_TOP_TO_BOTTOM },
    .border = { .width = { 5, 5, 5, 5, 5 }, .color = COLOR_BLUE }
}) {
    // Child
    // -- 5px blue border will be here --
    // Child
    // -- 5px blue border will be here --
    // Child
}

Rendering

Element is subject to culling. Otherwise, a single Clay_RenderCommand with commandType = CLAY_RENDER_COMMAND_TYPE_BORDER representing the container will be created. Rendering of borders and rounded corners is left up to the user. See the provided Raylib Renderer for examples of how to draw borders using line and curve primitives.

Clay_FloatingElementConfig

Usage

CLAY(CLAY_ID("Floating"), { .floating = { ...floating config } }) {}

Notes

Floating Elements defines an element that "floats" above other content. Typical use-cases include tooltips and modals.

Floating containers:

With the default configuration, attach to the top left corner of their "parent"
Don't affect the width and height of their parent
Don't affect the positioning of sibling elements
Depending on their z-index can appear above or below other elements, partially or completely occluding them
Apart from positioning, function just like standard elements - including expanding to fit their children, etc.

The easiest mental model to use when thinking about floating containers is that they are a completely separate UI hierarchy, attached to a specific x,y point on their "parent".

Floating elements uses Clay_FloatingElementConfig to configure specific options.

Struct Definition (Pseudocode)

Clay_FloatingElementConfig {
    Clay_Vector2 offset {
        float x, float y
    };
    Clay_Dimensions expand {
        float width, float height
    };
    uint32_t parentId;
    int16_t zIndex;
    Clay_FloatingAttachPoints attachPoints {
        .element = CLAY_ATTACH_POINT_LEFT_TOP (default) | CLAY_ATTACH_POINT_LEFT_CENTER | CLAY_ATTACH_POINT_LEFT_BOTTOM | CLAY_ATTACH_POINT_CENTER_TOP | CLAY_ATTACH_POINT_CENTER_CENTER | CLAY_ATTACH_POINT_CENTER_BOTTOM | CLAY_ATTACH_POINT_RIGHT_TOP | CLAY_ATTACH_POINT_RIGHT_CENTER | CLAY_ATTACH_POINT_RIGHT_BOTTOM
        .parent = CLAY_ATTACH_POINT_LEFT_TOP (default) | CLAY_ATTACH_POINT_LEFT_CENTER | CLAY_ATTACH_POINT_LEFT_BOTTOM | CLAY_ATTACH_POINT_CENTER_TOP | CLAY_ATTACH_POINT_CENTER_CENTER | CLAY_ATTACH_POINT_CENTER_BOTTOM | CLAY_ATTACH_POINT_RIGHT_TOP | CLAY_ATTACH_POINT_RIGHT_CENTER | CLAY_ATTACH_POINT_RIGHT_BOTTOM
    };
    Clay_PointerCaptureMode pointerCaptureMode {
        CLAY_POINTER_CAPTURE_MODE_CAPTURE (default),
        CLAY_POINTER_CAPTURE_MODE_PASSTHROUGH
    };
    Clay_FloatingAttachToElement attachTo {
        CLAY_ATTACH_TO_NONE (default),
        CLAY_ATTACH_TO_PARENT,
        CLAY_ATTACH_TO_ELEMENT_WITH_ID,
        CLAY_ATTACH_TO_ROOT,
    };
    Clay_FloatingClipToElement clipTo {
        CLAY_CLIP_TO_NONE (default),
        CLAY_CLIP_TO_ATTACHED_PARENT,
    };
};

Fields

.offset - Clay_Vector2

CLAY(CLAY_ID("Floating"), { .floating = { .offset = { -24, -24 } } })

Used to apply a position offset to the floating container after all other layout has been calculated.

.expand - Clay_Dimensions

CLAY(CLAY_ID("Floating"), { .floating = { .expand = { 16, 16 } } })

Used to expand the width and height of the floating container before laying out child elements.

.zIndex - int16_t

CLAY(CLAY_ID("Floating"), { .floating = { .zIndex = 1 } })

All floating elements (as well as their entire child hierarchies) will be sorted by .zIndex order before being converted to render commands. If render commands are drawn in order, elements with higher .zIndex values will be drawn on top.

.parentId - uint32_t

CLAY(CLAY_ID("Floating"), { .floating = { .parentId = Clay_GetElementId("HeaderButton").id } })

By default, floating containers will "attach" to the parent element that they are declared inside. However, there are cases where this limitation could cause significant performance or ergonomics problems. .parentId allows you to specify a CLAY_ID().id to attach the floating container to. The parent element with the matching id can be declared anywhere in the hierarchy, it doesn't need to be declared before or after the floating container in particular.

Consider the following case:

// Load an image somewhere in your code
CLAY(CLAY_IDI("SidebarButton", 1), { }) {
    // .. some button contents
    if (tooltip.attachedButtonIndex == 1) {
        CLAY(CLAY_ID("OptionTooltip"), { /* floating config... */ })
    }
}
CLAY(CLAY_IDI("SidebarButton", 2), { }) {
    // .. some button contents
    if (tooltip.attachedButtonIndex == 2) {
        CLAY(CLAY_ID("OptionTooltip"), { /* floating config... */ })
    }
}
CLAY(CLAY_IDI("SidebarButton", 3), { }) {
    // .. some button contents
    if (tooltip.attachedButtonIndex == 3) {
        CLAY(CLAY_ID("OptionTooltip"), { /* floating config... */ })
    }
}
CLAY(CLAY_IDI("SidebarButton", 4), { }) {
    // .. some button contents
    if (tooltip.attachedButtonIndex == 4) {
        CLAY(CLAY_ID("OptionTooltip"), { /* floating config... */ })
    }
}
CLAY(CLAY_IDI("SidebarButton", 5), { }) {
    // .. some button contents
    if (tooltip.attachedButtonIndex == 5) {
        CLAY(CLAY_ID("OptionTooltip"), { /* floating config... */ })
    }
}

The definition of the above UI is significantly polluted by the need to conditionally render floating tooltips as a child of many possible elements. The alternative, using parentId, looks like this:

// Load an image somewhere in your code
CLAY(CLAY_IDI("SidebarButton", 1), { }) {
    // .. some button contents
}
CLAY(CLAY_IDI("SidebarButton", 2), { }) {
    // .. some button contents
}
CLAY(CLAY_IDI("SidebarButton", 3), { }) {
    // .. some button contents
}
CLAY(CLAY_IDI("SidebarButton", 4), { }) {
    // .. some button contents
}
CLAY(CLAY_IDI("SidebarButton", 5), { }) {
    // .. some button contents
}

// Any other point in the hierarchy
CLAY(CLAY_ID("OptionTooltip"), { .floating = { .attachTo = CLAY_ATTACH_TO_ELEMENT_WITH_ID, .parentId = CLAY_IDI("SidebarButton", tooltip.attachedButtonIndex).id }) {
    // Tooltip contents...
}

.attachPoints - Clay_FloatingAttachPoints

CLAY(CLAY_ID("Floating"), { .floating = { .attachPoints = { .element = CLAY_ATTACH_POINT_LEFT_CENTER, .parent = CLAY_ATTACH_POINT_RIGHT_TOP } } }) {}

In terms of positioning the floating container, .attachPoints specifies

The point on the floating container (.element)
The point on the parent element that it "attaches" to (.parent)

You can mentally visualise this as finding a point on the floating container, then finding a point on the parent, and lining them up over the top of one another.

For example:

"Attach the LEFT_BOTTOM of the floating container to the CENTER_CENTER of the parent"

CLAY(CLAY_ID("Floating"), { .floating = { .attachPoints = { .element = CLAY_ATTACH_POINT_LEFT_BOTTOM, .parent = CLAY_ATTACH_POINT_CENTER_CENTER } } });

.pointerCaptureMode - Clay_PointerCaptureMode

CLAY({ .floating = { .pointerCaptureMode = CLAY_POINTER_CAPTURE_MODE_CAPTURE } })

Controls whether pointer events like hover and click should pass through to content underneath this floating element, or whether the pointer should be "captured" by this floating element. Defaults to CLAY_POINTER_CAPTURE_MODE_CAPTURE.

.clipTo - Clay_FloatingClipToElement

CLAY({ .floating = { .clipTo = CLAY_CLIP_TO_ATTACHED_PARENT } })

By default, floating elements will appear with a z-order above their parent, and won't be clipped by a .clip defined on that parent. To clip floating elements by their parents' clip rectangle, use .clipTo = CLAY_CLIP_TO_ATTACHED_PARENT.

typedef enum {
    CLAY_CLIP_TO_NONE,
    CLAY_CLIP_TO_ATTACHED_PARENT,
} Clay_FloatingClipToElement;

Examples

// Horizontal container with three option buttons
CLAY(CLAY_ID("OptionsList"), { .layout = { childGap = 16 } }) {
    CLAY(CLAY_IDI("Option", 1), { .layout = { padding = CLAY_PADDING_ALL(16)), .backgroundColor = COLOR_BLUE } }) {
        CLAY_TEXT(CLAY_STRING("Option 1"), {});
    }
    CLAY(CLAY_IDI("Option", 2), { .layout = { padding = CLAY_PADDING_ALL(16)), .backgroundColor = COLOR_BLUE } }) {
        CLAY_TEXT(CLAY_STRING("Option 2"), {});
        // Floating tooltip will attach above the "Option 2" container and not affect widths or positions of other elements
        CLAY(CLAY_ID("OptionTooltip"), { .floating = { .zIndex = 1, .attachPoints = { .element = CLAY_ATTACH_POINT_CENTER_BOTTOM, .parent = CLAY_ATTACH_POINT_CENTER_TOP } } }) {
            CLAY_TEXT(CLAY_STRING("Most popular!"), {});
        }
    }
    CLAY(CLAY_IDI("Option", 3), { .layout = { padding = CLAY_PADDING_ALL(16)), .backgroundColor = COLOR_BLUE } }) {
        CLAY_TEXT(CLAY_STRING("Option 3"), {});
    }
}

// Floating containers can also be declared elsewhere in a layout, to avoid branching or polluting other UI
for (int i = 0; i < 1000; i++) {
    CLAY(CLAY_IDI("Option", i + 1), { }) {
        // ...
    }
}
// Note the use of "parentId".
// Floating tooltip will attach above the "Option 2" container and not affect widths or positions of other elements
CLAY(CLAY_ID("OptionTooltip"), { .floating = { .parentId = CLAY_IDI("Option", 2).id, .zIndex = 1, .attachPoints = { .element = CLAY_ATTACH_POINT_CENTER_BOTTOM, .parent = CLAY_ATTACH_POINT_TOP_CENTER } } }) {
    CLAY_TEXT(CLAY_STRING("Most popular!"), {});
}

When using .parentId, the floating container can be declared anywhere after BeginLayout and before EndLayout. The target element matching the .parentId doesn't need to exist when Clay_FloatingElementConfig is used.

Rendering

Clay_FloatingElementConfig will not generate any specific render commands.

Clay_CustomElementConfig

Usage

CLAY(CLAY_ID("Custom"), { .custom = { .customData = &something } }) {}

Notes

Clay_CustomElementConfig allows the user to pass custom data to the renderer.

Struct Definition (Pseudocode)

typedef struct
{
    void * customData;
} Clay_CustomElementConfig;

Fields

.customData - void *

CLAY({ .custom = { .customData = &myCustomData } })

.customData is a generic void pointer that can be used to pass through custom data to the renderer.

Examples

#include "clay.h"

typedef enum {
    CUSTOM_ELEMENT_TYPE_MODEL,
    CUSTOM_ELEMENT_TYPE_VIDEO
} CustomElementType;

// A rough example of how you could handle laying out 3d models in your UI
typedef struct {
    CustomElementType type;
    union {
        Model model;
        Video video;
        // ...
    };
} CustomElementData;

Model myModel = Load3DModel(filePath);
CustomElement modelElement = (CustomElement) { .type = CUSTOM_ELEMENT_TYPE_MODEL, .model = myModel }

typedef struct {
    void* memory;
    uintptr_t offset;
} Arena;

// During init
Arena frameArena = (Arena) { .memory = malloc(1024) };

// ...
CLAY(0) {
    // Custom elements only take a single pointer, so we need to store the data somewhere
    CustomElementData *modelData = (CustomElementData *)(frameArena.memory + frameArena.offset);
    *modelData = (CustomElementData) { .type = CUSTOM_ELEMENT_TYPE_MODEL, .model = myModel };
    frameArena.offset += sizeof(CustomElementData);
    CLAY(CLAY_ID("3DModelViewer"), { .custom = { .customData = modelData } }) {}
}

// Later during your rendering
switch (renderCommand->commandType) {
    // ...
    case CLAY_RENDER_COMMAND_TYPE_CUSTOM: {
        // Your extended struct is passed through
        CustomElementData *customElement = renderCommand->config.customElementConfig->customData;
        if (!customElement) continue;
        switch (customElement->type) {
            case CUSTOM_ELEMENT_TYPE_MODEL: {
                // Render your 3d model here
                break;
            }
            case CUSTOM_ELEMENT_TYPE_VIDEO: {
                // Render your video here
                break;
            }
            // ...
        }
        break;
    }
}

Rendering

Element is subject to culling. Otherwise, a single Clay_RenderCommand with commandType = CLAY_RENDER_COMMAND_TYPE_CUSTOM will be created.

Clay_TransitionElementConfig

Usage

CLAY(CLAY_ID("Transition"), { .transition = { ...transition config } }) {}

Notes

Clay_TransitionElementConfig is used to configure element "transitions", which are animations between states. A .handler function and .properties must be provided for transitions to occur.

Struct Definition (Pseudocode)

typedef struct Clay_TransitionElementConfig
{
    // Handler function pointer for computing current frame state, see below for more info
    bool (*handler)(Clay_TransitionCallbackArguments arguments);
    float duration;
    // Note: this is a flags field. You can pass multiple properties using a bitwise OR, e.g. CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR | CLAY_TRANSITION_PROPERTY_CORNER_RADIUS
    Clay_TransitionProperty properties = {
      CLAY_TRANSITION_PROPERTY_NONE (default),
      CLAY_TRANSITION_PROPERTY_X,
      CLAY_TRANSITION_PROPERTY_Y,
      CLAY_TRANSITION_PROPERTY_POSITION = CLAY_TRANSITION_PROPERTY_X | CLAY_TRANSITION_PROPERTY_Y,
      CLAY_TRANSITION_PROPERTY_WIDTH,
      CLAY_TRANSITION_PROPERTY_HEIGHT,
      CLAY_TRANSITION_PROPERTY_DIMENSIONS = CLAY_TRANSITION_PROPERTY_WIDTH | CLAY_TRANSITION_PROPERTY_HEIGHT,
      CLAY_TRANSITION_PROPERTY_BOUNDING_BOX = CLAY_TRANSITION_PROPERTY_POSITION | CLAY_TRANSITION_PROPERTY_DIMENSIONS,
      CLAY_TRANSITION_PROPERTY_BACKGROUND_COLOR,
      CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR,
      CLAY_TRANSITION_PROPERTY_CORNER_RADIUS,
      CLAY_TRANSITION_PROPERTY_BORDER_COLOR,
      CLAY_TRANSITION_PROPERTY_BORDER_WIDTH,
      CLAY_TRANSITION_PROPERTY_BORDER = CLAY_TRANSITION_PROPERTY_BORDER_COLOR | CLAY_TRANSITION_PROPERTY_BORDER_WIDTH
    };
    Clay_TransitionInteractionHandlingType interactionHandling {
        CLAY_TRANSITION_DISABLE_INTERACTIONS_WHILE_TRANSITIONING_POSITION (default),
        CLAY_TRANSITION_ALLOW_INTERACTIONS_WHILE_TRANSITIONING_POSITION,
    };
    struct {
        // Function pointer, see below for details
        Clay_TransitionData (*setInitialState)(Clay_TransitionData targetState, Clay_TransitionProperty properties);
        Clay_TransitionEnterTriggerType trigger {
            CLAY_TRANSITION_ENTER_SKIP_ON_FIRST_PARENT_FRAME (default),
            CLAY_TRANSITION_ENTER_TRIGGER_ON_FIRST_PARENT_FRAME,
        };
    } enter;
    struct {
        Clay_TransitionData (*setFinalState)(Clay_TransitionData initialState, Clay_TransitionProperty properties);
        Clay_TransitionExitTriggerType trigger {
            CLAY_TRANSITION_EXIT_SKIP_WHEN_PARENT_EXITS (default),
            CLAY_TRANSITION_EXIT_TRIGGER_WHEN_PARENT_EXITS,
        };
        Clay_ExitTransitionSiblingOrdering siblingOrdering {
            CLAY_EXIT_TRANSITION_ORDERING_UNDERNEATH_SIBLINGS (default),
            CLAY_EXIT_TRANSITION_ORDERING_NATURAL_ORDER,
            CLAY_EXIT_TRANSITION_ORDERING_ABOVE_SIBLINGS,
        };
    } exit;
} Clay_TransitionElementConfig;

Fields

.handler - bool (Clay_TransitionCallbackArguments arguments) {}

CLAY(CLAY_ID("Transition"), { .transition = { .handler = Clay_EaseOut } })

When a transition has begun, this function will be called each frame to determine the current state of the element in transition. Clay provides the built-in Clay_EaseOut function which uses a standard EaseOut curve.

If you want to implement your own transition handler, the handler function takes Clay_TransitionCallbackArguments and returns a bool to indicate whether the transition has finished or not (return true means the transition is complete, return false means that the handler should be called again next frame) Consider inspecting the source of the Clay_EaseOut function for more information.

// Example custom handler
bool TransitionHandler(Clay_TransitionCallbackArguments arguments) {
    float ratio = 1;
    if (arguments.duration > 0) {
        // You may want to guard against durations of zero if you use them
        ratio = arguments.elapsedTime / arguments.duration;
    }
    float lerpAmount = (1 - powf(1 - CLAY__MIN(ratio, 1.f), 3.0f));
    // Only animate properties that were specified in the original config
    if (arguments.properties & CLAY_TRANSITION_PROPERTY_X) {
        // Clay provides the initial state from when the transition first started, as well as the target state, to allow
        // easy interpolation
        arguments.current->boundingBox.x = Lerp(arguments.initial.boundingBox.x, arguments.target.boundingBox.x, lerpAmount);
    }
    if (arguments.properties & CLAY_TRANSITION_PROPERTY_Y) {
        arguments.current->boundingBox.y = Lerp(arguments.initial.boundingBox.y, arguments.target.boundingBox.y, lerpAmount);
    }
    // etc...
    
    // End (return true) once elapsedTime is greater than duration 
    return ratio >= 1;
}

.duration - float

CLAY(CLAY_ID("Transition"), { .transition = { .duration = 0.2f } })

The duration in seconds that the transition should take to arrive at its target state. Passed through to the handler function.

.properties - Clay_TransitionProperty

CLAY(CLAY_ID("Transition"), { .transition = { .properties = CLAY_TRANSITION_PROPERTY_X | CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR } })

A flag field containing the properties on which to transition. Any properties that change but are not listed here will immediately snap to their target value.

This flag is a bitfield, which means that you will use bitwise operations to interact with it. For example, use bitwise OR | to combine multiple flags, or bitwise AND & to test if a flag is switched on.

The full list of available transition properties is as follows:

typedef enum {
      CLAY_TRANSITION_PROPERTY_NONE (default),
      CLAY_TRANSITION_PROPERTY_X,
      CLAY_TRANSITION_PROPERTY_Y,
      CLAY_TRANSITION_PROPERTY_POSITION = CLAY_TRANSITION_PROPERTY_X | CLAY_TRANSITION_PROPERTY_Y,
      CLAY_TRANSITION_PROPERTY_WIDTH,
      CLAY_TRANSITION_PROPERTY_HEIGHT,
      CLAY_TRANSITION_PROPERTY_DIMENSIONS = CLAY_TRANSITION_PROPERTY_WIDTH | CLAY_TRANSITION_PROPERTY_HEIGHT,
      CLAY_TRANSITION_PROPERTY_BOUNDING_BOX = CLAY_TRANSITION_PROPERTY_POSITION | CLAY_TRANSITION_PROPERTY_DIMENSIONS,
      CLAY_TRANSITION_PROPERTY_BACKGROUND_COLOR,
      CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR,
      CLAY_TRANSITION_PROPERTY_CORNER_RADIUS,
      CLAY_TRANSITION_PROPERTY_BORDER_COLOR,
      CLAY_TRANSITION_PROPERTY_BORDER_WIDTH,
      CLAY_TRANSITION_PROPERTY_BORDER = CLAY_TRANSITION_PROPERTY_BORDER_COLOR | CLAY_TRANSITION_PROPERTY_BORDER_WIDTH
} Clay_TransitionProperty;

.interactionHandling - Clay_TransitionInteractionHandlingType

CLAY(CLAY_ID("Transition"), { .transition = { .interactionHandling = CLAY_TRANSITION_ALLOW_INTERACTIONS_WHILE_TRANSITIONING_POSITION } })

This flag controls how interactions are handled when elements are transitioning their positions. By default, Clay will ignore interactions i.e. returning false for functions like Clay_Hovered() when .interactionHandling is in the default mode of CLAY_TRANSITION_DISABLE_INTERACTIONS_WHILE_TRANSITIONING

You can set .interactionHandling = CLAY_TRANSITION_ALLOW_INTERACTIONS_WHILE_TRANSITIONING_POSITION if you want to interact with transitioning elements.

The full list of values is as follows:

typedef enum {
    CLAY_TRANSITION_DISABLE_INTERACTIONS_WHILE_TRANSITIONING_POSITION (default),
    CLAY_TRANSITION_ALLOW_INTERACTIONS_WHILE_TRANSITIONING_POSITION,
} Clay_TransitionInteractionHandlingType;

.enter.setInitialState - Clay_TransitionData (Clay_TransitionData targetState, Clay_TransitionProperty properties) {}

CLAY(CLAY_ID("Transition"), { .transition = { .enter = { .setInitialState = { EnterSlideUp } } })

This function pointer is called the first frame an element appears, and allows you to modify the "initial state" of the element to create an entry transition. Common techniques include offsetting the y position to "slide up / down", or using a .overlayColor matched to the background color to fade in.

The function will be called with Clay_TransitionData that provides the first-frame state of the element, which you can modify and then return.

Note: "Enter" transitions will only trigger if this function pointer is set.

Here is an example "fade in & slide up" function:

Clay_TransitionData EnterSlideUp(Clay_TransitionData initialState, Clay_TransitionProperty properties) {
    Clay_TransitionData targetState = initialState;
    if (properties & CLAY_TRANSITION_PROPERTY_Y) {
        targetState.boundingBox.y += 20;
    }
    if (properties & CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR) {
        // Assuming the background color is white, this will produce an alpha-like "fade-in" effect
        targetState.overlayColor = (Clay_Color) { 255, 255, 255, 255 };
    }
    return targetState;
}

.enter.trigger - Clay_TransitionEnterTriggerType

CLAY(CLAY_ID("Transition"), { .transition = { .enter = { .trigger = CLAY_TRANSITION_ENTER_TRIGGER_ON_FIRST_PARENT_FRAME } } })

This flag controls whether or not the "enter" transition of this element will trigger on the same frame that the parent element first appeared.

A common use case for enter transitions is adding items to animated lists. Without this flag, the first frame the list is displayed, all the item enter animations will simultaneously trigger, which is usually undesirable.

For cases where you do want enter animations to trigger when the parent first appears, you can set .trigger = CLAY_TRANSITION_ENTER_TRIGGER_ON_FIRST_PARENT_FRAME.

The full list of values is as follows:

typedef enum trigger {
  CLAY_TRANSITION_ENTER_SKIP_ON_FIRST_PARENT_FRAME (default),
  CLAY_TRANSITION_ENTER_TRIGGER_ON_FIRST_PARENT_FRAME,
} Clay_TransitionEnterTriggerType;

.exit.setFinalState - Clay_TransitionData (Clay_TransitionData currentState, Clay_TransitionProperty properties) {}

CLAY(CLAY_ID("Transition"), { .transition = { .exit = { .setFinalState = { ExitSlideDown } } })

This function pointer is called the frame the element "exits" (i.e. it was in the layout tree last frame, and this frame it isn't). It allows you to modify the "final state" of the element to create an exit transition. Common techniques include offsetting the y position to "slide up / down", or using a .overlayColor matched to the background color to fade out.

The function will be called with Clay_TransitionData that provides the final-frame state of the element, which you can modify and then return.

Note: "Exit" transitions will only trigger if this function pointer is set.

Here is an example "fade out & slide down" function:

Clay_TransitionData ExitSlideDown(Clay_TransitionData currentState, Clay_TransitionProperty properties) {
    Clay_TransitionData finalState = currentState;
    if (properties & CLAY_TRANSITION_PROPERTY_Y) {
        finalState.boundingBox.y += 20;
    }
    if (properties & CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR) {
        // Assuming the background color is white, this will produce an alpha-like "fade-out" effect
        finalState.overlayColor = (Clay_Color) { 255, 255, 255, 255 };
    }
    return finalState;
}

.exit.trigger - Clay_TransitionExitTriggerType

CLAY(CLAY_ID("Transition"), { .transition = { .exit = { .trigger = CLAY_TRANSITION_EXIT_TRIGGER_WHEN_PARENT_EXITS } } })

This flag controls whether or not the "exit" transition of this element will trigger on the same frame that the parent element disappears.

A common use case for exit transitions is removing items from animated lists. Without this flag, the frame after the list disappears (due to say, menu navigation), all the item exit animations will simultaneously trigger, which is usually undesirable.

For cases where you do want exit animations to trigger when the parent exits, you can set .trigger = CLAY_TRANSITION_EXIT_TRIGGER_WHEN_PARENT_EXITS.

The full list of values is as follows:

typedef enum {
  CLAY_TRANSITION_EXIT_SKIP_WHEN_PARENT_EXITS (default),
  CLAY_TRANSITION_EXIT_TRIGGER_WHEN_PARENT_EXITS,
} Clay_TransitionExitTriggerType;

.exit.siblingOrdering - Clay_ExitTransitionSiblingOrdering

CLAY(CLAY_ID("Transition"), { .transition = { .exit = { .siblingOrdering = CLAY_EXIT_TRANSITION_ORDERING_NATURAL_ORDER } } })

This flag controls the relative z-ordering of exiting elements.

It's often useful to be able to control whether you want an exiting element to appear "underneath siblings" in its "natural order" (i.e. above the previous sibling, below the subsequent sibling) or "above all siblings."

By default, exiting elements will be underneath siblings as this appears to be the most common case.

The full list of values is as follows:

typedef enum {
  CLAY_EXIT_TRANSITION_ORDERING_UNDERNEATH_SIBLINGS (default),
  CLAY_EXIT_TRANSITION_ORDERING_NATURAL_ORDER,
  CLAY_EXIT_TRANSITION_ORDERING_ABOVE_SIBLINGS,
} Clay_ExitTransitionSiblingOrdering;

Examples

See video below for how the following would look.

// Note: for transitions to work, elements need a stable ID from one frame to the next - using loop indexes or CLAY_AUTO_ID will not work.
CLAY(CLAY_IDI("box", colors[index].id), {
    .layout.sizing = { CLAY_SIZING_GROW(), CLAY_SIZING_GROW() },
    .layout.childAlignment = { CLAY_ALIGN_X_CENTER, CLAY_ALIGN_Y_CENTER },
    .backgroundColor = boxColor,
    .overlayColor = Clay_Hovered() ? (Clay_Color) { 140, 140, 140, 80 } : (Clay_Color) { 255, 255, 255, 0 },
    // Transitions will activate once a handler function is defined.
    .transition = {
        .handler = Clay_EaseOut,
        .duration = 0.5f,
        // A "flag" enum is used to specify which properties to transition, use a bitwise OR (|) to construct the flags.
        .properties = CLAY_TRANSITION_PROPERTY_WIDTH
                | CLAY_TRANSITION_PROPERTY_POSITION
                | CLAY_TRANSITION_PROPERTY_OVERLAY_COLOR
                | CLAY_TRANSITION_PROPERTY_BACKGROUND_COLOR,
        .enter = { .setInitialState = EnterExitSlideUp },
        .exit = { .setFinalState = EnterExitSlideUp },
    }
}) {
    CLAY_TEXT(CLAY_STRING("Animated Box"), {
      .fontSize = 32,
      .textColor = colors[index].id > 29 ? (Clay_Color) { 255, 255, 255, 255 } : (Clay_Color) { 154, 123, 184, 255 }
    });
}

An example of the transition API action can be found at examples/raylib-transitions

Clay_Color

typedef struct {
    float r, g, b, a;
} Clay_Color;

Clay_Color is an RGBA color struct used in Clay's declarations and rendering. By convention the channels are represented as 0-255, but this is left up to the renderer. Note: when using the debug tools, their internal colors are represented as 0-255.

Clay_String

typedef struct {
    bool isStaticallyAllocated;
    int32_t length;
    const char *chars;
} Clay_String;

Clay_String is a string container that clay uses internally to represent all strings.

Fields

.isStaticallyAllocated - bool

Whether or not the string is statically allocated, or in other words, whether or not it lives for the entire lifetime of the program.

.length - int32_t

The number of characters in the string, not including an optional null terminator.

.chars - const char *

A pointer to the contents of the string. This data is not guaranteed to be null terminated, so if you are passing it to code that expects standard null terminated C strings, you will need to copy the data and append a null terminator.

Clay_ElementId

typedef struct {
    uint32_t id;
    uint32_t offset;
    uint32_t baseId;
    Clay_String stringId;
} Clay_ElementId;

Returned by CLAY_ID and CLAY_IDI, this struct contains a hash id, as well as the source string that was used to generate it.

Fields

.id - uint32_t

A unique ID derived from the string passed to CLAY_ID or CLAY_IDI.

.offset - uint32_t

If this id was generated using CLAY_IDI, .offset is the value passed as the second argument. For CLAY_ID, this will always be 0.

.baseId - uint32_t

If this id was generated using CLAY_IDI, .baseId is the hash of the base string passed, before it is additionally hashed with .offset. For CLAY_ID, this will always be the same as .id.

.stringId - Clay_String

Stores the original string that was passed in when CLAY_ID or CLAY_IDI were called.

Clay_RenderCommandArray

typedef struct
{
	int32_t capacity;
	int32_t length;
	Clay_RenderCommand *internalArray;
} Clay_RenderCommandArray;

Returned by Clay_EndLayout, this array contains the Clay_RenderCommands representing the calculated layout.

Fields

.capacity - uint32_t

Represents the total capacity of the allocated memory in .internalArray.

.length - uint32_t

Represents the total number of Clay_RenderCommand elements stored consecutively at the address .internalArray.

.internalArray - Clay_RenderCommand

An array of Clay_RenderCommands representing the calculated layout. If there was at least one render command, this array will contain elements from .internalArray[0] to .internalArray[.length - 1].

Clay_RenderCommand

typedef struct {
    Clay_BoundingBox boundingBox;
    Clay_RenderData renderData;
    void* userData;
    uint32_t id;
    int16_t zIndex;
    Clay_RenderCommandType commandType;
} Clay_RenderCommand;

Fields

.commandType - Clay_RenderCommandType

An enum indicating how this render command should be handled. Possible values include:

CLAY_RENDER_COMMAND_TYPE_NONE - Should be ignored by the renderer, and never emitted by clay under normal conditions.
CLAY_RENDER_COMMAND_TYPE_RECTANGLE - A rectangle should be drawn, configured with .renderData.rectangle
CLAY_RENDER_COMMAND_TYPE_BORDER - A border should be drawn, configured with .renderData.border
CLAY_RENDER_COMMAND_TYPE_TEXT - Text should be drawn, configured with .renderData.text
CLAY_RENDER_COMMAND_TYPE_IMAGE - An image should be drawn, configured with .renderData.image
CLAY_RENDER_COMMAND_TYPE_SCISSOR_START - Named after glScissor, this indicates that the renderer should begin culling any subsequent pixels that are drawn outside the .boundingBox of this render command.
CLAY_RENDER_COMMAND_TYPE_SCISSOR_END - Only ever appears after a matching CLAY_RENDER_COMMAND_TYPE_SCISSOR_START command, and indicates that the scissor has ended.
CLAY_RENDER_COMMAND_TYPE_OVERLAY_COLOR_START - The renderer should begin applying an overlay color to all subsequent render commands, similar to glsl's mix(source, target, alpha).
CLAY_RENDER_COMMAND_TYPE_OVERLAY_COLOR_END - The previous OVERLAY_COLOR should be removed. Note: nested color overlays may require a stack data structure on the renderer side.
CLAY_RENDER_COMMAND_TYPE_CUSTOM - A custom render command controlled by the user, configured with .renderData.custom

.boundingBox - Clay_BoundingBox

typedef struct {
    float x, y, width, height;
} Clay_BoundingBox;

A rectangle representing the bounding box of this render command, with .x and .y representing the top left corner of the element.

.id - uint32_t

The id that was originally used with the element macro that created this render command. See CLAY_ID for details.

.zIndex - int16_t

The z index of the element, based on what was passed to the root floating configuration that this element is a child of. Higher z indexes should be rendered on top of lower z indexes.

.renderData - Clay_RenderData

typedef union {
    Clay_RectangleRenderData rectangle;
    Clay_TextRenderData text;
    Clay_ImageRenderData image;
    Clay_CustomRenderData custom;
    Clay_BorderRenderData border;
} Clay_RenderData;

A C union containing various structs, with the type dependent on .commandType. Possible values include:

renderData.rectangle - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_RECTANGLE.
renderData.text - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_TEXT. See Clay_Text for details.
renderData.image - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_IMAGE. See Clay_ImageElementConfig for details.
renderData.custom - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_CUSTOM. See Clay_CustomElementConfig for details.
renderData.border - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_BORDER. See Clay_BorderElementConfig for details.
renderData.clip - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_SCISSOR_START. See Clay_ClipElementConfig for details.
renderData.overlayColor - Used when .commandType == CLAY_RENDER_COMMAND_TYPE_OVERLAY_COLOR_START. See Clay_ElementDeclaration.overlayColor for details.

Union Structs

typedef struct {
    Clay_StringSlice stringContents;
    Clay_Color textColor;
    uint16_t fontId;
    uint16_t fontSize;
    uint16_t letterSpacing;
    uint16_t lineHeight;
} Clay_TextRenderData;

typedef struct {
    Clay_Color backgroundColor;
    Clay_CornerRadius cornerRadius;
} Clay_RectangleRenderData;

typedef struct {
    Clay_Color backgroundColor;
    Clay_CornerRadius cornerRadius;
    void* imageData;
} Clay_ImageRenderData;

typedef struct {
    Clay_Color backgroundColor;
    Clay_CornerRadius cornerRadius;
    void* customData;
} Clay_CustomRenderData;

typedef struct {
    Clay_Color color;
    Clay_CornerRadius cornerRadius;
    Clay_BorderWidth width;
} Clay_BorderRenderData;

typedef union {
    Clay_RectangleRenderData rectangle;
    Clay_TextRenderData text;
    Clay_ImageRenderData image;
    Clay_CustomRenderData custom;
    Clay_BorderRenderData border;
} Clay_RenderData;

Clay_ScrollContainerData

// Data representing the current internal state of a scrolling element.
typedef struct {
    // Note: This is a pointer to the real internal scroll position, mutating it may cause a change in final layout.
    // Intended for use with external functionality that modifies scroll position, such as scroll bars or auto scrolling.
    Clay_Vector2 *scrollPosition;
    // The bounding box of the scroll element.
    Clay_Dimensions scrollContainerDimensions;
    // The outer dimensions of the inner scroll container content, including the padding of the parent scroll container.
    Clay_Dimensions contentDimensions;
    // The config that was originally passed to the scroll element.
    Clay_ClipElementConfig config;
    // Indicates whether an actual scroll container matched the provided ID or if the default struct was returned.
    bool found;
} Clay_ScrollContainerData;

Fields

.scrollPosition - Clay_Vector2 *

A pointer to the internal scroll position of this scroll container. Mutating it will result in elements inside the scroll container shifting up / down (.y) or left / right (.x).

.scrollContainerDimensions - Clay_Dimensions

typedef struct {
    float width, height;
} Clay_Dimensions;

Dimensions representing the outer width and height of the scroll container itself.

.contentDimensions - Clay_Dimensions

typedef struct {
    float width, height;
} Clay_Dimensions;

Dimensions representing the inner width and height of the content inside the scroll container. Scrolling is only possible when the contentDimensions are larger in at least one dimension than the scrollContainerDimensions.

.config - Clay_ClipElementConfig

The Clay_ClipElementConfig for the matching scroll container element.

Clay_ElementData

// Bounding box and other data for a specific UI element.
typedef struct {
    // The rectangle that encloses this UI element, with the position relative to the root of the layout.
    Clay_BoundingBox boundingBox;
    // Indicates whether an actual Element matched the provided ID or if the default struct was returned.
    bool found;
} Clay_ElementData;

Fields

.boundingBox - Clay_BoundingBox

typedef struct {
    float x, y, width, height;
} Clay_BoundingBox;

A rectangle representing the bounding box of this render command, with .x and .y representing the top left corner of the element.

.found - bool

A boolean representing whether or not the ID passed to Clay_GetElementData matched a valid element or not. In the case that .found is false, .boundingBox will be the default value (zeroed).

Clay_PointerData

typedef struct
{
    Clay_Vector2 position;
    Clay_PointerDataInteractionState state;
} Clay_PointerData;

Fields

.position - Clay_Vector2

A Vector2 containing the current x,y coordinates of the mouse pointer, which were originally passed into Clay_SetPointerState().

.state - Clay_PointerDataInteractionState

typedef enum
{
    CLAY_POINTER_DATA_PRESSED_THIS_FRAME,
    CLAY_POINTER_DATA_PRESSED,
    CLAY_POINTER_DATA_RELEASED_THIS_FRAME,
    CLAY_POINTER_DATA_RELEASED,
} Clay_PointerDataInteractionState;

An enum value representing the current "state" of the pointer interaction. As an example, consider the case where a user is on a desktop computer, moves the mouse pointer over a button, clicks and holds the left mouse button for a short time, then releases it:

While the mouse pointer is over ("hovering") the button, but no mouse button has been pressed: CLAY_POINTER_DATA_RELEASED
First frame that the user presses the left mouse button: CLAY_POINTER_DATA_PRESSED_THIS_FRAME
All subsequent frames where the user is still holding the left mouse button: CLAY_POINTER_DATA_PRESSED
The single frame where the left mouse button goes from pressed -> released: CLAY_POINTER_DATA_RELEASED_THIS_FRAME
All subsequent frames while the mouse pointer is still over the button: CLAY_POINTER_DATA_RELEASED

Clay_ErrorHandler

typedef struct
{
    void (*errorHandlerFunction)(Clay_ErrorData errorText);
    uintptr_t userData;
} Clay_ErrorHandler;

Fields

.errorHandlerFunction - void (Clay_ErrorData errorText) {}

A function pointer to an error handler function, which takes Clay_ErrorData as an argument. This function will be called whenever Clay encounters an internal error.

.userData - uintptr_t

A generic pointer to extra userdata that is transparently passed through from Clay_Initialize to Clay's error handler callback. Defaults to NULL.

Clay_ErrorData

typedef struct
{
    Clay_ErrorType errorType;
    Clay_String errorText;
    uintptr_t userData;
} Clay_ErrorData;

Fields

.errorType - Clay_ErrorType

typedef enum {
    CLAY_ERROR_TYPE_TEXT_MEASUREMENT_FUNCTION_NOT_PROVIDED,
    CLAY_ERROR_TYPE_ARENA_CAPACITY_EXCEEDED,
    CLAY_ERROR_TYPE_ELEMENTS_CAPACITY_EXCEEDED,
    CLAY_ERROR_TYPE_TEXT_MEASUREMENT_CAPACITY_EXCEEDED,
    CLAY_ERROR_TYPE_DUPLICATE_ID,
    CLAY_ERROR_TYPE_FLOATING_CONTAINER_PARENT_NOT_FOUND,
    CLAY_ERROR_TYPE_INTERNAL_ERROR,
} Clay_ErrorType;

An enum representing the type of error Clay encountered. It's up to the user to handle on a case by case basis, but as some general guidance:

CLAY_ERROR_TYPE_TEXT_MEASUREMENT_FUNCTION_NOT_PROVIDED - The user is attempting to use CLAY_TEXT and either forgot to call Clay_SetMeasureTextFunction or accidentally passed a null function pointer.
CLAY_ERROR_TYPE_ARENA_CAPACITY_EXCEEDED - Clay was initialized with an Arena that was too small for the configured Clay_SetMaxElementCount. Try using Clay_MinMemorySize() to get the exact number of bytes required by the current configuration.
CLAY_ERROR_TYPE_ELEMENTS_CAPACITY_EXCEEDED - The declared UI hierarchy has too many elements for the configured max element count. Use Clay_SetMaxElementCount to increase the max, then call Clay_MinMemorySize() again and reinitialize clay's memory with the required size.
CLAY_ERROR_TYPE_TEXT_MEASUREMENT_CAPACITY_EXCEEDED - The declared UI hierarchy has too much text for the configured text measure cache size. Use Clay_SetMaxMeasureTextCacheWordCount to increase the max, then call Clay_MinMemorySize() again and reinitialize clay's memory with the required size.
CLAY_ERROR_TYPE_DUPLICATE_ID - Two elements in Clays UI Hierarchy have been declared with exactly the same ID. Set a breakpoint in your error handler function for a stack trace back to exactly where this occured.
CLAY_ERROR_TYPE_FLOATING_CONTAINER_PARENT_NOT_FOUND - A CLAY_FLOATING element was declared with the .parentId property, but no element with that ID was found. Set a breakpoint in your error handler function for a stack trace back to exactly where this occured.
CLAY_ERROR_TYPE_INTERNAL_ERROR - Clay has encountered an internal logic or memory error. Please report this as a bug with a stack trace to help us fix these!

.errorText - Clay_String

A Clay_String that provides a human readable description of the error. May change in future and should not be relied on to detect error types.

.userData - uintptr_t

A generic pointer to extra userdata that is transparently passed through from Clay_Initialize to Clay's error handler callback. Defaults to NULL.

brunodev85/winlator

Android application for running Windows applications with Wine and Box86/Box64

Winlator

Winlator is an Android application that lets you to run Windows (x86_64) applications with Wine and Box86/Box64.

Installation

Download and install the APK (Winlator_11.1.apk) from GitHub Releases
Launch the app and wait for the installation process to finish

Useful Tips

If you are experiencing performance issues, try changing the Box64 preset to Performance in Container Settings -> Advanced Tab.
For applications that use .NET Framework, try installing Wine Mono found in Start Menu -> System Tools -> Installers.
If some older games don't open, try adding the environment variable MESA_EXTENSION_MAX_YEAR=2003 in Container Settings -> Environment Variables.
Try running the games using the shortcut on the Winlator home screen, there you can define individual settings for each game.
To display low resolution games correctly, try to enabling the Force Fullscreen option in the shortcut settings.
To improve stability in games that uses Unity Engine, try changing the Box64 preset to Stability or in the shortcut settings add the exec argument -force-gfx-direct.
If you are experiencing audio crackling, try increasing the average latency in ALSA/PulseAudio configuration. Old games like Unreal Gold resolve audio issues by increasing this value to 90ms.

Credits and Third-party apps

GLIBC Patches by Termux Pacman
Wine (winehq.org)
Box86/Box64 by ptitseb
Mesa (Turnip/Zink/VirGL) (mesa3d.org)
DXVK (github.com/doitsujin/dxvk)
VKD3D (gitlab.winehq.org/wine/vkd3d)
CNC DDraw (github.com/FunkyFr3sh/cnc-ddraw)

Special thanks to all the developers involved in these projects.
Thank you to all the people who believe in this project.

curl/curl

A command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features

curl is a command-line tool for transferring data from or to a server using URLs. It supports these protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS.

Learn how to use curl by reading the man page or everything curl.

Find out how to install curl by reading the INSTALL document.

libcurl is the library curl is using to do its job. It is readily available to be used by your software. Read the libcurl man page to learn how.

Open Source

curl is Open Source and is distributed under an MIT-like license.

Contact

All contributors to the project are listed in the THANKS document.

Commercial support

For commercial support, maybe private and dedicated help with your problems or applications using (lib)curl visit the support page.

Website

Visit the curl website for the latest news and downloads.

Source code

Download the latest source from the Git server:

git clone https://github.com/curl/curl

Security problems

Report suspected security problems privately and not in public.

Backers

Thank you to all our backers 🙏 Become a backer.

obsproject/obs-studio

OBS Studio - Free and open source software for live streaming and screen recording

OBS Studio https://obsproject.com

.. image:: https://github.com/obsproject/obs-studio/actions/workflows/push.yaml/badge.svg?branch=master :alt: OBS Studio Build Status - GitHub Actions :target: https://github.com/obsproject/obs-studio/actions/workflows/push.yaml?query=branch%3Amaster

.. image:: https://badges.crowdin.net/obs-studio/localized.svg :alt: OBS Studio Translation Project Progress :target: https://crowdin.com/project/obs-studio

.. image:: https://img.shields.io/discord/348973006581923840.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2 :alt: OBS Studio Discord Server :target: https://obsproject.com/discord

What is OBS Studio?

OBS Studio is software designed for capturing, compositing, encoding, recording, and streaming video content, efficiently.

It's distributed under the GNU General Public License v2 (or any later version) - see the accompanying COPYING file for more details.

Quick Links

Website: https://obsproject.com
Help/Documentation/Guides: https://github.com/obsproject/obs-studio/wiki
Forums: https://obsproject.com/forum/
Build Instructions: https://github.com/obsproject/obs-studio/wiki/Install-Instructions
Developer/API Documentation: https://obsproject.com/docs
Donating/backing/sponsoring: https://obsproject.com/contribute
Bug Tracker: https://github.com/obsproject/obs-studio/issues

Contributing

If you would like to help fund or sponsor the project, you can do so via Patreon <https://www.patreon.com/obsproject>, OpenCollective <https://opencollective.com/obsproject>, or PayPal <https://www.paypal.me/obsproject>. See our contribute page <https://obsproject.com/contribute> for more information.
If you wish to contribute code to the project, please make sure to read the coding and commit guidelines: https://github.com/obsproject/obs-studio/blob/master/CONTRIBUTING.md
Code for the project follows the code style guidelines, located here: https://github.com/obsproject/obs-studio/blob/master/CODESTYLE.md
Developer/API documentation can be found here: https://obsproject.com/docs
If you wish to contribute translations, do not submit pull requests. Instead, please use Crowdin. For more information read this page: https://obsproject.com/wiki/How-To-Contribute-Translations-For-OBS
Contributors to OBS Studio and related repositories are expected to follow our Code of Conduct, which can be read here: https://github.com/obsproject/obs-studio/blob/master/COC.rst
Other ways to contribute are by helping people out with support on our forums or in our community chat. Please limit support to topics you fully understand -- bad advice is worse than no advice. When it comes to something that you don't fully know or understand, please defer to the official help or official channels.

SAST Tools

PVS-Studio <https://pvs-studio.com/pvs-studio/?utm_source=website&utm_medium=github&utm_campaign=open_source>_ - static analyzer for C, C++, C#, and Java code.

superturtlee/gbl_root_canoe

No TrickyStore on Canoe

GBL Root Canoe

中文版

⚠️ This project has been archived. This is the final version — the patching engine is stable across multiple vendors and ABL versions, the core logic no longer changes, and active maintenance has ended. The code still works; forks are welcome. See ARCHIVE.md for details.

gbl_root_canoe is an EDK2-based workspace for patching the EFI applications within Qualcomm ABL (Android Bootloader) images. It leverages a GBL (Generic Bootloader Loader) vulnerability so the real ABL loads an embedded superfastboot BDS off the raw efisp partition. The BDS then scans a compatible partition (ext4/fat32) for boot entries and chains to the selected one - primarily to achieve a Fake Locked Bootloader state on Snapdragon 8 Gen 5 / 8 Elite (Gen 5) devices to bypass bootloader unlock detection.

BDS.efi is written raw to the efisp partition; the cracked ABL (boot.efi) and the boot entry list (BOOTENTRIES) live on the persist partition under its efisp/ directory.

Builder Guide

This section is for developers who want to compile the toolkits from source.

Prerequisites

You must be on a Linux host to build the project:

gcc / clang, lld, make, zip, python3
liblzma-dev (for compiling extractfv)
Android NDK (Required for make target_magisk_module to cross-compile tools for Android)
MinGW-w64

Build Targets

Note: You do not need to provide an abl.img to build the distributable toolkits or module.

make target_toolkit_linux Builds the superfastboot BDS (BDS.efi) from the uefi submodule and compiles the patching utilities (extractfv, patch_abl) for Linux.
make target_toolkit_windows Same as above, but cross-compiles the utilities into Windows .exe programs using MinGW-w64.
make target_magisk_module Cross-compiles the patcher tools for Android using your NDK, builds the BDS, and packages everything as a KernelSU/Magisk module.
make target_toolkit_android Produces a standalone Android arm64 toolkit (toolkit_android.zip) with Android-native binaries for on-device use outside of the module.

User Guide

For more detailed instructions, please refer to the Wiki.

1. Using the Module (On-Device)

The module is designed to run directly on your rooted Android device.

Requirements:

Device must be Snapdragon 8 Gen 5 / 8 Elite (Gen 5).
Bootloader must be unlocked.
Kernel must NOT have Baseband Guard.
The ABL on the abl partition must contain the GBL vulnerability. If it does not, flash an older ABL with the vulnerability first (the cracked boot.efi does not need to match the ABL on the abl partition).

Installation & Usage: When flashing the module via a root manager (KernelSU, Magisk, or APatch), the script interacts with you using the volume keys:

Volume Up (First-time installation): The script extracts the current-slot .abl, cracks it into boot.efi, places boot.efi / LinuxLoader.efi / BOOTENTRIES into /mnt/vendor/persist/efisp/, and flashes BDS.efi to efisp. After this, reboot into Recovery and format Data. Once booted, install this module again (Volume Down the second time) to complete the installation.
Volume Down (OTA retention or post-format): Installs the OTA-update patch. After each OTA, open the module WebUI and flash again to retain the BL version.

2. Using the PC Toolkits (Linux / Windows)

If you downloaded the target_toolkit_linux or target_toolkit_windows zip files:

Extract the toolkit zip on your PC.
Place your device's stock abl.img inside the images/ (or images\) directory of the toolkit.
Linux: Run bash build.sh. Windows: Run build.bat.
The script extracts and cracks the ABL, outputting ABL.efi (fake re-lock) and ABL_original.efi (original). BDS.efi is bundled. Check patch_log.txt - if it says "Warning: Failed to patch ABL GBL", the ABL lacks the vulnerability and the abl partition must be downgraded to an older ABL with it.

Then complete the install manually (see the Wiki for full steps): copy ABL.efi into /mnt/vendor/persist/efisp/, create BOOTENTRIES, sync, and flash BDS.efi to efisp (dd if=BDS.efi of=/dev/block/by-name/efisp bs=4M).

3. OTA Upgrade

Before rebooting for an OTA update, use the module WebUI to flash and retain the old ABL version. "Update efisp" is enabled by default; for a major version upgrade keep it on, otherwise the device may get stuck on the first boot screen.

4. Superfastboot Usage Instructions

When OEM Unlocking is enabled and the white warning text appears on boot, press Volume Down to enter Superfastboot mode (the BDS). Common commands include:

Temp-boot an EFI file (without flashing): fastboot boot xxx.efi
Lock and Unlock (BL related):
- Lock BL, triggers a data wipe: fastboot flashing lock
- Unlock BL, no data wipe: fastboot flashing unlock or fastboot flashing unlock_critical
- Note: If the TEE status is inconsistent, the device will refuse to provide the data key, rendering data inaccessible.
Flashing and Erasing:
- fastboot flash <partition> <file.img>
- fastboot erase <partition>
Rebooting:
- fastboot reboot bootloader (Next normal boot enters Official Fastboot)
- fastboot reboot recovery
- fastboot reboot

5. File Reference

BDS.efi: The superfastboot BDS, flashed raw to the efisp partition.
boot.efi / ABL.efi: The cracked ABL with fake re-lock (the module names it boot.efi; the toolkit names it ABL.efi), placed on persist under efisp/.
LinuxLoader.efi / ABL_original.efi: The original unpatched ABL. For analysis; do not flash to efisp.
BOOTENTRIES: Boot entry list, format <name>:<path relative to efisp/>.

tr4m0ryp/tr4mpass

Free, open-source iCloud activation lock bypass tool. Remove iCloud lock from iPhone 5s through iPhone 15 Pro (iOS 12-26.1). Fully offline -- no servers, no payments. Supports checkm8 (A5-A11) and session activation (A12+).

tr4mpass: iCloud Activation Lock Bypass

New improved version will be released soon

Free, open-source tool that removes iCloud activation lock from iPhones and iPads. Runs locally on your computer -- no servers, no payments, no accounts needed. Just plug in your device and run.

Supports iOS 12 through 26.1 | iPhone 5s through iPhone 15 Pro

For developers and security researchers: read 26.3-vulnerability.md for potential vulnerabilities that could enable bypass on iOS 26.3 and later.

How to Use

1. Download

git clone https://github.com/tr4m0ryp/tr4mpass.git
cd tr4mpass

2. Run

./start.sh

That's it. The script will:

Install everything needed (works on macOS, Linux, and Windows via WSL)
Build the tool automatically
Detect your device when you plug it in
Guide you into DFU mode step by step
Run the bypass
Tell you when it's done

3. Put Your Device in DFU Mode

The script will walk you through this, but here's the short version:

iPhone 7 and older (Home button):

Connect to your computer via USB
Hold Power + Home for 10 seconds
Release Power, keep holding Home for 5 more seconds
Screen should be completely black (no Apple logo)

iPhone 8, X, and newer (Face ID / no Home button):

Connect to your computer via USB
Quick-press Volume Up, quick-press Volume Down
Hold Side button until screen goes black
Hold Side + Volume Down for 5 seconds
Release Side, keep holding Volume Down for 10 seconds
Screen should be completely black

Supported Devices

iPhone

Device	Chip	Bypass Method	Signal Preserved
iPhone 5s	A7	Path A (checkm8)	No (WiFi only)
iPhone 6 / 6 Plus	A8	Path A (checkm8)	No (WiFi only)
iPhone 6s / 6s Plus	A9	Path A (checkm8)	Yes
iPhone SE (1st gen)	A9	Path A (checkm8)	Yes
iPhone 7 / 7 Plus	A10	Path A (checkm8)	Yes
iPhone 8 / 8 Plus	A11	Path A (checkm8)	Yes
iPhone X	A11	Path A (checkm8)	Yes
iPhone XR	A12	Path B (session)	Yes
iPhone XS / XS Max	A12	Path B (session)	Yes
iPhone 11 / Pro / Pro Max	A13	Path B (session)	Yes
iPhone SE (2nd gen)	A13	Path B (session)	Yes
iPhone 12 / Mini / Pro / Pro Max	A14	Path B (session)	Yes
iPhone 13 / Mini / Pro / Pro Max	A15	Path B (session)	Yes
iPhone SE (3rd gen)	A15	Path B (session)	Yes
iPhone 14 / Plus	A15	Path B (session)	Yes
iPhone 14 Pro / Pro Max	A16	Path B (session)	Yes
iPhone 15 / Plus	A16	Path B (session)	Yes
iPhone 15 Pro / Pro Max	A17	Path B (session)	Yes

iPad

Device	Chip	Bypass Method
iPad Air	A7	Path A (checkm8)
iPad Air 2	A8X	Path A (checkm8)
iPad mini 4	A8	Path A (checkm8)
iPad Pro (1st gen)	A9X	Path A (checkm8)
iPad (5th-7th gen)	A9-A10	Path A (checkm8)
iPad Pro (2nd gen)	A10X	Path A (checkm8)
iPad Pro (3rd/4th gen)	A12/A12Z	Path B (session)
iPad Air (4th/5th gen)	A14/M1	Path B (session)
iPad Pro (5th/6th gen)	M1/M2	Path B (session)

Other

Device	Chip	Bypass Method
iPod touch (6th gen)	A8	Path A (checkm8)
iPod touch (7th gen)	A10	Path A (checkm8)
Apple TV 4K (1st gen)	A10X	Path A (checkm8)
Apple Watch Series 1-3	S1P/S3	Path A (checkm8)

What Does "Signal Preserved" Mean?

Yes -- After bypass, your iPhone keeps full cellular service (calls, texts, data). SIM card works normally.
No (WiFi only) -- After bypass, the device works on WiFi but cellular service is disabled. This applies to older devices (A7/A8) and all WiFi-only iPads.

Advanced Usage

If you prefer to run things manually instead of using start.sh:

# Build
make

# Just identify your device (no bypass)
./tr4mpass --detect-only

# Run with full debug output
./tr4mpass --verbose

# Force a specific bypass path
./tr4mpass --force-path-a    # checkm8 (A5-A11 devices)
./tr4mpass --force-path-b    # session activation (A12+ devices)

# Preview what would happen without doing it
./tr4mpass --dry-run

Manual dependency install -- macOS

brew install libimobiledevice libirecovery libusb libplist openssl pkg-config

Manual dependency install -- Linux (Debian/Ubuntu)

sudo apt-get install -y \
    libimobiledevice-dev libirecovery-1.0-dev libusb-1.0-0-dev \
    libplist-dev libssl-dev pkg-config build-essential

Manual dependency install -- Linux (Fedora)

sudo dnf install -y \
    libimobiledevice-devel libirecovery-devel libusb1-devel \
    libplist-devel openssl-devel pkg-config gcc make

Windows

Native Windows is not supported. Install WSL first:

wsl --install

Then open a WSL terminal and follow the Linux instructions.

How It Works (Technical)

tr4mpass has two bypass paths, selected automatically based on your device's chip:

Path A -- checkm8 (A5 through A11)

Uses a permanent hardware vulnerability in the BootROM (the very first code that runs when the device powers on). This vulnerability cannot be patched by Apple because the BootROM is burned into silicon at the factory.

DFU Mode -> checkm8 exploit -> load ramdisk -> jailbreak kernel
-> inject activation record -> cleanup Setup.app -> verify

Path B -- Session Activation (A12 and later)

Does not use a hardware exploit. Instead, it manipulates the device's identity in DFU mode, then uses Apple's own activation protocol (drmHandshake session mode) to change the lock state.

DFU Mode -> identity manipulation -> signal detection
-> session handshake -> activation record -> cleanup -> verify

Architecture

+-------------------------+
|        start.sh         |  Guided wrapper (OS detect, deps, DFU guide)
+-------------------------+
|         main.c          |  CLI, device detection, path selection
+-------------------------+
|  Path A    |   Path B   |  Bypass strategies
+------------+------------+
| checkm8    | identity   |  Exploit / manipulation
| jailbreak  | session    |  Activation protocol
+------------+------------+
| DFU protocol | activation record | deletescript |
+--------------+-------------------+--------------+
| libusb | libimobiledevice | libplist | OpenSSL  |
+--------+------------------+---------+----------+

Source Files

The codebase is written in C99 (21 source files, 20 headers). Every file is under 300 lines. The Makefile auto-discovers all sources -- no manual file lists.

Module	What it does
`src/main.c`	Entry point, CLI args, orchestration
`src/device/`	Device detection (USB + libimobiledevice), chip database (A5-A17)
`src/exploit/`	checkm8 exploit stages, DFU protocol, payload assembly
`src/bypass/`	Path A, Path B, signal detection, deletescript, AFC utils
`src/activation/`	Activation client, session protocol, record builder
`src/util/`	Logging, plist helpers, USB helpers

iOS 26.3+ (Research in Progress)

Current bypass methods work up to iOS 26.1. For iOS 26.2 and later, Apple hardened several security layers that break existing approaches.

We have identified a potential bypass vector through VU#346053 -- an unpatched vulnerability in Apple's activation server that accepts unsigned XML payloads. This could enable bypass via a captive portal during device setup, without needing any exploit or jailbreak.

This is not implemented yet. See 26.3-vulnerability.md for the full technical analysis, proposed attack chain, and implementation roadmap.

Disclaimer

This tool is for authorized security research only (Apple Security Bounty program).

Only use on devices you own or have written authorization to test.
Bypassing activation lock on stolen devices is illegal.
No warranty. Use at your own risk.
Results are not guaranteed for every device or iOS version.

References

This project was built on extensive research and analysis of open-source tools, security disclosures, Apple documentation, and community knowledge.

Open-Source Tools and Libraries

Project	What we used it for
gaster	checkm8 exploit implementation in C -- chip offsets, ROP chains, exploit stages, shellcode structure
ipwndfu	Original checkm8 exploit reference (Python) -- payload structure, heap spray parameters
libimobiledevice	Device communication, lockdownd, mobileactivation API
libideviceactivation	Activation record handling, drmHandshake protocol
go-ios	mobileactivation module -- session protocol, handshake sequence, activation flow
pymobiledevice3	Python reference for activation protocol and mobile services
checkra1n / PongoOS	Pre-boot execution environment, jailbreak reference for A5-A11
palera1n	Modern checkm8-based jailbreak, ramdisk builder
jbinit	iOS booter ramdisk creator for checkm8 devices
Lockra1n	Untethered iCloud bypass reference (iOS 15-16.7.8)
LIBRE-HACKTIVATOR	Deletescript reference -- per-iOS-version cleanup scripts
iOS-Hacktivation-Toolkit	Per-version mobileactivationd patching scripts
Onii_Ramdisk	Free iCloud bypass ramdisk tool
img4tool	IMG4 firmware container extraction
iBoot64Patcher	Bootloader patching for ramdisk loading
ramdiskutil	iOS restore ramdisk customization
iExtractor	Automated IPSW firmware extraction

Security Research and Disclosures

Source	Relevance
VU#346053 -- iOS Activation Flaw	Unpatched XML injection at humb.apple.com/humbug/baa (iOS 26.3+ bypass vector)
Full Disclosure: iOS Activation Flaw	Original public disclosure of VU#346053 (June 2025)
CVE-2019-8900 -- checkm8	BootROM use-after-free vulnerability (A5-A11)
CVE-2023-41991 -- CoreTrust	Code signing bypass (patched iOS 17.0.1), explains why persistent signing fails on iOS 18+
CVE-2026-20687 -- Kernel UAF	IOCommandGate use-after-free via AppleKeyStore race condition (iOS 26.1-26.3)
CVE-2026-28859 -- WebKit Sandbox Escape	Memory handling bug allowing process to escape sandbox (patched iOS 26.4)

Apple Documentation

Source	What it covers
Apple Activation Lock	Official activation lock documentation
Apple Security Bounty	Bug bounty program this research falls under
Secure Enclave	SEP architecture and activation state storage
The Apple Wiki -- Firmware Keys	Decryption keys for IPSW ramdisk extraction
The iPhone Wiki -- Activation Token	Activation record plist format and fields
The iPhone Wiki -- WildcardTicket	Activation ticket structure (TEA-CBC encryption)
The iPhone Wiki -- Setup.app	Setup Assistant paths targeted by deletescript
Albert Server	Apple's activation server endpoints

Analysis and Articles

Source	Topic
GBHackers -- iOS Activation Flaw	VU#346053 technical analysis
CyberSecurity News -- Activation Vulnerability	VU#346053 impact analysis
checkm8 Deep Dive (Medium)	checkm8 exploit mechanics
Zimperium -- checkm8 Analysis	Security industry analysis of checkm8
Habr -- checkm8 Technical Analysis	Detailed technical breakdown of the DFU UAF
Black Hat 2016 -- Demystifying the SEP	Secure Enclave architecture research
Dynastic Research -- iOS Codesign Bypass	CoreTrust/AMFI bypass history

Commercial Tools Analyzed

During development, the following proprietary tools were analyzed to understand bypass flows and protocol implementations:

Tool	Version	What we extracted
Checkm8.info Software	9.5	Two-section architecture (A5-A11 vs A12+), DFU exploit flow, FActivation protocol, offline bypass method, bundled go-ios binary, ipwndfu payloads
iRemoveTools	9.5	A12+ activation APIs, signal vs no-signal handling, MobileDeviceFramework usage, mobileactivationd interaction

memovai/mimiclaw

MimiClaw: Harness on a $5 chip. No OS(Linux). No Node.js. No Mac mini. No Raspberry Pi. No VPS. Hardware agents OS.

MimiClaw: Pocket AI Assistant on a $5 Chip

English | 中文 | 日本語

The world's first AI assistant(OpenClaw) on a $5 chip. No Linux. No Node.js. Just pure C

MimiClaw turns a tiny ESP32-S3 board into a personal AI assistant. Plug it into USB power, connect to WiFi, and talk to it through Telegram — it handles any task you throw at it and evolves over time with local memory — all on a chip the size of a thumb.

Meet MimiClaw

Tiny — No Linux, no Node.js, no bloat — just pure C
Handy — Message it from Telegram, it handles the rest
Loyal — Learns from memory, remembers across reboots
Energetic — USB power, 0.5 W, runs 24/7
Lovable — One ESP32-S3 board, $5, nothing else

How It Works

You send a message on Telegram. The ESP32-S3 picks it up over WiFi, feeds it into an agent loop — the LLM thinks, calls tools, reads memory — and sends the reply back. Supports both Anthropic (Claude) and OpenAI (GPT) as providers, switchable at runtime. Everything runs on a single $5 chip with all your data stored locally on flash.

Quick Start

What You Need

An ESP32-S3 dev board with 16 MB flash and 8 MB PSRAM (e.g. Xiaozhi AI board, ~$10)
A USB Type-C cable
A Telegram bot token — talk to @BotFather on Telegram to create one
An Anthropic API key — from console.anthropic.com, or an OpenAI API key — from platform.openai.com

Install

# You need ESP-IDF v5.5+ installed first:
# https://docs.espressif.com/projects/esp-idf/en/v5.5.2/esp32s3/get-started/

git clone https://github.com/memovai/mimiclaw.git
cd mimiclaw

idf.py set-target esp32s3

Ubuntu Install

Recommended baseline:

Ubuntu 22.04/24.04
Python >= 3.10
CMake >= 3.16
Ninja >= 1.10
Git >= 2.34
flex >= 2.6
bison >= 3.8
gperf >= 3.1
dfu-util >= 0.11
libusb-1.0-0, libffi-dev, libssl-dev

Install and build on Ubuntu:

sudo apt-get update
sudo apt-get install -y git wget flex bison gperf python3 python3-pip python3-venv \
  cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0

./scripts/setup_idf_ubuntu.sh
./scripts/build_ubuntu.sh

macOS Install

Recommended baseline:

macOS 12/13/14
Xcode Command Line Tools
Homebrew
Python >= 3.10
CMake >= 3.16
Ninja >= 1.10
Git >= 2.34
flex >= 2.6
bison >= 3.8
gperf >= 3.1
dfu-util >= 0.11
libusb, libffi, openssl

Install and build on macOS:

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

./scripts/setup_idf_macos.sh
./scripts/build_macos.sh

Configure

MimiClaw uses a two-layer config system: build-time defaults in mimi_secrets.h, with runtime overrides via the serial CLI. CLI values are stored in NVS flash and take priority over build-time values.

cp main/mimi_secrets.h.example main/mimi_secrets.h

Edit main/mimi_secrets.h:

#define MIMI_SECRET_WIFI_SSID       "YourWiFiName"
#define MIMI_SECRET_WIFI_PASS       "YourWiFiPassword"
#define MIMI_SECRET_TG_TOKEN        "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
#define MIMI_SECRET_API_KEY         "sk-ant-api03-xxxxx"
#define MIMI_SECRET_MODEL_PROVIDER  "anthropic"     // "anthropic" or "openai"
#define MIMI_SECRET_SEARCH_KEY      ""              // optional: Brave Search API key
#define MIMI_SECRET_TAVILY_KEY      ""              // optional: Tavily API key (preferred)
#define MIMI_SECRET_PROXY_HOST      ""              // optional: e.g. "10.0.0.1"
#define MIMI_SECRET_PROXY_PORT      ""              // optional: e.g. "7897"

Then build and flash:

# Clean build (required after any mimi_secrets.h change)
idf.py fullclean && idf.py build

# Find your serial port
ls /dev/cu.usb*          # macOS
ls /dev/ttyACM*          # Linux

# Flash and monitor (replace PORT with your port)
# USB adapter: likely /dev/cu.usbmodem11401 (macOS) or /dev/ttyACM0 (Linux)
idf.py -p PORT flash monitor

Important: Plug into the correct USB port! Most ESP32-S3 boards have two USB-C ports. You must use the one labeled USB (native USB Serial/JTAG), not the one labeled COM (external UART bridge). Plugging into the wrong port will cause flash/monitor failures.

Show reference photo

CLI Commands (via UART/COM port)

Connect via serial to configure or debug. Config commands let you change settings without recompiling — just plug in a USB cable anywhere.

Runtime config (saved to NVS, overrides build-time defaults):

mimi> wifi_set MySSID MyPassword   # change WiFi network
mimi> set_tg_token 123456:ABC...   # change Telegram bot token
mimi> set_api_key sk-ant-api03-... # change API key (Anthropic or OpenAI)
mimi> set_model_provider openai    # switch provider (anthropic|openai)
mimi> set_model gpt-4o             # change LLM model
mimi> set_proxy 127.0.0.1 7897  # set HTTP proxy
mimi> clear_proxy                  # remove proxy
mimi> set_search_key BSA...        # set Brave Search API key
mimi> set_tavily_key tvly-...      # set Tavily API key (preferred)
mimi> config_show                  # show all config (masked)
mimi> config_reset                 # clear NVS, revert to build-time defaults

Debug & maintenance:

mimi> wifi_status              # am I connected?
mimi> memory_read              # see what the bot remembers
mimi> memory_write "content"   # write to MEMORY.md
mimi> heap_info                # how much RAM is free?
mimi> session_list             # list all chat sessions
mimi> session_clear 12345      # wipe a conversation
mimi> heartbeat_trigger           # manually trigger a heartbeat check
mimi> cron_start                  # start cron scheduler now
mimi> restart                     # reboot

USB (JTAG) vs UART: Which Port for What

Most ESP32-S3 dev boards expose two USB-C ports:

Port	Use for
USB (JTAG)	`idf.py flash`, JTAG debugging
COM (UART)	REPL CLI, serial console

REPL requires the UART (COM) port. The USB (JTAG) port does not support interactive REPL input.

Port details & recommended workflow

Port	Label	Protocol
USB	USB / JTAG	Native USB Serial/JTAG
COM	UART / COM	External UART bridge (CP2102/CH340)

The ESP-IDF console/REPL is configured to use UART by default (CONFIG_ESP_CONSOLE_UART_DEFAULT=y).

If you have both ports connected simultaneously:

USB (JTAG) handles flash/download and provides secondary serial output
UART (COM) provides the primary interactive console for the REPL
macOS: both appear as /dev/cu.usbmodem* or /dev/cu.usbserial-* — run ls /dev/cu.usb* to identify
Linux: USB (JTAG) → /dev/ttyACM0, UART → /dev/ttyUSB0

Recommended workflow:

# Flash via USB (JTAG) port
idf.py -p /dev/cu.usbmodem11401 flash

# Open REPL via UART (COM) port
idf.py -p /dev/cu.usbserial-110 monitor
# or use any serial terminal: screen, minicom, PuTTY at 115200 baud

Memory

MimiClaw stores everything as plain text files you can read and edit:

File	What it is
`SOUL.md`	The bot's personality — edit this to change how it behaves
`USER.md`	Info about you — name, preferences, language
`MEMORY.md`	Long-term memory — things the bot should always remember
`HEARTBEAT.md`	Task list the bot checks periodically and acts on autonomously
`cron.json`	Scheduled jobs — recurring or one-shot tasks created by the AI
`2026-02-05.md`	Daily notes — what happened today
`tg_12345.jsonl`	Chat history — your conversation with the bot

Tools

MimiClaw supports tool calling for both Anthropic and OpenAI — the LLM can call tools during a conversation and loop until the task is done (ReAct pattern).

Tool	Description
`web_search`	Search the web via Tavily (preferred) or Brave for current information
`get_current_time`	Fetch current date/time via HTTP and set the system clock
`cron_add`	Schedule a recurring or one-shot task (the LLM creates cron jobs on its own)
`cron_list`	List all scheduled cron jobs
`cron_remove`	Remove a cron job by ID

To enable web search, set a Tavily API key via MIMI_SECRET_TAVILY_KEY (preferred), or a Brave Search API key via MIMI_SECRET_SEARCH_KEY in mimi_secrets.h.

Cron Tasks

MimiClaw has a built-in cron scheduler that lets the AI schedule its own tasks. The LLM can create recurring jobs ("every N seconds") or one-shot jobs ("at unix timestamp") via the cron_add tool. When a job fires, its message is injected into the agent loop — so the AI wakes up, processes the task, and responds.

Jobs are persisted to SPIFFS (cron.json) and survive reboots. Example use cases: daily summaries, periodic reminders, scheduled check-ins.

Heartbeat

The heartbeat service periodically reads HEARTBEAT.md from SPIFFS and checks for actionable tasks. If uncompleted items are found (anything that isn't an empty line, a header, or a checked - [x] box), it sends a prompt to the agent loop so the AI can act on them autonomously.

This turns MimiClaw into a proactive assistant — write tasks to HEARTBEAT.md and the bot will pick them up on the next heartbeat cycle (default: every 30 minutes).

Also Included

WebSocket gateway on port 18789 — connect from your LAN with any WebSocket client
OTA updates — flash new firmware over WiFi, no USB needed
Dual-core — network I/O and AI processing run on separate CPU cores
HTTP proxy — CONNECT tunnel support for restricted networks
Multi-provider — supports both Anthropic (Claude) and OpenAI (GPT), switchable at runtime
Cron scheduler — the AI can schedule its own recurring and one-shot tasks, persisted across reboots
Heartbeat — periodically checks a task file and prompts the AI to act autonomously
Tool use — ReAct agent loop with tool calling for both providers

For Developers

Technical details live in the docs/ folder:

docs/ARCHITECTURE.md — system design, module map, task layout, memory budget, protocols, flash partitions
docs/TODO.md — feature gap tracker and roadmap
docs/WIFI_ONBOARDING_AP.md — how the local MimiClaw-XXXX onboarding/admin AP flow works
docs/tool-setup/ — configuration guides for external service integrations (Tavily, etc.)

Contributing

Please read CONTRIBUTING.md before opening issues or pull requests.

Contributors

Thanks to everyone who has contributed to MimiClaw.

License

MIT

Acknowledgments

Inspired by OpenClaw and Nanobot. MimiClaw reimplements the core AI agent architecture for embedded hardware — no Linux, no server, just a $5 chip.

Star History

veracrypt/VeraCrypt

Disk encryption with strong security based on TrueCrypt

This archive contains the source code of VeraCrypt. It is based on the original TrueCrypt 7.1a with security enhancements and modifications.

Important

You may use the source code contained in this archive only if you accept and agree to the license terms contained in the file 'License.txt', which is included in this archive.

Note that the license specifies, for example, that a derived work must not be called 'TrueCrypt' or 'VeraCrypt'

I. Windows

II. Linux and Mac OS X

III. FreeBSD and OpenBSD

IV. Third-Party Developers (Contributors)

V. Legal Information

VI. Further Information

I. Windows

Requirements for Building VeraCrypt for Windows:

A detailed guide on how to build VeraCrypt on Windows can be found in the documentation in the repository and it is also available online or on the mirror.

IMPORTANT:

The 64-bit editions of Windows Vista and later versions of Windows, and in some cases (e.g. playback of HD DVD content) also the 32-bit editions do not allow the VeraCrypt driver to run without an appropriate digital signature. Therefore, all .sys files in official VeraCrypt binary packages are digitally signed with the digital certificate of the IDRIX, which was issued by GlobalSign certification authority. At the end of each official .exe and .sys file, there are embedded digital signatures and all related certificates (i.e. all certificates in the relevant certification chain, such as the certification authority certificates, CA-MS cross-certificate, and the IDRIX certificate).

Keep this in mind if you compile VeraCrypt and compare your binaries with the official binaries. If your binaries are unsigned, the sizes of the official binaries will usually be approximately 10 KiB greater than the sizes of your binaries (there may be further differences if you use a different version of the compiler, or if you install a different or no service pack for Visual Studio, or different hotfixes for it, or if you use different versions of the required SDKs).

Instructions for Signing and Packaging VeraCrypt for Windows:

First, create an environment variable 'WSDK81' pointing to the Windows SDK for Windows 8.1 installation directory.

The folder "Signing" contains a batch file (sign.bat) that will sign all VeraCrypt components using a code signing certificate present on the certificate store and build the final installation setup and MSI package. The batch file assumes that the code signing certificate is issued by GlobalSign. This is the case for IDRIX's certificate. If yours is issued by another CA, then you should put its intermediate certificates in the "Signing" folder and modify sign.bat accordingly.

To generate MSI packages, WiX Toolset v3.11 must be installed.

VeraCrypt EFI Boot Loader:

VeraCrypt source code contains pre-built EFI binaries under src\Boot\EFI. The source code of VeraCrypt EFI Boot Loader is licensed under LGPL and it is available at https://github.com/veracrypt/VeraCrypt-DCS. For build instructions, please refer to the file src\Boot\EFI\Readme.txt.

II. Linux and Mac OS X

A detailed guide on how to build VeraCrypt on Linux can be found in the documentation in the repository and it is also available online or on the mirror.

Requirements for Building VeraCrypt for Linux and Mac OS X:

GNU Make
GNU C++ Compiler 4.0 or compatible
Apple Xcode or Xcode command line tools (Mac OS X only)
YASM 1.3.0 or newer (Linux only, x86/x64 architecture only)
pkg-config
wxWidgets 3.0 shared library and header files installed or wxWidgets 3.0 library source code (available at https://www.wxwidgets.org)
FUSE library and header files (available at https://github.com/libfuse/libfuse and https://macfuse.github.io/)
PCSC-lite library and header files (available at https://github.com/LudovicRousseau/PCSC)

Instructions for Building VeraCrypt for Linux and Mac OS X:

Change the current directory to the root of the VeraCrypt source code.
If you have no wxWidgets shared library installed, run the following command to configure the wxWidgets static library for VeraCrypt and to build it:

$ make WXSTATIC=1 WX_ROOT=/usr/src/wxWidgets wxbuild

The variable WX_ROOT must point to the location of the source code of the wxWidgets library. Output files will be placed in the './wxrelease/' directory.
To build VeraCrypt, run the following command:

$ make

or if you have no wxWidgets shared library installed:

$ make WXSTATIC=1
If successful, the VeraCrypt executable should be located in the directory 'Main'.

Reproducible build note: when SOURCE_DATE_EPOCH is not set, a build from a git checkout uses the HEAD commit timestamp, while a build from a release tarball uses the release date in src/Common/Tcdefs.h at 00:00 UTC. To reproduce official release artifacts from a git checkout, set SOURCE_DATE_EPOCH explicitly or build from the release tarball. Vendored VeraCrypt sources tracked in another git checkout are treated the same way and use that checkout's HEAD timestamp.

Both the generated .deb and .rpm packages are reproducible, including on older rpm (e.g. CentOS/RHEL 7) that lacks the SOURCE_DATE_EPOCH/_buildhost build macros.

By default, a universal executable supporting both graphical and text user interface (through the switch --text) is built. On Linux, a console-only executable, which requires no GUI library, can be built using the 'NOGUI' parameter:

$ make NOGUI=1 WXSTATIC=1 WX_ROOT=/usr/src/wxWidgets wxbuild

$ make NOGUI=1 WXSTATIC=1

Arch Linux package build:

Arch Linux users can build and install a package from the current checkout with makepkg:

$ cd src/Build/Packaging/arch

$ makepkg -si

On MacOSX, building a console-only executable is not supported.

Mac OS X specifics:

Under MacOSX, the latest installed SDK is used by default. To use a different version of the SDK when building using make, you can export the environment variable VC_OSX_SDK:

$ export VC_OSX_SDK=13.0

For development dependencies management, you can use homebrew.

$ brew install pkg-config yasm wxwidgets

You also need system dependencies

$ brew install --cask macfuse packages

After installing dependencies via brew, you can build a local development build

$ ./src/Build/build_veracrypt_macosx.sh -b

If you want to build the package, you must pass -p to the build script above. The built executable will be in .src/Main

If you prefer to build from sources, or without homebrew, pkg-config and packages must be installed.

Get pkg-config from https://pkgconfig.freedesktop.org/releases/pkg-config-0.29.2.tar.gz and compile using the following commands:

$ CFLAGS="-Wno-int-conversion" CXXFLAGS="-Wno-int-conversion" ./configure --with-internal-glib

$ make

$ sudo make install

After making sure pkg-config is available, download and install macFUSE from https://macfuse.github.io/

The build_veracrypt_macosx.sh script performs the full build of VeraCrypt including the creation of the installer pkg. It expects to find the wxWidgets 3.2.5 sources at the same level as where you put VeraCrypt sources (i.e. if "src" path is "/Users/joe/Projects/VeraCrypt/src" then wxWidgets should be at "/Users/joe/Projects/wxWidgets-3.2.5")

The make build process uses Code Signing certificates whose ID is specified in src/Main/Main.make (look for lines containing "Developer ID Application" and "Developer ID Installer"). You'll have to modify these lines to put the ID of your Code Signing certificates or comment them out if you don't have one.

Because of incompatibility issues with macFUSE, the SDK 10.9 generates a VeraCrypt binary that has issues communicating with the macFUSE kernel extension. Thus, we recommend using a different macOS SDK version for building VeraCrypt.

The Packages installer that is used for the VeraCrypt official build has been notarized by IDRIX and it is available at https://github.com/idrassi/packages/releases

III. FreeBSD and OpenBSD

FreeBSD is supported starting from version 14. OpenBSD is supported starting from version 7.8. The build requirements and instructions are the same as Linux except that gmake should be used instead of make.

IV. Third-Party Developers (Contributors)

If you intend to implement a feature, please contact us first to make sure:

That the feature has not been implemented (we may have already implemented it, but haven't released the code yet).
That the feature is acceptable.
Whether we need the help of third-party developers with implementing the feature.

Information on how to contact us can be found at: https://veracrypt.jp or https://veracrypt.io (mirror)

V. Legal Information

Copyright Information

This software as a whole:
Copyright (c) 2026 AM Crypto. All rights reserved.

Portions of this software:
Copyright (c) 2026 AM Crypto. All rights reserved.
Copyright (c) 2013-2025 IDRIX. All rights reserved.
Copyright (c) 2003-2012 TrueCrypt Developers Association. All rights reserved.
Copyright (c) 1998-2000 Paul Le Roux. All rights reserved.
Copyright (c) 1998-2008 Brian Gladman, Worcester, UK. All rights reserved.
Copyright (c) 1995-2023 Jean-loup Gailly and Mark Adler.
Copyright (c) 2016 Disk Cryptography Services for EFI (DCS), Alex Kolotnikov
Copyright (c) 1999-2023 Dieter Baron and Thomas Klausner.
Copyright (c) 2013, Alexey Degtyarev. All rights reserved.
Copyright (c) 1999-2016 Jack Lloyd. All rights reserved.
Copyright (c) 2013-2019 Stephan Mueller smueller@chronox.de
Copyright (c) 1999-2023 Igor Pavlov

For more information, please see the legal notices attached to parts of the source code.

Trademark Information

Any trademarks contained in the source code, binaries, and/or in the documentation, are the sole property of their respective owners.

VI. Further Information

https://veracrypt.jp
https://veracrypt.io (mirror)

betaflight/betaflight

Open Source Flight Controller Firmware

Betaflight is flight controller software (firmware) used to fly multi-rotor craft and fixed wing craft. Betaflight focuses on flight performance, leading-edge feature additions, and wide target support.

Release Schedule

The Betaflight release schedule and development cadence are published at betaflight.com.

Requirements for the submission of new and updated target configuration

The requirements for pull requests adding new targets or modifying existing targets are available on the betaflight.com website.

Features

Betaflight has the following features:

Multi-color RGB LED strip support (each LED can be a different color using variable length WS2811 Addressable RGB strips - use for Orientation Indicators, Low Battery Warning, Flight Mode Status, Initialization Troubleshooting, etc)
DShot (150, 300 and 600), Multishot, Oneshot (125 and 42) and Proshot1000 motor protocol support
Blackbox flight recorder logging (to onboard flash or external microSD card where equipped)
Support for targets that use the STM32 F4, G4, F7 and H7 processors
PWM, PPM, SPI, and Serial (SBus, SumH, SumD, Spektrum 1024/2048, XBus, etc) RX connection with failsafe detection
Multiple telemetry protocols (CRSF, FrSky, HoTT smart-port, MSP, etc)
RSSI via ADC - Uses ADC to read PWM RSSI signals, tested with FrSky D4R-II, X8R, X4R-SB, & XSR
OSD support & configuration without needing third-party OSD software/firmware/comm devices
OLED Displays - Display information on: Battery voltage/current/mAh, profile, rate profile, mode, version, sensors, etc
In-flight manual PID tuning and rate adjustment
PID and filter tuning using sliders
Rate profiles and in-flight selection of them
Configurable serial ports for Serial RX, Telemetry, ESC telemetry, MSP, GPS, OSD, Sonar, etc - Use most devices on any port, softserial included
VTX support for Unify Pro and IRC Tramp
and MUCH, MUCH more.

Installation & Documentation

See: https://betaflight.com/docs/wiki

Support and Developers Channel

There's a dedicated Discord server for help, support and general community.

Betaflight Application

To configure Betaflight you should use the Betaflight App. It is a progressive web app, so should always be the latest version.

Contributing

Contributions are welcome and encouraged. You can contribute in many ways:

implement a new feature in the firmware or in the app (see below);
documentation updates and corrections;
How-To guides - received help? Help others!
bug reporting & fixes;
new feature ideas & suggestions;
provide a new translation for the app, or help us maintain the existing ones (see below).

The best place to start is the Betaflight Discord (registration here). Next place is the github issue tracker:

https://github.com/betaflight/betaflight/issues https://github.com/betaflight/betaflight-configurator/issues

Before creating new issues please check to see if there is an existing one, search first otherwise you waste people's time when they could be coding instead!

If you want to contribute to our efforts financially, please consider making a donation to us through PayPal.

If you want to contribute financially on an ongoing basis, you should consider becoming a patron for us on Patreon.

Developers

Contribution of bugfixes and new features is encouraged. Please be aware that we have a thorough review process for pull requests, and be prepared to explain what you want to achieve with your pull request. Before starting to write code, please read our development guidelines and coding style definition.

GitHub actions are used to run automatic builds.

Building with Docker/Devcontainers

A preconfigured devcontainer is included for a consistent build environment across all platforms. This is the recommended approach for Windows developers:

# With VS Code: Install "Dev Containers" extension, open folder, and select "Reopen in Container"

# Or command-line only:
docker build -t betaflight-dev -f .devcontainer/containerfile .devcontainer/
docker run --rm -v "${PWD}:/workspace" -w /workspace betaflight-dev make TARGET=SPEEDYBEEF405WING

See the devcontainer documentation for detailed setup instructions including hardware flashing.

Translators

We want to make Betaflight accessible for pilots who are not fluent in English, and for this reason we are currently maintaining translations into 21 languages for Betaflight Configurator: Català, Dansk, Deutsch, Español, Euskera, Français, Galego, Hrvatski, Bahasa Indonesia, Italiano, 日本語, 한국어, Latviešu, Português, Português Brasileiro, polski, Русский язык, Svenska, 简体中文, 繁體中文. We have got a team of volunteer translators who do this work, but additional translators are always welcome to share the workload, and we are keen to add additional languages. If you would like to help us with translations, you have got the following options:

if you help by suggesting some updates or improvements to translations in a language you are familiar with, head to crowdin and add your suggested translations there;
if you would like to start working on the translation for a new language, or take on responsibility for proof-reading the translation for a language you are very familiar with, please head to the Betaflight Discord chat (registration here), and join the 'translation' channel - the people in there can help you to get a new language added, or set you up as a proof reader.

Hardware Issues

Betaflight does not manufacture or distribute their own hardware. While we are collaborating with and supported by a number of manufacturers, we do not do any kind of hardware support.

If you encounter any hardware issues with your flight controller or another component, please contact the manufacturer or supplier of your hardware, or check Discord to see if others with the same problem have found a solution.

Betaflight Releases

You can find our release here on Github and we also have more detailed release notes at betaflight.com.

Open Source / Contributors

Betaflight is software that is open source and is available free of charge without warranty to all users.

For a complete list of contributors (past and present) see Github.

portapack-mayhem/mayhem-firmware

The firmware for the HackRF+PortaPack H1/H2/H4/H4M

PortaPack Mayhem

This is a fork of the Havoc firmware, which itself was a fork of the PortaPack firmware, an add-on for the HackRF. A fork is a derivate, in this case one that has extra features and fixes when compared to the older versions.

What is this?

If you are new to HackRF+PortaPack+Mayhem, check these:

Frequently Asked Questions

This repository expands upon the previous work by many people and aims to constantly add new features, bugfixes and generate documentation to make further development easier. Collaboration is always welcomed and appreciated.

What to buy?

✔️ The fabulous H4M complete or upgrade, featuring numerous improvements and accessories. Sold by our friends at OpenSourceSDRLab. Join their giveaways on discord (check the badge on top). EU customers can purchase via Lab401.

✔️ A recommended one is this PortaPack H2, that includes everything you need with the plastic case "inspired" on this.

✔️ Some individuals lean towards the H2 with a metal enclosure, but its advantages remain debated. Share your insights on our wiki.

⚠️ Be cautious , ask the seller about compatibility with the latest releases. Look out for the description of the item, if they provide the firmware files for an older version or they have custom setup instructions, this means it might be NOT compatible, for example:

⚠️ If it looks too different, this might mean that they are using their own recipe, check the different models in our wiki. For example all the H3 and clones of that version use their own version of the firmware. They do not contribute the changes back and eventually you will be left with a device that nobody maintains:

Where is the latest version?

The current stable release is on the page. Follow the instructions you can find in the release description. The latest (nightly) release can be found here.

How can I collaborate

We warmly welcome your contributions! Please refer to our Contributing Guidelines for details.

You can write documentation, fix bugs and answer issues or add new functionality. Please also check the following guide with details.

Consider that the hardware and firmware has been created and maintain by a lot of people, so always try collaborating your time and effort first. For coding related questions, if something does not fit as an issue, please join our Discord by clicking the chat badge on top.

To support the people behind the hardware, please buy a genuine HackRF and PortaPack.

What if I really want something specific?

If what you need can be relevant in general, you can request a feature. Alternatively, go to our Discord by clicking the chat badge on top and discuss there.

What if I need help?

First, check the documentation. If you find a bug or you think the problem is related to the current repository, please open an issue.

You can reach the official community in Facebook, and our Discord by clicking the chat badge on top.

Genymobile/scrcpy

Display and control your Android device

Warning

This GitHub repo (https://github.com/Genymobile/scrcpy) is the only official source for the project. Do not download releases from random websites, even if their name contains scrcpy.

scrcpy (v4.1)

pronounced "screen copy"

This application mirrors Android devices (video and audio) connected via USB or TCP/IP and allows control using the computer's keyboard and mouse. It does not require root access or an app installed on the device. It works on Linux, Windows, and macOS.

It focuses on:

lightness: native, displays only the device screen
performance: 30~120fps, depending on the device
quality: 1920×1080 or above
low latency: 35~70ms
low startup time: ~1 second to display the first image
non-intrusiveness: nothing is left installed on the Android device
user benefits: no account, no ads, no internet required
freedom: free and open source software

Its features include:

audio forwarding (Android 11+)
recording
virtual display
mirroring with Android device screen off
copy-paste in both directions
configurable quality
camera mirroring (Android 12+)
mirroring as a webcam (V4L2) (Linux-only)
physical keyboard and mouse simulation (HID)
gamepad support
OTG mode
and more…

Prerequisites

The Android device requires at least API 21 (Android 5.0).

Audio forwarding is supported for API >= 30 (Android 11+).

Make sure you enabled USB debugging on your device(s).

On some devices (especially Xiaomi), you might get the following error:

Injecting input events requires the caller (or the source of the instrumentation, if any) to have the INJECT_EVENTS permission.

In that case, you need to enable an additional option USB debugging (Security Settings) (this is an item different from USB debugging) to control it using a keyboard and mouse. Rebooting the device is necessary once this option is set.

Note that USB debugging is not required to run scrcpy in OTG mode.

Get the app

Must-know tips

Reducing resolution may greatly improve performance (scrcpy -m1024)
Right-click triggers BACK
Middle-click triggers HOME
Alt+f toggles fullscreen
There are many other shortcuts

Usage examples

There are a lot of options, documented in separate pages. Here are just some common examples.

Capture the screen in H.265 (better quality), limit the size to 1920, limit the frame rate to 60fps, disable audio, and control the device by simulating a physical keyboard:
```
scrcpy --video-codec=h265 --max-size=1920 --max-fps=60 --no-audio --keyboard=uhid
scrcpy --video-codec=h265 -m1920 --max-fps=60 --no-audio -K  # short version
```
Start VLC in a new virtual display (separate from the device display):
```
scrcpy --new-display=1920x1080 --start-app=org.videolan.vlc
```
Start VLC in a new flex display using H.265 with a bitrate of 16 Mbps, while keeping the display active so it does not turn off:
```
scrcpy --new-display -x --keep-active --start-app=org.videolan.vlc --video-codec=h265 -b16M
```

Record the device camera in H.265 at 1920x1080 (and microphone) to an MP4 file:

scrcpy --video-source=camera --video-codec=h265 --camera-size=1920x1080 --record=file.mp4

Capture the device front camera and expose it as a webcam on the computer (on Linux):

scrcpy --video-source=camera --camera-size=1920x1080 --camera-facing=front --v4l2-sink=/dev/video2 --no-playback

Control the device without mirroring by simulating a physical keyboard and mouse (USB debugging not required):
```
scrcpy --otg
```
Control the device using gamepads plugged into the computer:
```
scrcpy --gamepad=uhid
scrcpy -G  # short version
```

User documentation

The application provides a lot of features and configuration options. They are documented in the following pages:

Resources

FAQ
Translations (not necessarily up to date)
Build instructions
Developers
Verify release signatures

Articles

Contact

You can open an issue for bug reports, feature requests or general questions.

For bug reports, please read the FAQ first, you might find a solution to your problem immediately.

You can also use:

Reddit: r/scrcpy
BlueSky: @scrcpy.bsky.social
Twitter: @scrcpy_app

Donate

I'm @rom1v, the author and maintainer of scrcpy.

If you appreciate this application, you can support my open source work:

License

Copyright (C) 2018 Genymobile
Copyright (C) 2018-2026 Romain Vimont

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

HermannBjorgvin/Clawdmeter

ESP32 desk dashboard that shows Claude Code usage

Clawdmeter

A small ESP32 dashboard I made for my desk to keep an eye on Claude Code usage.

It runs on a Waveshare ESP32-S3-Touch-AMOLED-2.16 as well as a few other alternative boards and pairs over Bluetooth, the splash screen plays pixel-art Clawd animations that get busier when your usage rate climbs. The two side buttons send Space and Shift+Tab over BLE HID for Claude Code's voice mode and mode-toggle shortcuts.

Screens

The device boots into the splash. Tap the screen anywhere to switch to the Usage view; tap again to flip back to the splash.

Splash	Usage

Splash; touch-toggle anytime	Session and weekly utilization

While the splash is up, the middle (PWR) button cycles animations. Hold the power button for 3 seconds, then release, to put the device into pairing mode — this clears the saved Bluetooth bond and re-advertises. The firmware also auto-rotates animations every 20 s within the current usage-rate group, so a long stretch on the splash isn't just one Clawd on loop.

Hardware

Boards supported out of the box:

Please check if a pull request exists for your alternative hardware port before opening a new one, providing QA feedback and testing on the same hardware is more valuable than duplicate pull requests.

Porting to another board: the firmware is a thin HAL with per-board folders under firmware/src/boards/. Drop in a new folder and a new PlatformIO env — main.cpp, ui.cpp, and splash.cpp never need to change. See docs/porting/adding-a-board.md for the walk-through and docs/porting/hal-contract.md for the interfaces a port must implement.

Prerequisites

Linux (tested on Ubuntu), macOS, or Windows 10/11
PlatformIO CLI
Linux: curl, bluetoothctl, busctl (BlueZ Bluetooth stack)
macOS: python3 (the installer sets up a venv with bleak and httpx)
Windows: python3 3.11+ (the installer sets up a venv with bleak, httpx, and pystray)
Claude Code with an active subscription

macOS installation

The macOS host pieces — Python daemon, LaunchAgent, and flash helper — were ported by Chris Davidson (@lorddavidson). Thanks Chris!

Flash the firmware

./flash-mac.sh waveshare_amoled_216                       # auto-detects /dev/cu.usbmodem*
./flash-mac.sh waveshare_amoled_18  /dev/cu.usbmodem1101  # or pass an explicit USB serial port

The board env name is required. Run ./flash-mac.sh with no args to see the available envs (scraped from firmware/platformio.ini).

Pair the device

After flashing, open System Settings → Bluetooth and click Connect next to "Clawdmeter". The daemon only ever connects to the peripheral this Mac is paired/connected to — it never scans for a nearby device — so once it's connected here the daemon picks it up on its next poll (~60 s).

Install the daemon

The daemon reads your Claude OAuth token from the macOS Keychain (service Claude Code-credentials), polls usage every 60 s, and pushes it to the display over BLE.

./install-mac.sh

The installer creates a Python venv in daemon/.venv/, installs bleak and httpx, renders a LaunchAgent into ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist, and loads it. The first run is launched interactively so macOS prompts for Bluetooth permission.

Useful commands:

launchctl list | grep claude-usage                                          # check it's running
tail -F ~/Library/Logs/claude-usage-daemon.out.log                          # live logs
launchctl unload ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist  # stop
launchctl load -w ~/Library/LaunchAgents/com.user.claude-usage-daemon.plist # start

Linux installation

Flash the firmware

./flash.sh waveshare_amoled_216                  # defaults to /dev/ttyACM0
./flash.sh waveshare_amoled_18  /dev/ttyACM1     # or pass an explicit USB serial port

The board env name is required. Run ./flash.sh with no args to see the available envs (scraped from firmware/platformio.ini).

Pair the device

After flashing, the device advertises as "Clawdmeter". Pair it once:

# Scan for the device
bluetoothctl scan le

# When "Clawdmeter" appears, pair and trust it
bluetoothctl pair F4:12:FA:C0:8F:E5    # use your device's MAC
bluetoothctl trust F4:12:FA:C0:8F:E5

To re-pair later, hold the power button for 3 seconds then release — the device clears its saved bond and re-advertises.

Install the daemon

The daemon polls your Claude usage every 60 seconds and sends it to the display over BLE.

./install.sh
systemctl --user start claude-usage-daemon

Check status: systemctl --user status claude-usage-daemon

View logs: journalctl --user -u claude-usage-daemon -f

Windows installation

Runs natively on Windows — no WSL required. A system-tray app polls your usage and pushes it over BLE, and starts automatically at login.

Prerequisites

Native Windows (not WSL).
Python 3.11+ from python.org — check "Add python.exe to PATH" during install.
Claude Code installed, with claude login completed. The token is read from %USERPROFILE%\.claude\.credentials.json (falling back to %LOCALAPPDATA%\Claude\ then %APPDATA%\Claude\).
The repo on a native Windows path (e.g. %USERPROFILE%\Clawdmeter), not a \\wsl$ share — the installer refuses a WSL path.

Flash the firmware

pio run -d firmware -e waveshare_amoled_216 -t upload --upload-port COM5   # use your device's COM port

Run pio run -d firmware with no env to see the available board envs.

Pair the device

The device is a bonded BLE HID keyboard, so pair it once: Settings → Bluetooth & devices → Add device → Bluetooth, then select "Clawdmeter". Pairing is required — it enables the physical buttons and keeps a persistent connection (the device keeps showing your last-synced usage even after the daemon quits). To undo, use Remove device (this disables the buttons).

Install the daemon (recommended)

From the repo root in PowerShell:

powershell -ExecutionPolicy Bypass -File install-windows.ps1

This creates a venv, installs bleak/httpx/pystray/Pillow from the in-repo requirements (no internet downloads), registers a per-user login-autostart entry (HKCU\…\Run, no admin needed), and launches the tray app headlessly (no console window).

Run manually instead (optional)

python -m venv .venv
.venv\Scripts\Activate.ps1        # if blocked: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned, then retry
pip install -r daemon\requirements-windows.txt
python daemon\claude_usage_daemon_windows.py        # runs in the foreground; Ctrl+C to stop

Tray icon and menu

The icon's corner bubble shows state — green Connected, amber Scanning, red Error — and hovering shows the status (Connected · last update HH:MM). A notification fires once when it enters Error (e.g. an expired token). Right-click for the menu:

Status header — live state + last sync time.
Start at login — toggle autostart on/off.
Quit — stops the daemon cleanly; leaves the Windows pairing intact (device keeps its last reading).

Logs and troubleshooting

Get-Content $env:LOCALAPPDATA\Clawdmeter\daemon.log -Tail 30        # view logs
reg delete "HKCU\Software\Microsoft\Windows\CurrentVersion\Run" /v Clawdmeter /f   # remove autostart

Symptom	Fix
`Device not found`	Power on the device; make sure it's in range and paired.
`token expired` toast / `API HTTP 401`	Re-run `claude login`, then restart the daemon.
`Connection failed`	Toggle Windows Bluetooth off/on in Settings.
`Warning: running under Linux/WSL`	Run from a native PowerShell window, not a WSL shell.

How it works

The daemon reads your Claude Code OAuth token — from the macOS Keychain (service Claude Code-credentials) on macOS, or from ~/.claude/.credentials.json on Linux (%USERPROFILE%\.claude\.credentials.json on Windows).
It makes a minimal API call to api.anthropic.com/v1/messages — one token of Haiku, basically free.
The usage numbers come straight out of the response headers (anthropic-ratelimit-unified-5h-utilization and friends).
The daemon connects to the ESP32 over BLE and writes a JSON payload to the GATT RX characteristic.
The firmware parses it and updates the LVGL dashboard.
The firmware also tracks the rate of change of session % over a 5-minute window and picks splash animations from the matching mood group.
The two side buttons are independent of all of this — they send Space and Shift+Tab as BLE HID keyboard input to the paired host directly.

Physical buttons

The board has three side buttons. Left and right send HID keys; the middle (PWR) button cycles splash animations and, held for 3 seconds, triggers pairing mode.

Button	GPIO	Function
Left	GPIO 0	Hold to send Space (Claude Code voice-mode push-to-talk)
Middle (PWR)	AXP2101 PKEY	On splash: cycle animations. Hold 3s + release: pairing mode
Right	GPIO 18	Press to send Shift+Tab (Claude Code mode toggle)

Space and Shift+Tab go out as standard BLE HID keyboard reports, so they trigger in whatever window has focus on the paired host — not just Claude Code.

BLE protocol

The device advertises a custom GATT service alongside the standard HID keyboard service:

	UUID
Data Service	`4c41555a-4465-7669-6365-000000000001`
RX Characteristic (write)	`4c41555a-4465-7669-6365-000000000002`
TX Characteristic (notify)	`4c41555a-4465-7669-6365-000000000003`
HID Service	`00001812-0000-1000-8000-00805f9b34fb`

JSON payload format (written to RX):

{ "s": 45, "sr": 120, "w": 28, "wr": 7200, "st": "allowed", "ok": true }

Fields: s = session %, sr = session reset (minutes), w = weekly %, wr = weekly reset (minutes), st = status, ok = success flag.

Development

Desktop simulator — iterate on the UI without hardware: an SDL2 window runs the full firmware loop with scenario playback (pio run -d firmware -e sim, then cd firmware && .pio/build/sim/program). See SIM-USAGE.md for controls, scenarios, and headless screenshots.
Splash animations — Anthropic's official Clawd sprites, archived with provenance notes in research/clawd-official/; node tools/convert_official_clawd.js regenerates firmware/src/splash_animations.h. See tools/README.md.
Icons — Lucide PNGs convert to LVGL C arrays with tools/png_to_lvgl.js. See tools/README.md.
Fonts — the pre-compiled LVGL fonts and the LVGL-9 patching they need: docs/fonts.md.
Porting — docs/porting/adding-a-board.md and docs/porting/hal-contract.md.

Credits

Pixel-art Clawd animations are Anthropic's official mascot art (claude.ai/code, Claude Code desktop), archived and converted by the tooling in tools/ and research/clawd-official/.
Lucide icon set (lucide.dev, MIT) for bluetooth and battery UI glyphs.
Anthropic brand fonts (Tiempos Text, Styrene B) — see licensing warning below.

Licensing gray area warning

The software in this repository uses and adheres to the Anthropic brand guidelines and uses the same proprietary fonts that Anthropic has a license for but this software uses without permission as well as using assets from Anthropic such as the copyrighted Clawd mascot so even though the code in this repo is non-proprietary I will not license it myself under a copyleft license since this repo includes proprietary fonts and copyrighted assets. Please be aware of this if you fork or copy the code from this repo. You have been warned!

greatscottgadgets/hackrf

low cost software radio platform

HackRF

This repository contains hardware designs and software for HackRF, a low cost, open source Software Defined Radio platform.

(photo by fd0 from https://github.com/fd0/hackrf-one-pictures)

principal author: Michael Ossmann mike@ossmann.com

Information on HackRF and purchasing HackRF: https://greatscottgadgets.com/hackrf/

Documentation

Documentation for HackRF can be viewed on Read the Docs. The raw documentation files for HackRF are in the docs folder in this repository and can be built locally by installing Sphinx Docs and running make html. Documentation changes can be submitted through pull request and suggestions can be made as GitHub issues.

To create a PDF of the HackRF documentation from the HackRF repository while on Ubuntu:

run sudo apt install latexmk texlive-latex-extra
navigate to hackrf/docs on command line
run the command make latex
run the command make latexpdf

Getting Help

Before asking for help with HackRF, check to see if your question is listed on the troubleshooting page.

For assistance with HackRF general use or development, please look at the issues on the GitHub project. This is the preferred place to ask questions so that others may locate the answer to your question in the future.

We invite you to join our community discussions on Discord. Note that while technical support requests are welcome here, we do not have support staff on duty at all times. Be sure to also submit an issue on GitHub if you've found a bug or if you want to ensure that your request will be tracked and not overlooked.

If you wish to see past discussions and questions about HackRF, you may also view the mailing list archives.

GitHub issues on this repository that are labelled "technical support" by Great Scott Gadgets employees can expect a response time of two weeks. We currently do not have expected response times for other GitHub issues or pull requests for this repository.

armel/uv-k1-k5v3-firmware-custom

This is a fork of F4HWN firmware https://github.com/armel/uv-k5-firmware-custom by @muzkr and @armel

Stats

F4HWN firmware port for the UV-K1 and UV-K5 V3 using the PY32F071 MCU

This repository is a fork of the F4HWN custom firmware, who was a fork of Egzumer custom firmware. It extends the work done for the UV-K5 V1, based on the DP32G030 MCU, and adapts it to the newer UV-K1 and UV-K5 V3 built around the PY32F071 MCU. It is the result of the joint work of @muzkr and @armel.

A big thanks to DualTachyon, who paved the way by releasing the very first open-source firmware for the UV-K5 V1. None of this would have been possible without that initial work !

A note for developers who intend to fork this project

This firmware is distributed under the Apache 2.0 License, carrying forward the original copyright of DualTachyon, whose work laid the foundation for the UV-K5 open-source ecosystem. If you create a fork or a derived version, we strongly encourage you to keep your work open source.

Keeping your fork open:

aligns with the intent and spirit of the Apache 2.0 License
supports the amateur-radio and embedded-development community
avoids unnecessary fragmentation
allows others to study, audit and improve the firmware

It is also very much in line with the ham spirit: sharing knowledge, experimenting together and helping each other, rather than closing things off or claiming them as your own.

Maintaining an open-source fork is the best way to help build a healthy and sustainable ecosystem for everyone.

Warning

EN - THIS FIRMWARE HAS NO REAL BRAIN. PLEASE USE YOUR OWN. Use this firmware at your own risk (entirely). There is absolutely no guarantee that it will work in any way shape or form on your radio(s), it may even brick your radio(s), in which case, you'd need to buy another radio. Anyway, have fun.

FR - CE FIRMWARE N'A PAS DE VÉRITABLE CERVEAU. VEUILLEZ UTILISER LE VÔTRE. Utilisez ce firmware à vos risques et périls. Il n'y a absolument aucune garantie qu'il fonctionnera d'une manière ou d'une autre sur votre (vos) radio(s), il peut même bousiller votre (vos) radio(s), dans ce cas, vous devrez acheter une autre radio. Quoi qu'il en soit, amusez-vous bien.

Note

EN - About CHIRP, as with many other firmwares, you need to use a dedicated driver. The matching CHIRP driver is now bundled with each release of this repository, so you can download the firmware and its driver together from the Releases page.

FR - A propos de CHIRP, comme pour beaucoup d'autres firmwares, vous devez utiliser un pilote dédié. Le driver CHIRP correspondant est désormais fourni avec chaque release de ce dépôt, ce qui permet de récupérer ensemble le firmware et son pilote depuis la page des Releases.

Caution

EN - I recommend backing up your calibration data with UV Studio immediately after flashing this firmware. It is a good habit to adopt.

FR - Je recommande de sauvegarder vos données de calibration avec UV Studio juste après avoir flashé ce firmware. C'est un bon réflexe à adopter.

Donations

Special thanks to Jean-Cyrille F6IWW (3 times), Fabrice 14RC123, David F4BPP, Olivier 14RC206, Frédéric F4ESO, Stéphane F5LGW (2 times), Jorge Ornelas (4 times), Laurent F4AXK, Christophe Morel, Clayton W0LED, Pierre Antoine F6FWB, Jean-Claude 14FRS3306, Thierry F4GVO, Eric F1NOU, PricelessToolkit, Ady M6NYJ, Tom McGovern (4 times), Joseph Roth, Pierre-Yves Colin, Frank DJ7FG, Marcel Testaz, Brian Frobisher, Yannick F4JFO, Paolo Bussola, Dirk DL8DF, Levente Szőke (2 times), Bernard-Michel Herrera, Jérôme Saintespes, Paul Davies, RS (3 times), Johan F4WAT, Robert Wörle, Rafael Sundorf, Paul Harker, Peter Fintl, Pascal F4ICR (2 times), Mike DL2MF (3 times), Eric KI1C / F4WFS (3 times), Phil G0ELM, Jérôme Lambert, Eliot Vedel, Alfonso EA7KDF, Jean-François F1EVM, Robert DC1RDB (2 times), Ian KE2CHJ, Daryl VK3AWA, Roberto Brunelli, Robert Boardman, Stephen Oliver, Nicolas F4INE, William Bruno, Daniel OK2VLK, Tayler Chew, Peter DL7RFP, Philippe Kopp, Rune LA6YMA, Jeremy Luna, Steef Wagenaar (2 times), Zhuo BG7SGA, Jamie M0JLB, Antoine LIBERT, Vince K0DKR, Julia DF7JA, Ken 2E0UMK, Victor TI2SYS, Tobi DG9LAY, Deaglan K4DFQ, Catherine PALMER, Brian WA6JFK, Stéphane Hintzy, Roger F1HCN, Marcin Kusaj, Flavio Cottarelli, Bob N1MLZ, Carlos EA1IJ, Brian M7YLF, Giuseppe IT9LLH and 邓月 for their donations. That’s so kind of them. Thanks so much 🙏🏻

Main features and improvements from F4HWN

Fusion edition

Fusion is the reference edition of the project. It provides an all-in-one firmware for the UV-K1 and UV-K5 V3, including:

Fagci's spectrum analyzer,
broadcast FM radio,
VOX and AirCopy,
BEAM wireless channel transfer,
UV Studio with integrated K5Viewer screen mirroring, screenshots and remote keyboard control,
advanced RX audio profiles and Audio Scope,
first-responder-oriented controls,
the Breakout game,
automatic RX/TX activity logging with RF Log,
full Fox Hunt and Morse Beacon support.

Radio and signal handling

Reworked output-power levels:
- Low 1: below approximately 20 mW,
- Low 2: approximately 125 mW,
- Low 3: approximately 250 mW,
- Low 4: approximately 500 mW,
- Low 5: approximately 1 W,
- Mid: approximately 2 W,
- High: approximately 5 W,
- User: configurable through SetPwr.
S-meter calibrated according to the IARU Region 1 recommendation for VHF/UHF:
- fixed S0 to S9+ values replace the former EEPROM S-meter thresholds,
- Classic and Tiny display styles are available.
Configurable 12.5 kHz or 6.25 kHz narrow-FM bandwidth.
Per-channel TX lock.
Adjustable RX audio volume.
Advanced RX audio profiles for FM and AM reception.
Regional frequency-lock profiles for amateur bands, PMR446, FRS, GMRS and MURS.
Support for 1600, 2200 and 3500 mAh battery profiles.

Spectrum analyzer

Channel names displayed in the spectrum view.
Persistent spectrum settings.
Faster and smoother spectrum rendering.
Improved behavior when freezing the spectrum or disconnecting USB-C.
Spectrum analyzer state can be restored automatically at startup.

Scanning

Support for up to 24 named scan lists.
Each memory channel can be assigned to:
- OFF,
- one scan list from 01 to 24,
- ALL.
The ALL list scans every channel except those assigned to OFF.
Automatic selection of the next valid list when the requested list is empty.
Direct scan-list selection while scanning:
- 00 selects ALL,
- 01 to 24 select the corresponding list.
Long press on MENU while scanning to exclude the current memory channel.
Up to 64 frequency exclusions.
Very fast scanning mode, reaching approximately 150 frequencies per second.
Scan progress, RSSI and detected CTCSS/DCS information.
Configurable scan resume behavior.
Scan state can be restored automatically at startup.

User interface

Improved VFO screen with:
- Classic and Tiny S-meter styles,
- Classic and Tiny frequency-information layouts,
- MAIN ONLY, DUAL and CROSS display modes,
- RX activity indication on the active VFO,
- optional RX LED blinking,
- squelch, monitor, step and CTCSS/DCS information,
- last-RX indication,
- RX and TX timers.
Improved status bar with updated fonts and icons.
Menu index remains visible while editing an entry.
Improved frequency and memory-channel input.
Improved audio-level display.
AirCopy progress percentage and gauge.
Smooth backlight fading.
Manual backlight controls for quickly switching between minimum and maximum brightness.
Configurable contrast and inverted-display mode.
Configurable navigation layout for the different radio models.
Improved power-on message and optional startup logo.
System-information pages for:
- firmware version and build information,
- battery information,
- Flash and SRAM usage,
- project and documentation QR codes.

Audio and transmission controls

Classic and OnePush PTT modes.
Configurable timeout-timer alerts:
- disabled,
- sound,
- visual,
- sound and visual.
Configurable end-of-transmission alerts using the same modes.
Audio Scope during RX and TX.
Improved Audio Scope behavior with OnePush PTT, DTMF and the 1750 Hz tone.
Configurable automatic deep-sleep timeout.
Quick actions for:
- RX mode,
- main-VFO-only display,
- PTT,
- wide/narrow bandwidth,
- 1750 Hz tone,
- mute,
- RX audio profile,
- maximum power,
- offset removal.

Fox Hunt and Beacon

Dedicated Fox Hunt receiver with:
- calibrated S-meter display,
- scrolling signal-history graph,
- peak, minimum and trend indicators,
- selectable RF attenuation,
- silent, Geiger-style and received-audio modes,
- long-press F keypad lock (attenuation stays adjustable with the arrow keys).
Integrated Morse Beacon transmitter with:
- MOE, MOI, MOS, MOH, MO5 and MO identifiers,
- optional callsign identification,
- configurable TX and idle periods,
- live TX and idle countdowns,
- persisted Beacon settings,
- interactive control during transmission,
- shared long-press F keypad lock,
- TX-lock, modulation and battery-safety checks.
Fox Hunt and Beacon screens are mirrored to UV Studio's integrated K5Viewer.

RF Log

Automatic logging of RX and TX activity when RF Log is enabled.
Logs stored in the radio's external Flash memory.
Recorded information includes:
- RX or TX direction,
- frequency and channel,
- channel name,
- activity duration,
- S-meter level,
- battery voltage.
On-radio history with RX/TX filtering and detailed views.
Live RF Log dashboard and history access through UV Studio.

Connectivity and data transfer

Live screen streaming to UV Studio over a USB serial connection.
Screenshot capture and download.
Remote keyboard control through the integrated K5Viewer.
Automatic reconnection after a USB disconnect.
RF Log monitoring, analytics and CSV export.
Firmware flashing, calibration backup and restore, and boot-logo management from the same interface.
BEAM transfer of complete channel settings between compatible radios.
Improved AirCopy interface and progress reporting.

Settings and controls

New or extended menu entries:
- SetPwr: configurable User output power,
- SetPTT: Classic or OnePush PTT,
- SetTOT: timeout-timer alert,
- SetEOT: end-of-transmission alert,
- SetCtr: display contrast,
- SetInv: inverted display,
- SetLck: keypad or keypad-and-PTT lock,
- SetMet: S-meter style,
- SetGUI: VFO information style,
- SetRxA: RX audio profile,
- SetTmr: RX and TX timers,
- SetOff: automatic deep-sleep delay,
- SetNFM: narrow-FM bandwidth,
- SetVol: RX audio volume,
- SetScn: scan mode,
- SetNav: radio-specific navigation layout.
Improved PonMsg, BackLt, TxTOut, ScnRev and KeyLck menus.
Full VFO state restoration with a long press on EXIT.
Squelch changes made with F + UP or F + DOWN are persisted.

Keyboard shortcuts and assignable actions

F + UP or F + DOWN: adjust the squelch level.
F + F1 or F + F2: adjust the frequency step.
F + 8: temporarily switch the backlight between minimum and maximum brightness.
F + 9: return to the configured backlight strategy.
Configurable short- and long-press actions include:
- RX mode,
- main-VFO-only display,
- virtual PTT,
- wide/narrow bandwidth,
- 1750 Hz tone,
- mute,
- RX audio profile,
- maximum power,
- offset removal,
- BEAM,
- RF Log,
- Fox Hunt / Beacon.

Reliability and optimization

Improved squelch and S-meter behavior.
Fixed DTMF overlay issues.
Fixed scan-range limits.
Cleaner startup display.
Removed PWM-related audio noise.
Improved serial and K5Viewer key handling.
Improved VFO persistence and restoration.
Extensive code refactoring and memory optimization.
DTMF calling and the scrambler remain disabled in Fusion.
Legacy AM Fix code is not used by this firmware.

Main features from Egzumer:

many of OneOfEleven mods:
- AM fix, huge improvement in reception quality
- long press buttons functions replicating F+ action
- fast scanning
- channel name editing in the menu
- channel name + frequency display option
- shortcut for scan-list assignment (long press 5 NOAA)
- scan-list toggle (long press * Scan while scanning)
- configurable button function selectable from menu
- battery percentage/voltage on status bar, selectable from menu
- longer backlight times
- mic bar
- RSSI s-meter
- more frequency steps
- squelch more sensitive
fagci spectrum analyzer (F+5 to turn on)
some other mods introduced by me:
- SSB demodulation (adopted from fagci)
- backlight dimming
- battery voltage calibration from menu
- better battery percentage calculation, selectable for 1600mAh or 2200mAh
- more configurable button functions
- long press MENU as another configurable button
- better DCS/CTCSS scanning in the menu (* SCAN while in RX DCS/CTCSS menu item)
- Piotr022 style s-meter
- restore initial freq/channel when scanning stopped with EXIT, remember last found transmission with MENU button
- reordered and renamed menu entries
- LCD interference crash fix
- many others...

Manual

Up to date manual is available in the Wiki section

Radio performance

Please note that the Quansheng UV-Kx radios are not professional quality transceivers, their performance is strictly limited. The RX front end has no track-tuned band pass filtering at all, and so are wide band/wide open to any and all signals over a large frequency range.

Using the radio in high intensity RF environments will most likely make reception difficult, especially in AM mode. The receiver simply does not have a great dynamic range, so stronger signals can easily cause distortion, desensitization and poor AM audio. This is fundamentally a hardware limitation: firmware can improve behavior at the margins, but it cannot overcome the front-end design of the radio. In practice, AM reception will degrade first and most severely, while FM reception is generally more tolerant and should remain more usable.

But, they are nice toys for the price, fun to play with.

Compiling and Building from Docker

This project provides a Docker-based build system to compile the Fusion firmware for the UV-K1 and UV-K5 V3. Everything is handled through the compile-with-docker.sh helper script.

The documented build output is generated inside build/Fusion, using the CMake presets defined in CMakePresets.json.

Prerequisites

Docker installed on your system
Bash environment (Linux, macOS, WSL, Git Bash on Windows)

Build Script Overview

The script compile-with-docker.sh performs the following actions:

Builds the Docker image (uvk1-uvk5v3) if it does not already exist.
Removes any previous build directory to ensure a clean configuration.
Runs CMake using the Fusion preset inside the Docker container.
Builds the firmware and outputs .elf, .bin and .hex files.

Usage

./compile-with-docker.sh Fusion [extra CMake options]

Documented Preset

Fusion

Examples

Build Fusion:

./compile-with-docker.sh Fusion

Passing Additional CMake Options

You can pass extra configuration options after the preset name.
These are forwarded directly to cmake --preset inside the container.

Examples:

./compile-with-docker.sh Fusion -DENABLE_SPECTRUM=ON
./compile-with-docker.sh Fusion -DENABLE_FEAT_F4HWN_GAME=ON -DENABLE_NOAA=ON
./compile-with-docker.sh Fusion -DSQL_TONE=600

To prepare the rolling development firmware:

./compile-with-docker.sh Fusion -DDEV=ON

This keeps the regular build output in build/Fusion and also updates archive/f4hwn.fusion.development.bin. The development build is identified as DEV in the firmware information screen. Publishing the updated archive file remains an explicit Git operation.

Notes

The first run may take a few minutes while Docker builds the base image.
Each build runs inside Docker, so your host environment remains clean.

Flashing the Firmware with UV Studio

You can flash the UV-K5 V3 and UV-K1 directly from your web browser using the Web Serial-based UV Studio.

UV Studio combines firmware flashing, calibration maintenance, boot-logo management, K5Viewer and RF Log in a single interface. It requires no application installation, server or account. Use a desktop browser with Web Serial support, such as Chrome, Brave, Edge, Opera or Firefox 151+.

Steps to flash the firmware

Open the Flash Firmware view in UV Studio.
Connect your radio to your computer using a compatible USB programming cable (USB-C or Baofeng/Kenwood like double jack USB cable).
Make sure your radio is in DFU mode (flash mode).
Select an official F4HWN Fusion release from the catalog or load a local .bin firmware file.
Click on Flash Firmware, then select the serial port associated with your radio.
The progress bar will guide you through the flashing steps.

Once finished, your radio restarts with the new firmware.

Steps to dump or restore calibration data

UV Studio can also dump and restore calibration data, which is highly recommended. It is best to create a dump immediately after installing the F4HWN firmware, and to restore it before installing another firmware or returning to the stock firmware.

Dump

Open the Dump Calibration view in UV Studio.
Power on your radio in normal mode.
Click Dump Calibration Data.

When the process is complete, click Download calibration.dat to save the file to your computer.

Note

A good practice is to rename your calibration file using the serial number of your radio, which you can find on the label on the back of the device once you remove the battery. This helps avoid mixing up calibration files when you own multiple units.

Restore

Open the Restore Calibration view in UV Studio.
Power on your radio in normal mode.
Select your calibration.dat file on your computer.

Click Restore Calibration Data and wait until the process fully completes.

Other sources of information

k1-teardown

Credits

Many thanks to various people:

Muzkr
Mrkusypl
Andrej
Egzumer
OneOfEleven
DualTachyon
Mikhail
Manuel
@wagner
@Lohtse Shar
@Matoz
@Davide
@Ismo OH2FTG
OneOfEleven
@d1ced95
and others I forget

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

RfidResearchGroup/proxmark3

Iceman Fork - Proxmark3

The Proxmark3 is the swiss-army tool of RFID, allowing for interactions with the vast majority of RFID tags on a global scale. Originally built by Jonathan Westhues, the device is now the goto tool for RFID Analysis for the enthusiast. Iceman repository is considered to be the pinnacle of features and functionality, enabling a huge range of extremely useful and convenient commands and LUA scripts to automate chip identification, penetration testing, and programming

Latest Release	Coverity	Contributors

Actions OSX CI	Actions Ubuntu CI	Actions Windows CI

PROXMARK3 INSTALLATION AND OVERVIEW

Installation	Use of the Proxmark3
Linux - Setup and Build	Compilation Instructions
Linux - Important notes on ModemManager	Validating Proxmark3 Client Functionality
macOS - Homebrew & Upgrading HomeBrew Tap Formula	First Use and Verification
macOS - MacPorts	Commands & Features
macOS - Setup and Build	Standalone Modes
Windows - Setup and Build
Termux / Android - Setup and Build
iOS - Setup and Build
Blue Shark Manual	Command Cheat Sheet
Advanced Compilation Parameters	More Cheat Sheets
Troubleshooting	Complete Client Command Set
JTAG	T5577 Introduction Guide

Notes / helpful documents

Notes
Notes on UART	Notes on Termux / Android	Notes on paths
Notes on frame format	Notes on tracelog / wireshark	Notes on EMV
Notes on external flash	Notes on loclass	Notes on Coverity Scan Config & Run
Notes on file formats used with Proxmark3	Notes on MFU binary format	Notes on FPGA & ARM
Developing standalone mode	Wiki about standalone mode	Notes on Magic UID cards
Notes on Color usage	Makefile vs CMake	Notes on Cloner guns
Notes on cliparser usage	Notes on clocks	Notes on MIFARE DESFire
Notes on CIPURSE	Notes on NDEF type4a	Unofficial MIFARE DESFire bible

How to build?

Proxmark3 RDV4

See the instruction links in the tables above to build, flash and run for your Proxmark3 RDV4 device.

Generic Proxmark3 platforms

In order to build this repo for generic Proxmark3 platforms we urge you to read Advanced compilation parameters

We define generic Proxmark3 platforms as following devices.

Supported

RDV1, RDV2, RDV3 easy
Ryscorp green PCB version
Radiowar black PCB version
numerous Chinese adapted versions of the RDV3 easy (kkmoon, PiSwords etc)
Proxmark3 SE (Special Edition) (BLE enabled)
Proxmark3 X
- Note: Community tested
- Note: unknown device hw

Not supported

⚠ Proxmark Evolution (EVO)
- Note: unknown pin assignments.
⚠ Ryscorp Proxmark3 Pro
- Note: device has different fpga and unknown pin assignments.
- Note: Company have disappeared, leaving their customers in the dark.

Experimental support

⚠ iCopy-X
- Note: currently incompatible with iCopy-X GUI as Proxmark client commands using different syntax
- Note: see also icopyx-community repos for upstream sources, reversed hw etc.
- Note: Uses DRM to lock down tags, ignores the open source licences. Use on your own risk.
⚠ Proxmark3 Ultimate
- Note: unknown device hw
- Note: FPGA images is building for it. Use on your own risk.

Unknown support status

⚠ VX
- Note: unknown device hw

When it comes to these new unknown models we are depending on the community to report in if this repo works and what they did to make it work.

256KB flash memory size of generic Proxmark3 platforms

⚠ Note: You need to keep a eye on how large your ARM chip built-in flash memory is. With 512KB you are fine but if its 256KB you need to compile this repo with even less functionality. When running the ./pm3-flash-all you can see which size your device have if you have the bootloader from this repo installed. Otherwise you will find the size reported in the start message when running the Proxmark3 client ./pm3.

OBS! Read the 256KB flash memory advisory

What has changed?

Proxmark3 RDV4 hardware modifications:

added flash memory 256KB
added smart card module
added FPC connector for peripherals such as Bluetooth+battery addon
improved antennas
- swappable
- LF Q factor switch
- LF 125/134 frequency switch
tiny PCB form factor
ABS case

This repo vs official Proxmark3 repo:

See the Changelog file which we try to keep updated.

In short this repo gives you a completely different user experience when it comes to Proxmark3.

Supports command tab complete
Richer CLI with use of colors / emojis
Help text system implemented everywhere
Hints system
User preference settings
Extensive testing with continuous integration build systems on Linux, OSX and Windows, and regular usage of static analysis tools like
- Coverity Scan
- Cppcheck (v2.6)
- GCC and Clang aggressive enforcement of diagnostic flags
Auto detection of serial ports and seamless integration with Bluetooth addon
Reconnect to device from inside client
Supports tearoff attacks
Supports NFC NDEF type1, type2, type4a, type4b, mifare, barcode
Supports pm3 client scripts, lua scripts, python scripts
Most comprehensive collection of scripts available
Wiegand encoding, decoding.
Supports EMV
Supports CIPURSE
Most standalone modes available with easy compilation
Extensive test script for client and external tools
Most comprehensive compiled known keys dictionaries
Slimed down usb communications with NG-frames
The most compiled public known key recovery software
The fastest implementations of said software
Support multiple fileformats for dump files (BIN/EML/JSON)
Interoperability of said fileformats with libnfc, MFC tool app etc
Supports more RFID based protocols than ever
Easy install for package maintainers, distro maintainers
Supports cmake, make
Builds without errors or warnings on more OS/platforms than ever
Available as package on known distros like Gentoo, Kali, Termux, Macports, Homebrew
Much more documentation

Development

⚠ Note: This is a bleeding edge repository. The maintainers actively is working out of this repository and will be periodically re-structuring the code to make it easier to comprehend, navigate, build, test, and contribute to, so DO expect significant changes to code layout on a regular basis.

👉 Remember! If you intend to contribute to the code, please read the coding style notes first. We usually merge your contributions fast since we do like the idea of getting a functionality in the Proxmark3 and weed out the bugs afterwards.

The public roadmap is an excellent start to read if you are interesting in contributing.

Supported operating systems

This repo compiles nicely on

WSL1 on Windows 10
WSL2 on Windows 10/11
Proxspace environment release v3.xx
Windows/MinGW environment
Ubuntu, ParrotOS, Gentoo, Pentoo, Kali, NetHunter, Arch Linux, Fedora, Debian, Raspbian
Android / Termux
macOS / Homebrew (or MacPorts, experimental) / Apple Silicon M1
iOS (Jailbroken, rootful)
Docker container
- Iceman repo based ubuntu 18.04 container
- Iceman fork based container v1.7

Precompiled binaries

See Proxmark3 precompiled builds

Proxmark3 GUI

The official PM3-GUI from Gaucho will not work. Not to mention is quite old and not maintained any longer.

Proxmark3 Universal GUI will work more or less.
Proxmark3 GUI cross-compiled which is recently updated and claims to support latest source of this repo.
Proxmark3_GUI simple gui in vb.net

Official channels

Where do you find the community?

Maintainers

To all distro, package maintainers, we tried to make your life easier.

make install is now available and if you want to know more.

This document will be helpful for you

Notes for maintainers

Citation

Use this bibtex to cite this repository globally:

@misc{proxmark3,
  author = {C. {Herrmann} and P. {Teuwen} and O. {Moiseenko} and M. {Walker} and others},
  title = {{Proxmark3 -- Iceman repo}},
  howpublished = {\url{https://github.com/RfidResearchGroup/proxmark3}},
  keywords = {rfid nfc iceman proxmark3 125khz 134khz 13.56mhz},
}

If you need to refer to a specific state of the repository, use a commit number or a date of access, e.g.:

  note = {Accessed: commit 12327f71a27da23831901847886aaf20e8ad3ca0}
  note = {Accessed: 2021-01-01}

Copyright and licensing terms

Each contribution is under the copyright of its author. See AUTHORS.

The Proxmark3 source code is covered by the following licensing terms, usually referred as GPLv3 or later.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

A copy of the GPLv3 is available in LICENSE.

Some dependencies may be under other free licensing terms compatible with the Proxmark3 licensing terms, see their respective description.

henrypp/memreduct

Lightweight real-time memory management application to monitor and clean system memory on your computer.

Mem Reduct

Description:

Lightweight real-time memory management application to monitor and clean system memory on your computer.

The program used undocumented internal system features (Native API) to clear system cache (system working set, working set, standby page lists, modified page lists) with variable result ~10-50%. Application it is compatible with ~~Windows XP SP3~~ Windows 7 SP1 and higher operating systems.

You can download either the installer or portable version. For correct working you are require administrator rights.

To activate portable mode, create "memreduct.ini" in application folder, or move it from "%APPDATA%\Henry++\Mem Reduct".

System requirements:

Windows 7, 8, 8.1, 10, 11 (64-bit/ARM64)
An SSE2-capable CPU
~~KB2533623~~ KB3063858 update for Windows 7 was required

Donate:

Bitcoin (BTC)
Ethereum (ETH)
Yandex Money (RUB)
Paypal (USD)

GPG Signature:

Binaries have GPG signature memreduct.exe.sig in application folder.

Public key: pubkey.asc (pgpkeys.eu)
Key ID: 0x5635B5FD
Fingerprint: D985 2361 1524 AB29 BE73 30AC 2881 20A7 5635 B5FD

Website: github.com/henrypp
Support: sforce5@mail.ru

Cisco-Talos/clamav

ClamAV - Documentation is here: https://docs.clamav.net

ClamAV

ClamAV® is an open source antivirus engine for detecting trojans, viruses, malware & other malicious threats.

Documentation & FAQ

ClamAV documentation is hosted at docs.clamav.net. The source archive for each release also includes a copy of the documentation for offline reading.

You can contribute to the documentation by submitting improvements to Cisco-Talos/clamav-documentation

ClamAV News

For information about the features in this and prior releases, read the news.

Catch up on the latest about ClamAV by reading our blog and follow us on Twitter @clamav.

ClamAV Signatures

Anyone can learn to read and write ClamAV signatures. To get started, see our signature writing manual.

Installation Instructions

Using Docker

ClamAV can be run using Docker. For details, visit to the online manual under "Docker" and check out our images on Docker Hub.

Using a Package Manager

For help installing from a package manager, refer to the online manual under "Packages".

Using an Installer

The following install packages are available for download from clamav.net/downloads:

Linux - Debian and RPM packages for x86_64 and i686. New in v0.104.
macOS - PKG installer for x86_64 and arm64 (universal). New in v0.104.
Windows - MSI installers and portable ZIP packages for win32 and x64.

To learn how to use these packages, refer to the online manual under "Installing".

Build from Source

For step-by-step instructions, refer to the online manual:

The source archive for each release includes a copy of the documentation for offline reading.

A reference with all of the available build options can be found in the INSTALL.md file.

You can find additional advice for developers in the online manual under "For Developers".

Upgrading from a previous version

Visit the FAQ for tips on how to upgrade from a previous version.

Join the ClamAV Community

The best way to get in touch with the ClamAV community is to join our mailing lists.

You can also join the community on our ClamAV Discord chat server.

Want to make a contribution?

The ClamAV development team welcomes code contributions, improvements to our documentation, and also bug reports.

Thanks for joining us!

Licensing

ClamAV is licensed for public/open source use under the GNU General Public License, Version 2 (GPLv2).

See COPYING.txt for a copy of the license.

3rd Party Code

ClamAV contains a number of components that include code copied in part or in whole from 3rd party projects and whose code is not owned by Cisco and which are licensed differently than ClamAV. These include:

Yara: Apache 2.0 license
- Yara has since switched to the BSD 3-Clause License; Our source is out-of-date and needs to be updated.
7z / lzma: public domain
libclamav's NSIS/NulSoft parser includes:
- zlib: permissive free software license
- bzip2 / libbzip2: BSD-like license
OpenBSD's libc/regex: BSD license
file: BSD license
str.c: Contains BSD licensed modified-implementations of strtol(), stroul() functions, Copyright (c) 1990 The Regents of the University of California.
pngcheck (png.c): MIT/X11-style license
getopt.c: MIT license
Curl: license inspired by MIT/X, but not identical
libmspack: LGPL license
UnRAR (libclamunrar): a non-free/restricted open source license
- Note: The UnRAR license is incompatible with GPLv2 because it contains a clause that prohibits reverse engineering a RAR compression algorithm from the UnRAR decompression code. For this reason, libclamunrar/libclamunrar_iface is not linked at all with libclamav. It is instead loaded at run-time. If it fails to load, ClamAV will continue running without RAR support.

See the COPYING directory for a copy of the 3rd party project licenses.

Acknowledgements

Credit for contributions to each release can be found in the News.

ClamAV is brought to you by the ClamAV Team