GBMaverick • Unreal Engine 5.7

Startup and Help Guide

GBMaverick is a UE5 plugin for running Game Boy and Game Boy Color content on meshes, screens, and in-world displays. This page covers the first setup path, ROM import workflow, saves, input, UI, and the most common packaging expectations.

Runtime Component

UGBMaverickScreenComponent drives ROM loading, video output, audio, saves, UI, and input.

ROM Asset Type

UGBMaverickROMAsset lets you import .gb and .gbc files as cooked Unreal assets.

Editor Import Support

GBMaverickEditor supplies the asset import path used by the Content Browser.

First Setup

Enable the GBMaverick plugin in your Unreal project and restart the editor if prompted.
Add or select an actor with a visible mesh, usually a plane, quad, screen prop, or monitor mesh.
Add GBMaverickScreenComponent to that actor.
Set the target mesh component and the material index the emulator should write into.
Use a material with a texture parameter named ScreenTexture, or set the component to your own parameter name.

Recommended: Keep the screen material simple while validating the setup. Start with an unlit or lightly shaded material that clearly shows the emulator texture.

Loading Games

Cooked / shippable workflow

Drag a .gb or .gbc file into the Content Browser.
Unreal imports it as a GBMaverickROMAsset.
Assign that asset to the component's ROM asset field.
Package normally. Imported ROM assets are cooked with the build.

Loose file workflow

Set a development ROM file path directly on the component.
Use this for quick iteration inside the editor.
Do not rely on loose file paths for a packaged commercial build unless you intentionally want external user-managed ROM files.

Default UI

The built-in UI can show a lightweight overlay for ROM selection and status. It is intended as a practical startup layer, not as the final presentation UI for your project.

Show Default UI

Enables the built-in overlay widget.

Show Status in Default UI

Displays status text such as ROM scan results, save events, and audio readiness.

Default Widget Class

Lets you replace the stock widget with a project-specific widget while keeping the plugin behavior.

Input

The component supports gamepad-driven play out of the box and exposes input remapping in the details panel.

D-pad directions map to Game Boy movement.
A, B, Start, and Select are individually remappable.
Player polling can be assigned by player index for local multiplayer setups or kiosk-style projects.

Save Data

Battery save files and save state files can both be configured on the component.
If no explicit path is supplied, GBMaverick falls back to project-managed save locations under Saved/GBMaverick.
Auto-load and auto-save options are exposed in the details panel.
Battery saves are the most important default path for cartridge-backed games.

Audio

Enable audio in the component details panel.
Use the volume multiplier to tune the emulator mix against the rest of your scene.
For shipping builds, validate audio together with pause, load, and map transitions.

Packaging Notes

The runtime module is GBMaverick.
The editor-only importer module is GBMaverickEditor.
Imported ROM assets are the right path when you want packaged builds to include playable content.
Plugin distribution should keep the standard plugin structure: Config, Content, Resources, Source, and GBMaverick.uplugin.

Troubleshooting

If the mesh stays blank, verify the target mesh component, material index, and texture parameter name.
If the game runs but input does not, confirm the correct player index and active controller.
If a packaged build cannot find content, switch from loose file paths to imported ROM assets.
If saves do not appear where expected, explicitly set the battery save path and test write permissions.

Included emulator source is first-party GBMaverick code under the plugin source tree and ships as part of the plugin implementation.

Quick Checklist

Plugin enabled • Screen component added • Material bound to ScreenTexture • ROM asset assigned • Save path verified • Audio enabled if needed