How to Build and Use Custom Bezels and Overlays in RetroArch

RetroArch calls the image-and-configuration system an input overlay because it was designed to draw touch controls over content. The same mechanism can display a decorative border or bezel. A shader is a different layer: it processes the game image, while an overlay draws an image above the resulting viewport.

One technical distinction prevents many broken bezels: overlay desc entries define touch-input hitboxes, not the rectangle where game video is placed. The game viewport is controlled by RetroArch’s video scaling/custom viewport settings. Treat artwork placement and video placement as two coordinated configurations.

Step 1: establish a plain, measured baseline

Load the target game with overlays and shaders disabled. Set the intended fullscreen resolution, aspect ratio, crop/overscan behavior, and integer-scaling preference first. Capture a screenshot and record the content resolution and final output dimensions.

Settings → Video → Scaling
Settings → On-Screen Display → On-Screen Overlay

Do not design around accidental television zoom. Put the display in its documented no-overscan or 1:1 mode. A bezel aligned to a cropped host display will be wrong on the captured output and on another panel.

Step 2: use artwork you are allowed to reproduce

Create original art, use Libretro’s maintained overlay repositories, or obtain an asset under a license that permits the intended use. Arcade marquees, cabinet scans, logos, characters, and box art can remain copyrighted. “Available in a pack” is not proof that commercial redistribution is allowed.

Record creator, source URL, license, changes, and retrieval date in a small text file beside the preset. Do not remove attribution required by a license. Keep a layered source master so future resolutions can be generated without resampling a flattened PNG repeatedly.

Step 3: design the PNG around the final output

Create a canvas matching the target output aspect and preferably its exact pixel dimensions. The region where game video should remain visible must be transparent. Decorative pixels belong around that opening; an opaque rectangle will cover the game.

Use a lossless PNG with alpha and an ordinary RGB color profile. Check the alpha channel against both black and bright test backgrounds to find stray opaque pixels, halos, or premultiplied-alpha artifacts. Avoid placing critical art outside television-safe margins if the setup includes displays that cannot disable overscan.

Keep the opening rectangular during the first build. Curved masks and faux glass can be added after geometry is correct; otherwise their visual edge makes measurement ambiguous.

Step 4: write a minimal decorative overlay configuration

Place the PNG and .cfg together in a user-writable overlay directory. Use simple filenames without secrets or machine-specific home paths. A decorative overlay with no touch controls can begin as:

overlays = 1
overlay0_overlay = "mybezel.png"
overlay0_full_screen = true
overlay0_descs = 0

overlay0_full_screen = true makes the overlay cover the full output rather than only the game viewport. That is normally required for a border occupying side areas. The image path is relative to the configuration file.

Do not add fictional overlay0_desc0_x, y, width, or height fields to define the game opening. Libretro’s overlay specification defines descriptors as input events with positions and hitbox ranges. If interactive controls are later added, document and test every hitbox separately.

Settings → On-Screen Display → On-Screen Overlay
         → Overlay Preset

Enable the overlay and select the .cfg. If no image appears, confirm the PNG name, relative location, case, alpha, and active hardware-accelerated video driver. Generate a RetroArch log before copying files into several directories.

Update official decorative borders through Libretro’s supported updater or repository, not an installer from a video description. An overlay needs only data files; it should not require administrator/root access or an executable setup program.

Step 6: align the game with a custom viewport

Measure the transparent opening in output pixels: left edge, top edge, width, and height. Configure RetroArch’s custom aspect ratio and viewport under Settings → Video → Scaling. Names vary slightly by menu driver, but the X/Y position and width/height belong to video scaling, not the overlay file.

Verify circles remain circles and pixel geometry matches the chosen aspect. Do not stretch the game merely to touch all four artwork edges. If the opening has the wrong proportions, correct the artwork or accept letterboxing rather than distorting content.

Integer scaling may leave a small gap because the source cannot fill the opening with whole-number multiples. Decide whether even pixels or edge-to-edge fit has priority and label the choice. A per-game exception is better than globally breaking every system.

Step 7: test multiple content states

Check title screen, gameplay, high-resolution menus, PAL/NTSC variants, rotated arcade games, and any resolution switch. Test screenshots as well as the physical display. A border can align at 224 lines and fail when a game exposes 239 or changes to an interlaced menu.

For vertical arcade titles, make a separate preset rather than rotating a horizontal bezel. For multi-screen machines, use a layout designed for that machine; one generic opening cannot represent every screen arrangement.

Step 8: add optional touch controls correctly

If the overlay also needs buttons, follow the official descriptor syntax:

overlay0_desc0 = "start,0.50,0.90,radial,0.05,0.05"
overlay0_desc0_normalized = true

The values identify an input, center, hitbox shape, and range. Test touch reach, overlap, accessibility, landscape/portrait rotation, and the option that shows physical inputs. Do not place invisible privileged hotkeys such as quit, load state, or disk eject where an ordinary touch can trigger them accidentally.

Step 9: save the right kind of scoped configuration

Overlay enable/path and custom viewport settings can be saved through Quick Menu → Overrides at core, content-directory, or game scope. Use game scope for one cabinet and core scope only for genuinely shared geometry. RetroArch’s override hierarchy applies the most specific configuration last.

Shaders use their own preset saving system, so save a shader as a Core/Game Shader Preset rather than assuming the overlay override owns every shader parameter. Back up the .cfg, PNG, override, shader preset, and source-art manifest together.

Step 10: verify portability and maintenance

Restart RetroArch and launch through the normal playlist path. Test on the target resolution and one different resolution; a pixel-perfect 4K overlay may scale poorly at 1080p. Avoid absolute paths if the pack must move between devices.

Static bright borders can age some display technologies unevenly during long sessions. Follow the display manufacturer’s care features, vary content, and avoid maximum-brightness static artwork. This is a display-management concern, not something a shader can undo.

A reproducible bezel package contains licensed source attribution, layered master, exported PNG dimensions/hash, overlay .cfg, viewport values, RetroArch/core versions, output mode, and scoped override. Alignment is proven when the transparent opening, undistorted game viewport, and physical display agree after restart.

Related:

Sources: