RmlUi images

WebP support is available since update 0.1.4, BUILD125 (in development). The public release remains 0.1.3. Existing PNG support is retained. WebP adds an image format to the existing GUI APIs; it does not introduce a new Lua function.

Supported images

Format	Behaviour
PNG	Existing PNG loading, including transparency, remains supported.
WebP (since 0.1.4 BUILD125)	Static lossy and lossless images, with or without alpha transparency. Animated WebP is explicitly rejected; it is not played and is not silently reduced to a first frame.
TGA	Uncompressed true-colour 24-bit and 32-bit images. BUILD126 adds stricter header, dimensions and payload checks to this path.

WebP uses the bundled, statically linked libwebp 1.6.0 decoder. No Windows WebP codec or additional runtime codec DLL is required. EXIF orientation and ICC colour profiles are not applied to WebP: export GUI images in their final orientation and sRGB colour space.

Example: PNG and WebP in one document

Declare the document and both images in the resource's scripts.xml:

<file src="ui/images.rml" download="join" />
<file src="ui/example.png" download="join" />
<file src="ui/example.webp" download="join" />

These are entries to add inside the existing resource manifest, not a complete manifest. Supply your own image files.

Contents of ui/images.rml:

<rml>
<head>
    <title>Image formats</title>
    <style>
        body { width: 380px; height: 220px; background-color: #182028; color: white; }
        .sample { display: inline-block; width: 170px; padding: 8px; }
    </style>
</head>
<body>
    <div class="sample">PNG:<br /><img src="example.png" width="128" height="128" /></div>
    <div class="sample">WEBP:<br /><img src="example.webp" width="128" height="128" /></div>
</body>
</rml>

Load it from an existing client script:

local document = guiLoadDocument("ui/images.rml")
if document then
    guiShow(document)
end

Image references above are relative to the RML document's directory. RCSS image decorators use the same texture loader. The existing guiLoadDocument and guiShow APIs have not changed.

Limits and safe asset loading

• Encoded texture file: at most 256 MiB. Decoded width and height: at most 8192 pixels each. These bounds are not a recommendation to use very large GUI textures or a guarantee of available VRAM.
• WebP container size, dimensions and bitstream features are checked before allocating the bounded RGBA output. Malformed, truncated, animated and oversized inputs fail to load.
• Since 0.1.4 BUILD126, resource GUI files must be declared in the verified download catalog and belong to the requesting resource. Cross-resource references, undeclared files, script files and arbitrary OS-file reads are rejected. Size/hash checks and resolved-path checks remain enforced.
• The download extension allowlist does not promise that every allowed extension is decodable by RmlUi. See Scripting limits for the distinction between transport policy and image/audio support.
• Update clients to BUILD125 or newer before relying on WebP; older clients do not gain support from a script change. The WebP codec alone does not require a server change. The separate BUILD126 security policy and shared Lua additions require the relevant updated client/server components.

See also Update 0.1.4, Scripting limits, guiLoadDocument.