Unreal-OBBSample sample overview

Updated: May 6, 2026

Overview

This sample demonstrates how to split a large Unreal Engine 5 project into multiple OBB files for Meta Quest deployment. It includes a complete automation pipeline covering synthetic content generation, chunk-based asset organization, multi-OBB packaging, and upload to a Meta Horizon release channel.

View the sample source code on GitHub⁠.

Learning objectives

Complete this guide to learn how to:

configure Unreal Engine to generate multiple OBB files instead of packaging all content into a single APK

organize project content into chunks using Primary Asset Labels

automate the build, packaging, and upload workflow for large projects using batch scripts

mark uploaded assets as required or optional for Meta Quest builds

generate large synthetic content for testing OBB functionality

Requirements

Meta Quest device

Unreal Engine 5

For detailed toolchain, SDK, and platform configuration requirements, see the sample README⁠.

Get started

Clone the repository from GitHub. Before building, run setup.bat to generate synthetic test content and import it into the Unreal project chunks. Then run package_project_for_upload.bat to build and package the project. The output appears in {ProjectDir}/Saved/StagedBuilds/Android_ASTC/.

Explore the sample

File / Directory	What it demonstrates	Key concepts
setup.bat	One-time project setup	Keystore generation, synthetic content creation, automated import
package_project_for_upload.bat	Build and package automation	Incremental store version updates, BuildCookRun invocation
upload_package.bat	Upload to Meta Horizon	APK + OBB extraction, required/optional file configuration
scripts/GenBigBmp.ps1	Large file generation	Creating incompressible 16384x16384 24-bit BMP files (~768 MB)
scripts/import_bmps.py	Chunk population	Importing assets to specific Unreal content paths
Content/Chunk100/	Chunk 100 assets	Primary Asset Label-based chunk assignment
Content/Chunk200/	Chunk 200 assets	Secondary chunk with isolated content
Config/DefaultEngine.ini	OBB packaging settings	Force small OBBs, enable patch and overflow OBBs
Config/DefaultGame.ini	Chunk generation settings	Enable chunk generation, IoStore, and pak files

Runtime behavior

When you run the packaged build, the APK loads content from multiple OBB files stored in the device’s OBB directory. The sample exists to demonstrate the build pipeline and packaging configuration. You verify the OBB split by inspecting the output directory, which contains the main APK plus multiple OBB files.

Key concepts

Enabling multiple OBB files

The sample enables multiple OBB generation in Config/DefaultEngine.ini:

bPackageDataInsideApk=False
bForceSmallOBBFiles=True
bAllowPatchOBBFile=True
bAllowOverflowOBBFiles=True

Setting bForceSmallOBBFiles=True forces Unreal to split content into smaller OBB files. bAllowPatchOBBFile=True and bAllowOverflowOBBFiles=True enable additional OBB types for overflow content.

Chunk-based content organization

Content is assigned to chunks using Primary Asset Labels in Content/Chunk100/ and Content/Chunk200/. The scripts/import_bmps.py script imports synthetic BMP files into the correct chunk directories, ensuring each chunk contains approximately 2.3 GB of content. Chunk generation is enabled in Config/DefaultGame.ini with bGenerateChunks=True.

Automated upload with required/optional assets

The scripts/GenUploadConfigJSON.ps1 script generates a JSON configuration that marks files as required or optional:

Get-ChildItem -Path $InputDir -File | ForEach-Object {
    $jsonObj[$_.Name] = [ordered]@{ required = $true }
}

All files default to required, then specific files are marked optional with an empty object. The upload script passes this configuration to ovr-platform-util.exe via the --asset_files_config parameter.

Generating large synthetic content

The scripts/GenBigBmp.ps1 script creates incompressible test files using cryptographically random pixel data. Each BMP is 16384x16384 pixels at 24-bit color depth (~768 MB per file), ensuring OBB files remain large even after compression.