#Quick Start

This guide walks you through the complete workflow of using the QuickUI UE5 Plugin together with the QuickUIDesign template to build interactive UE5 interfaces with React.

#Workflow Overview

UE5 Editor (QuickUI Plugin)
        │
        ├── 1. Install QuickUI Plugin → Enable in UE5 Project
        │
        ├── 2. Extract/Copy QuickUIDesign Project → npm install
        │
        ├── 3. Development: npm run dev → Load http://localhost:3000 in UE5
        │
        ├── 4. Build UI: npm run build → npm run merge-html
        │
        └── 5. Deploy: Load the merged HTML in UE5 Web Browser Widget

#Step 1: Install the QuickUI Plugin in UE5

#Download the Plugin

Download the QuickUI plugin package for your UE5 version from the official marketplace or distribution channel.

#Install to UE5 Project

Download the plugin from the marketplace, which will automatically copy the plugin folder to the Plugins/ directory of your UE5 project.

If you need to install the QuickUI plugin in a different plugin directory, copy the QuickUI plugin folder to the Plugins/ directory of your UE5 project:

YourProject/
├── Plugins/
│   └── QuickUI/          # QuickUI plugin files
├── Content/
├── Source/
└── YourProject.uproject

#Enable the Plugin

1. Open your UE5 project
2. Go to Edit → Plugins
3. Search for "QuickUI"
4. Check the Enabled checkbox
5. Restart the UE5 editor when prompted

#Add QuickUI Widget

In the UMG blueprint, you should be able to see the QuickUI widget. Add it to the UMG and ensure it is mounted using a Canvas component, filling the entire UMG area:

#Blueprint Configuration

A complete QuickUI blueprint configuration workflow is shown below:

In the UMG blueprint, configuring QuickUI mainly involves three steps:

• 1. Load QuickUI File:
  • In development mode, load the development URL address,
  • In production mode, load the production HTML address.

• 2. QuickUI Event Registration and Binding:
  • Custom event registration and binding, Event Name is the event name (needs to match the event name in the React component).
    The image below shows a complete binding workflow (register -> bind -> callback):

The Event1 registered in the image, if it matches Event1 in the React component, then UE5 as the backend will receive the event parameters from the React component.

• Mouse event registration and binding, such as MouseDown, MouseUp, MouseWheel.

Note: MouseDown, MouseUp, and MouseWheel events are independent and need to be registered and bound separately.

• 3. Callback Function Configuration
  • Use the Callback component to configure event callback functions, returning the UE5 processing results to QuickUI.
  • Payload is the parameter passed when the event is triggered, in JSON string format.
  • Fn Name is the function executed when the event is triggered, used to handle event logic, and needs to match the event name in the React component. The image below shows a complete callback function blueprint workflow (event trigger -> callback function execution):

Note: Payload must be passed in JSON string format, otherwise the QuickUI frontend will fail to parse.

#Step 2: Set Up QuickUIDesign

#Install Node.js Runtime

QuickUIDesign is built on the Node.js ecosystem. You need to install Node.js (which includes the npm package manager) first.

#Download & Install

1. Visit the Node.js official website and download the LTS (Long Term Support) version (18+ or higher)
2. Choose the installer matching your operating system (.msi for Windows, .pkg for macOS)
3. Run the installer and follow the default setup

Windows users: Restart your system after installation to ensure Node.js and npm are properly registered in the system PATH environment variable.

#Verify Installation

Open a terminal and run the following commands to confirm the installation:

# Check Node.js version (must be ≥ 18)
node -v

# Check npm version (must be ≥ 9)
npm -v

Expected output (version numbers may vary):

v18.20.4
10.8.1

The version just needs to meet or exceed the minimum requirements above.

#Optional: Configure npm Mirror (for China region)

If you are located in mainland China, consider configuring the Taobao mirror for faster downloads:

# Set the Taobao mirror registry
npm config set registry https://registry.npmmirror.com

# Verify the configuration
npm config get registry

#Update npm (if needed)

If the npm version that came with Node.js is lower than 9, you can update it manually:

npm install -g npm@latest

#Create Project from Archive

#Extract the Source Archive

Extract the QuickUIDesign source archive (.zip or .rar) into your desired working directory:

# After extraction, the project folder should contain src/, ue-connect/, package.json, etc.
D:\Projects\my-ui-project\

You can also extract the archive directly into the current directory and then navigate into the project folder.

#Install Dependencies

Navigate to the project directory and install dependencies:

# Enter the project directory
cd path-to-your-project

# Install dependencies
npm install

#Project Structure

After installation, your project should look like this:

my-ui-project/
├── src/
│   ├── assets/           # Static assets (images, etc.)
│   ├── components/       # React components
│   ├── lib/              # Utility functions
│   ├── pages/            # Page components
│   ├── styles/           # CSS/Tailwind styles
│   └── types/            # TypeScript declarations
├── ue-connect/           # UE5 connector module
├── assets-tool/          # Build helper tools
├── package.json
├── rspack.config.js      # Rspack bundler config
└── tsconfig.json

#Step 3: Development Workflow

#Start the Dev Server

npm run dev

This starts a development server with Hot Module Replacement on http://localhost:3000.

#Load in UE5

1. Open your UE5 project with the QuickUI plugin enabled
2. Create or open a Level Blueprint (or Widget Blueprint)
3. Use the LoadURL node to load http://localhost:3000
4. Run the game (Play)

#Debug with DevTools

While the game is running:

1. Press Ctrl + Shift + I to open the browser DevTools console
2. In the console, type window.ue to verify the UE5 communication object exists
3. Check for connection status and event logs

#Hot Reload

Any changes you make to the source code will be automatically reflected in UE5 without restarting the game — thanks to Rspack's HMR (Hot Module Replacement).

#Step 4: Building for Production

When your UI is ready, build it into an optimized single HTML file:

# Step 1: Build with Rspack
npm run build

# Step 2: Merge all assets into a single HTML file
npm run merge-html

The output will be in dist/merged/index.html — a fully self-contained HTML file with all JS, CSS, and images inlined.

#Build Output Explanation

#Step 5: Deploy in UE5

#Load the Built HTML

1. Use the QuickUI Web browser widget in your UE5 project
2. Point to the build artifact dist/merged/index.html
3. Copy the build artifact to the Content/html/ directory of your UE5 project (this is for illustration; adjust according to your actual project needs)
4. In the UE5 menu bar, add Content/html/ in Edit → ProjectSettings → Packaging → Advanced → Additional Non-Asset Directories to Package

#Complete Communication Architecture

┌─────────────────────┐          ┌──────────────────────┐
│   Web UI (React)    │          │   UE5 (Blueprint)    │
│                     │          │                      │
│  useQuickUIEvent    │ ──────►  │  QuickUIListenEvent   │
│  Sender('event')    │   send   │                      │
│                     │          │                      │
│  useQuickUIEvent    │ ◄────── │  QuickUIEventCallBack │
│  Listener('event')  │  listen  │                      │
│                     │          │                      │
│  useUEContext()     │ ◄────── │  Connection State     │
│  (isConnected...)   │          │                      │
└─────────────────────┘          └──────────────────────┘

#Demo 项目

QuickUIDesign provides a simple Demo project to showcase the basic usage of the QuickUI plugin.

• Google Drive

#Next Steps

• QuickUIDesign — Detailed template structure and customization
• UE-Connect — Complete API reference for UE5 communication hooks
• FAQ — Common issues and solutions