#QuickUIDesign Template Overview

#What is QuickUIDesign Template?

QuickUIDesign is a React-based UI development template designed specifically for Unreal Engine 5 (UE5). It provides a complete toolchain for creating interactive UE5 interfaces using modern frontend technologies, enabling developers to build high-performance game UI with React.

#Version History

• v1.0.0 nitial release with core template structure, UE5 connection demo, asset toolchain, and Rspack build configuration.
• v1.1.0 Added media asset packaging support, enabling images, audio, video, and other media assets to be bundled into HTML files.

#Template Structure

The template source code is located in the src/ directory with the following structure:

src/
├── assets/                    # Static resource files
│   └── img/
│       ├── QuickUI-A.svg      # QuickUI logo SVG
│       ├── QuickUI-A-base64.txt
│       ├── lufei.png           # Sample image
│       └── lufei-base64.txt
├── components/                # React components
│   └── UEConnect-Demo/
│       └── index.tsx          # UE5 connection demo component
├── lib/
│   └── utils.ts               # Utility functions (cn helper)
├── pages/
│   └── template/
│       ├── index.tsx           # Application entry point
│       └── App.tsx             # Root component
├── styles/
│   └── index.css               # Tailwind CSS directives
└── types/
│   └── @type.d.ts              # TypeScript type declarations
│
└──public/
    ├── audios/
    │   └── light-on.mp3           # Sample audio resource (non-inline reference)
    └── img/
    │   └── lufei.png              # Sample image resource (non-inline reference)
    └── index.html                 # HTML template

#Key Files

#Entry Point: src/pages/template/index.tsx

The application entry point that mounts the root component:

import App from './App'
import { createRoot } from 'react-dom/client'

const container = document.getElementById('root')
const root = createRoot(container)
root.render(
  <>
    <App />
  </>
)

#Root Component: src/pages/template/App.tsx

The main application component that sets up the UE5 connection context and configures the auto-fit layout:

import { useEffect } from 'react'
import { useQuickUIEventListener } from 'ue-connect'
import autofit from 'autofit.js'
import '@/styles/index.css'
import { UEProvider } from 'ue-connect'
import UEConnectDemo from '@/components/UEConnect-Demo'

export default function App({ Fit = false }: { Fit?: boolean }) {
  useQuickUIEventListener('UEcallback', (event) => {})

  useEffect(() => {
    if (Fit)
      autofit.init({
        dw: 1920,
        dh: 1080,
        el: 'body',
        resize: true,
        transition: 0.25,
        limit: 0.3
      })
  }, [])

  return (
    <UEProvider>
      <div className="flex flex-col items-center justify-center w-screen h-screen select-none overflow-hidden">
        <UEConnectDemo />
      </div>
    </UEProvider>
  )
}

Key features:

• UEProvider: Provides the global UE5 connection context to all child components
• useQuickUIEventListener: Must be called once in the root component to enable event listening in child components
• autofit.js (optional): Enables responsive scaling to maintain consistent layout across different resolutions. Pass Fit={true} to activate.

#Demo Component: src/components/UEConnect-Demo/index.tsx

A complete reference component demonstrating the core ue-connect APIs:

• useInputBlocker: Disables right-click context menu and Tab key
• useUEContext: Retrieves UE5 connection status, device type, mouse state, and last key action
• useQuickUIEventSender: Sends custom events to UE5
• useQuickUIEventListener: Listens for events from UE5
• data-nohit attribute: Marks elements as non-penetrable for mouse events, allowing proper event routing between Web UI and UE5

#Styles: src/styles/index.css

Tailwind CSS entry point with the three core directives:

@tailwind base;
@tailwind components;
@tailwind utilities;

#Utilities: src/lib/utils.ts

The cn() helper function combines clsx and tailwind-merge for conditional class name merging:

import { clsx, type ClassValue } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

#Type Declarations: src/types/@type.d.ts

Module declarations for static asset imports used in the project:

declare module '*.svg'
declare module '*.png'
declare module '*.jpg'
declare module '*.jpeg'
declare module '*.gif'
declare module '*.bmp'
declare module '*.tiff'
declare module '*.scss'
declare module '*.json'
declare module '*.txt' {
  const content: string
  export default content
}

#ue-connect Module

ue-connect is the core UE5 connector module located in the ue-connect/ directory. It provides a complete set of hooks and context management tools for establishing bidirectional communication between React and UE5.

For detailed documentation, please visit the ue-connect documentation

#assets-tool Utilities

The assets-tool/ directory contains two build helper utilities for optimizing the final output for UE5 integration.

#Tool Structure

assets-tool/
├── convertImageToBase64.js   # Image to Base64 converter
└── merge-html.js             # HTML inlining/merging tool

#convertImageToBase64

Converts image (PNG/JPG) files to Base64-encoded text files, making it easy to embed assets directly in UE5.

See the usage example in src/pages/template/App.tsx for reference

⚠️ Note: QuickUI supports two image resource loading methods: inline and non-inline. It is recommended to use Base64 encoding to inline small image resources into HTML files.

For non-inline resources, additional image assets need to be packaged when building for UE5. For details, please refer to Load the Built HTML
Usage:

# Convert a single file
node assets-tool/convertImageToBase64.js ./src/assets/img/lufei.png

# Batch convert all images in a directory
node assets-tool/convertImageToBase64.js ./src/assets/img/

Corresponding npm script:

"base64img": "node assets-tool/convertImageToBase64.js ./src/assets/img/"

How it works:

• Reads the binary data of the image/WASM file
• Converts to a Base64 string with a data:image/png;base64, or data:application/wasm;base64, prefix
• Generates a filename-base64.txt file in the same directory
• Supported formats: .png, .jpg, .jpeg,

#merge-html

An HTML inlining tool that inlines all external JS, CSS, images, and font files referenced in the build output into a single self-contained HTML file, suitable for loading in UE5's web browser widget.

Usage:

node assets-tool/merge-html.js

Corresponding npm script:

"merge-html": "node assets-tool/merge-html.js"

Supported merge types:

Use case:

• After rspack build, the generated HTML with external resources is processed by this tool
• Produces a single self-contained HTML file ready for loading in UE5 with no external dependencies

#Build Configuration

#rspack.config.js

The project uses Rspack (a high-performance Rust-based web build tool) as its core bundler. The configuration file is located at the project root.

Entry Configuration:

entry: {
  index: './src/pages/template/index.tsx',
}

src/pages/template/index.tsx is the single entry point for the template application. All components and dependencies are bundled starting from this file.

Module Resolution & Aliases:

resolve: {
  extensions: ['.js', '.jsx', '.ts', '.tsx'],
  alias: {
    '@': path.resolve(__dirname, './src'),
    'ue-connect': path.resolve(__dirname, './ue-connect')
  }
}

• @ alias simplifies source imports, e.g. import App from '@/pages/template/App'
• ue-connect alias ensures the module reference points to the local ue-connect/ directory

Dev Server:

devServer: {
  open: true,
  static: { directory: path.join(__dirname, 'dist') },
  hot: true,
  historyApiFallback: true,
  port: 3000
}

#Using the Template

#Development

Start the development server:

npm run dev

This launches a local dev server with hot module replacement for rapid development.

#Building

Build the project for production:

npm run build
npm run merge-html

The build output will be generated in the dist/merged/ directory as a single HTML file with all assets inlined, ready for use in UE5.

#UE5 Integration

After building, the generated HTML file can be loaded in UE5 using the QuickUI plugin's web browser widget, enabling seamless bidirectional communication between React and UE5.