Building Cesium-Unreal for VisionOS

I’m currently building Cesium-Unreal to target VisionOS. I have the 2.11.0 release commit cloned and building for iOS.

In updating the CMake toolchain files to support visionOS (adapting the iOS toolchain files) I get errors in triplets with ezckpgg:

~/Library/Application Support/JetBrains/CLion2024.3/scratches
/bin/bash /Users/myUserName/Library/Application\ Support/JetBrains/CLion2024.3/scratches/scratch_1.sh
DriverKit SDKs:
        DriverKit 24.1                  -sdk driverkit24.1

iOS SDKs:
        iOS 18.1                        -sdk iphoneos18.1

iOS Simulator SDKs:
        Simulator - iOS 18.1            -sdk iphonesimulator18.1

macOS SDKs:
        macOS 15.1                      -sdk macosx15.1
        macOS 15.1                      -sdk macosx15.1

tvOS SDKs:
        tvOS 18.1                       -sdk appletvos18.1

tvOS Simulator SDKs:
        Simulator - tvOS 18.1           -sdk appletvsimulator18.1

visionOS SDKs:
        visionOS 2.1                    -sdk xros2.1

visionOS Simulator SDKs:
        Simulator - visionOS 2.1        -sdk xrsimulator2.1

watchOS SDKs:
        watchOS 11.1                    -sdk watchos11.1

watchOS Simulator SDKs:
        Simulator - watchOS 11.1        -sdk watchsimulator11.1

----------------------------------------------
CESIUM_UNREAL_VERSION=v2.11.0
UPLOAD_PACKAGE_BASE_NAME=cesium-unreal
BUILD_CESIUM_UNREAL_PACKAGE_NAME=cesium-unreal-v2.11.0
BUILD_ROOT=/Users/myUserName/dev/cesium-unreal-samples/Plugins/cesium-unreal
----------------------------------------------
Installing nasm...
----------------------------------------------
UNREAL_ENGINE_ROOT=/Users/myUserName/.jenkins/workspace/UnrealEngineSourceBuild
CESIUM_VCPKG_RELEASE_ONLY=TRUE
----------------------------------------------
----------------------------------------------
Building cesium-native for VisionOS...
----------------------------------------------
Creating VisionOS project - Using iOS target
refer to temporary solution - https://github.com/CesiumGS/cesium-unity/pull/502
-- Currently using iOS toolchain settings in visionOS toolchain
-- TODO - Resulting XCode project will need to be retargeted from iOS to VisionOS
-- Using Unreal Engine installation at: /Users/myUserName/.jenkins/workspace/UnrealEngineSourceBuild
-- Debug - Detecting VCPKG
 - CMAKE_SYSTEM_PROCESSOR: arm64
 - CMAKE_OSX_ARCHITECTURES: arm64
 - CMAKE_SYSTEM_NAME: visionOS
-- DETECT-VCPKG-TRIPLET.Cmake: Using iOS for Vision OS builds
-- Debug - Detected VCPKG_TRIPLET set to arm64-visionos
-- Debug - Using DETECTED_VCPKG_TRIPLET
-- Debug - Detecting VCPKG
 - CMAKE_SYSTEM_PROCESSOR: arm64
 - CMAKE_OSX_ARCHITECTURES: arm64
 - CMAKE_SYSTEM_NAME: visionOS
-- DETECT-VCPKG-TRIPLET.Cmake: Using iOS for Vision OS builds
-- Debug - Detected VCPKG_TRIPLET set to arm64-visionos
-- VCPKG_TRIPLET arm64-visionos-unreal
-- VCPKG_OVERLAY_PORTS /Users/myUserName/dev/cesium-unreal-samples/Plugins/cesium-unreal/extern/vcpkg-overlays
-- VCPKG_OVERLAY_TRIPLETS /Users/myUserName/dev/cesium-unreal-samples/Plugins/cesium-unreal/extern/vcpkg-overlays/triplets
-- EZVCPKG v0.1 starting up
        Website: https://github.com/jherico/ezvcpkg
-- EZVCPKG_BASEDIR envrionment variable not found and basedir not set, using default /Users/myUserName/.ezvcpkg
-- EZVCPKG initializing
        commit:     2024.11.16
        repository: https://github.com/microsoft/vcpkg.git
        local dir:  /Users/myUserName/.ezvcpkg/2024.11.16
-- EZVCPKG Building/Verifying package asyncplusplus using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package expected-lite using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package fmt using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package glm using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package rapidjson using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package spdlog using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package stb using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package uriparser using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package abseil using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package draco using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package ktx using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package modp-base64 using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package meshoptimizer using triplet arm64-visionos-unreal
-- EZVCPKG Building/Verifying package openssl using triplet arm64-visionos-unreal
CMake Error at cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:83 (message):
  EZVCPKG failed with error 1
Call Stack (most recent call first):
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:184 (EZVCPKG_CHECK_RESULTS)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:276 (EZVCPKG_BUILD)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:290 (EZVCPKG_FETCH_IMPL)
  cesium-native/CMakeLists.txt:67 (ezvcpkg_fetch)


*** The output from the command was:
Computing installation plan...
The following packages will be built and installed:
    openssl:arm64-visionos-unreal@0.0.0 -- /Users/myUserName/dev/cesium-unreal-samples/Plugins/cesium-unreal/extern/vcpkg-overlays/openssl
Unable to determine toolchain use for arm64-visionos-unreal with with CMAKE_SYSTEM_NAME visionos. Did you mean to use VCPKG_CHAINLOAD_TOOLCHAIN_FILE?
note: updating vcpkg by rerunning bootstrap-vcpkg may resolve this failure.

CMake Error at cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:102 (message):
Call Stack (most recent call first):
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:184 (EZVCPKG_CHECK_RESULTS)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:276 (EZVCPKG_BUILD)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:290 (EZVCPKG_FETCH_IMPL)
  cesium-native/CMakeLists.txt:67 (ezvcpkg_fetch)

It looks like a very similar issue has been also encountered with Unity by @ChrisHandzlik, with the workaround being to use an iOS toolchain to build the project data with CMake then retarget the resulting Xcode project to VisionOS.

I’m curious if there are any other solutions or is this to date the best way to do this for Unreal engine given it’s CMake rather than Unity directly handling the Cesium-Native compilation.

Hi @dagillespie,

I’m afraid we can’t really advise – we don’t have a Vision Pro to test building on. But if you could share how you updated the files, maybe something obvious will jump out at us?

Hi @janine - no worries at all. I appreciate the question was rather vaguely formulated.

  • This example uses the VRTemplate project which has been converted to a C++ Unreal project configured for VisionOS and has successfully built and run on a VisionPro.

  • After confirming this has worked, I have then cloned the cerium-unreal repo into the project plugins then proceeded to get cesium-native to compile.

Steps for getting unreal-native to compile (the approach @ChrisHandzlik took for Unity through using iOS binaries - please forgive any errors here - CMake is a new beast to me!):

Using the travis CI commands as a basis, I’ve used the following commands to build VisionOS binaries (full version attached):

mkdir -p extern/build-visionos
cd extern
cmake -B build-visionos -S . -GXcode -DCMAKE_TOOLCHAIN_FILE="unreal-visionos-toolchain.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build-visionOS -j4 --target install --config Release

the toolchain file is:

set(GENERATOR Xcode)
set(CMAKE_SYSTEM_NAME visionOS)
set(CMAKE_OSX_ARCHITECTURES arm64)
set(CMAKE_SYSTEM_PROCESSOR arm64)
set(CMAKE_OSX_DEPLOYMENT_TARGET 2.1)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY BOTH)
SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE BOTH)
SET(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE BOTH)

then updating detect-vcpkg-triplet.cmake:

elseif (CMAKE_SYSTEM_NAME STREQUAL "visionOS")
    message(STATUS "DETECT-VCPKG-TRIPLET.Cmake: Using iOS for Vision OS builds")
    message(STATUS "refer to similar temporary solution - https://github.com/CesiumGS/cesium-unity/pull/502")
    set(DETECTED_VCPKG_TRIPLET "arm64-ios")

Having run the .sh I was able to build the project and open the editor. Packaging to VisionOS however resulted in the following:

UATHelper: Packaging (VisionOS): RunUAT ERROR: AutomationTool was unable to run successfully. Exited with code: 139
PackagingResults: Error: AutomationTool was unable to run successfully. Exited with code: 139
PackagingResults: Error: Unknown Error

I’ve also attached the full log
BuildCommandAndLog.zip (8.0 KB)

I’m also testing my base assumptions first of all with my dev environment by testing first of all that if I use the latest Unreal 5.5 GitHub zipped release 2.11.0 and first of all package to iOS with CesiumForUnreal that this is successful.

In this instance, I am doing the following:

  • Unreal 5.5.1 from Epic Launcher on M3 MacBook Air
  • Creating a VRTemplate project
  • Testing that this builds fine to iOS (it does and took less than 5 mins)
  • Adding CesiumForUnreal 2.11.0 release from github
  • Regenerate project files and compile through Xcode
  • Ensure CesiumForUnreal is enabled
  • Build to iOS

Currently the build to iOS with CesiumForUnreal enabled appears to be hanging compiling vecmath.cpp (1hr + and counting). I’ll be patient and leave this overnight however I wouldn’t have thought that this library would have caused such a long compilation time or be hanging?

UATHelper: Packaging (IOS): [182/188] Compile [arm64] VecMath.cpp

Assuming this packages, I’ll then extend the task to VisionOS as it might be possible to drop the pre-compiled cesium-native pre-compiled binaries into the 2.11.0 release and add a link to these in the relevant build.cs files by adding something along the lines of…

else if(Target.Platform == UnrealTargetPlatform.VisionOS)
{
    platform = "VisionOS-ARM64-";
    libSearchPattern = "lib*.a";
}

Confirming that after 12hrs - iOS build was still stuck compiling VecMath.cpp

Hi @dagillespie,

Thank you for all the details you shared. That’s a weird file for the process to get stuck on. I can’t imagine why it’d get stuck, but our team definitely needs to take a look, since iOS is supposed to be a supported platform.

I’ve opened a Github issue for this so we can formally track the problem. I’ll be sure to leave updates when we get a chance to more deeply investigate. Thank you :pray:

1 Like

Hi @janine - many thanks for having a look into this - hopefully it’s a straightforward fix as first iOS, then I’ll be shifting the problem to VisionOS!

@janine - FYI - I’ve now managed to package the plugin for VisionOS (using iOS binaries) however not surprisingly, I’m still getting that hang compiling VectorMath.cpp

1 Like

@janine - digging deeper into the VectorMath.cpp hang, I ran the response file through clang manually…

clang @Plugins/CesiumForUnreal/Intermediate/Build/IOS/arm64/UnrealGame/Development/CesiumRuntime/VecMath.cpp.o.rsp

which resulted in the following error:

In file included from /Users/dagillespie/dev/cesium-ue-devProj/Plugins/CesiumForUnreal/Source/CesiumRuntime/Private/VecMath.cpp:3:
**/Users/dagillespie/dev/cesium-ue-devProj/Plugins/CesiumForUnreal/Source/CesiumRuntime/Private/VecMath.h:5:10:** **fatal error:** **'Math/Matrix.h' file not found**

I’m packaging on the following:

  • macOS Sequoia 15.2
  • Xcode 16.2
  • Unreal 5.5.1
  • Unreal C++ project
  • CesiumForUnreal 2.12.0 (zip release file from GitHub)
  • iOS as target

Packaging from a blueprint project is a success - most likely because cesium-unreal is not being recompiled

Thank you for the updates @dagillespie, and sorry for the lack of response on our end.

That’s a really strange error, since the Math/Matrix.h file definitely exists in Unreal Engine files. :thinking:

Are you willing to try and edit the plugin from source? If so, I wonder what happens if you replace Math/Matrix.h with CesiumCommon.h. The FMatrix definition should be provided through the includes within CesiumCommon.h itself, and hopefully the compiler won’t complain.

I apologize for the delay in testing this oureslves. We’re in the process of setting up our environment for testing on Mac and iOS (Apple developer account and all), and I personally don’t have access to these resources. But I hope what I wrote above turns out to be a working solution :pray:

Hi @janine - thanks for the guidance - it’s looking like it’s going down a dependency rabbit hole as I am now missing the following:

% clang @/.../Plugins/cesium-unreal/Intermediate/Build/IOS/arm64/UnrealGame/Development/CesiumRuntime/VecMath.cpp.o.rsp 
In file included from /.../cesium-ue-devProj/Plugins/cesium-unreal/Source/CesiumRuntime/Private/VecMath.cpp:3:
In file included from /.../cesium-ue-devProj/Plugins/cesium-unreal/Source/CesiumRuntime/Private/VecMath.h:6:
/.../Plugins/cesium-unreal/Source/CesiumRuntime/Public/CesiumCommon.h:5:10: fatal error: 'Runtime/Launch/Resources/Version.h' file not found

I assume that whatever is causing the error originally with VecMath.h means that adding in CesiumCommon.h fixed the first part of the problem but subsequent dependencies from this are not addressed?

Excited you’re getting set up a Mac dev environment - if you by any chance also have a Vision Pro - the ultra wide screen mirroring is really good as a coding environment!

1 Like

Hi @dagillespie,
Just to check an easy thing, do you have the “Engine Source” for your UE version installed?

Hi @Kevin_Ring - yes, Engine source is there and I have verified that Matrix.h is present on my machine in:
‘/Users/Shared/Epic Games/UE_5.5/Engine/Source/Runtime/Core/Public/Math/Matrix.h’

The only difference is that I don’t have “editor symbols for debugging” like your screenshot however I wouldn’t have thought that would make a difference.

Hi @dagillespie,

I don’t have any ready-made solutions for any of this, but I may be able to help you make some progress, at least.

First, that Exited with code: 139 error. I also saw that on my corporate-managed MBP when packaging for iOS. I spent awhile trying to debug it, and I still don’t know exactly why it happens. UnrealBuildTool seems to simply be crashing for no clear reason. But I was able to work around it by disabling the Unreal Build Accelerator.

Create ~/Library/Application Support/Unreal Engine/UnrealBuildTool/BuildConfiguration.xml and copy this into it:

<?xml version="1.0" encoding="utf-8" ?>
<Configuration xmlns="https://www.unrealengine.com/BuildConfiguration">
	<BuildConfiguration>
		<bAllowUBAExecutor>false</bAllowUBAExecutor>
		<bAllowUBALocalExecutor>false</bAllowUBALocalExecutor>
	</BuildConfiguration>
</Configuration>

I don’t think this will do any harm to build performance if you’re not actually parallelizing builds across multiple machines.

As far as the hang in VecMath.cpp, I’m not quite sure what might cause that. But one thing worth mentioning is that Clang needs a lot of memory to compile Cesium for Unreal. It seems to struggle with the large std::variant used in the metadata system. So if your MacBook does not have a lot of memory, you’ll need to reduce the number of source files it compiles in parallel. You can do that by adding the following to that same BuildConfiguration.xml mentioned above, inside the <BuildConfiguration> element:

<MaxParallelActions>2</MaxParallelActions>

Hopefully some of that will help you make some progress! Let me know how it goes.

1 Like

Perfect - both disabling UBA and limiting MaxParallelActions did the trick. I’m now able to package a C++ project using cesium-unreal directly from Github.

Will feed back with anything that comes up building for AVP

1 Like

Feeding back on VisionOS build process now that iOS is packaging fine, it looks like I may be hitting issues building cesium-native for VisionOS SDK. It could be that I’m overlooking something relatively straightforward in the changes required for CMake to run this (CMake 3.31.5).

I’m adding the following cmake files to target VisionOS given that CMake 3.28+ supports it as a target platform CMake 3.28 Release Notes — CMake 4.0.0-rc2 Documentation

  • extern/unreal-visionos-toolchain.cmake - to target arm64, visionOS, 2.1SDK
set(CMAKE_GENERATOR Xcode)
set(CMAKE_SYSTEM_NAME visionOS)
set(CMAKE_OSX_ARCHITECTURES arm64)
set(CMAKE_SYSTEM_PROCESSOR arm64)
set(CMAKE_OSX_DEPLOYMENT_TARGET 2.1)
set(CMAKE_POSITION_INDEPENDENT_CODE ON)
SET(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY BOTH)
SET(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE BOTH)
SET(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE BOTH)

  • extern/vcpkg-overlays/triplets/arm64-visionos-unreal.cmake - to work with above
include("${CMAKE_CURRENT_LIST_DIR}/shared/common.cmake")

#simply adapted from iOS triplet file
set(VCPKG_TARGET_ARCHITECTURE arm64)
set(VCPKG_CRT_LINKAGE dynamic)
set(VCPKG_LIBRARY_LINKAGE static)
set(VCPKG_CMAKE_SYSTEM_NAME visionOS)
set(VCPKG_OSX_DEPLOYMENT_TARGET 2.1)

# From Unreal Build Tool:
# https://github.com/EpicGames/UnrealEngine/blob/5.3.2-release/Engine/Source/Programs/UnrealBuildTool/Platform/IOS/IOSToolChain.cs
set(VCPKG_CXX_FLAGS "-fvisibility=hidden")
set(VCPKG_C_FLAGS "${VCPKG_CXX_FLAGS}")

and modifying extern/cesium-native/cmake/detect-vcpkg-triplet.cmake with the following to use the correct triplet:

elseif (CMAKE_SYSTEM_NAME STREQUAL "visionOS")
    message(STATUS "DETECT-VCPKG-TRIPLET.Cmake: Using visionOS for Vision OS builds")
    set(DETECTED_VCPKG_TRIPLET "arm64-visionos")

This error is coming up when building Cesium-Native targetting VisionOS:

-- EZVCPKG Building/Verifying package asyncplusplus using triplet arm64-visionos-unreal
CMake Error at cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:83 (message):
  EZVCPKG failed with error 1
Call Stack (most recent call first):
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:194 (EZVCPKG_CHECK_RESULTS)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:286 (EZVCPKG_BUILD)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:300 (EZVCPKG_FETCH_IMPL)
  cesium-native/CMakeLists.txt:68 (ezvcpkg_fetch)


*** The output from the command was:
Computing installation plan...
The following packages will be built and installed:
    asyncplusplus:arm64-visionos-unreal@1.1#2 -- /Users/davidgillespie/cesium-ue-devProj/Plugins/cesium-unreal/extern/vcpkg-overlays/asyncplusplus
Unable to determine toolchain use for arm64-visionos-unreal with with CMAKE_SYSTEM_NAME visionOS. Did you mean to use VCPKG_CHAINLOAD_TOOLCHAIN_FILE?
note: updating vcpkg by rerunning bootstrap-vcpkg may resolve this failure.

CMake Error at cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:102 (message):
Call Stack (most recent call first):
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:194 (EZVCPKG_CHECK_RESULTS)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:286 (EZVCPKG_BUILD)
  cesium-native/cmake/ezvcpkg/ezvcpkg.cmake:300 (EZVCPKG_FETCH_IMPL)
  cesium-native/CMakeLists.txt:68 (ezvcpkg_fetch)


-- Configuring incomplete, errors occurred!

Any pointers here would be most appreciated!

Hi @dagillespie,

I think the problem is that vcpkg doesn’t support visionOS at all. So when you specify the CMAKE_SYSTEM_NAME as visionOS, this makes vcpkg throw up its hands and say it has no idea how to build for that platform.

Most likely, you can work around this by writing a custom toolchain file for visionOS and specifying it in the vcpkg triplet file:

As for what, exactly, needs to be in the toolchain file… I’m not sure. It’s possible that the one you’ve already written - unreal-visionos-toolchain.cmake - will be sufficient.

It’s also possible that it will be sufficient to simply build cesium-native for iOS instead of customizing the build for visionOS, and then link against those iOS binaries in the Unreal visionOS build. I’m far from certain that will work, but I think there’s at least a chance that it will!

Thanks for the clarity there with it being likely to be a VCPKG issue rather than CMake.

I’m able to confirm that I can build to iOS and open the same app on VisionOS with Cesium - the app runs windowed in 2D but that’s at least a start and validation that the metal rendering pipeline behaves reasonably.

Targetting VisionOS itself using iOS Cesium-Native binaries, appears to bring up the following issue from unreal when packaging:

ld: building for 'visionOS', but linking in object file (/Users/userName/cesium-ue-devProj/Plugins/cesium-unreal/Source/ThirdParty/lib/visionOS-arm64-Release/libktx.a[2](basis_transcode.cpp.o)) built for 'iOS'
clang++: error: linker command failed with exit code 1 (use -v to see invocation)
Total time in Parallel executor: 366.41 seconds

looks like ktx library which is pulled from vcpkg is the issue here - it’s Khronos texture library - is there any way I could retarget this or build the binaries from source for VisionOS?

FYI - this is happening when:

  • setting vcpkg triplet to iOS in order for it to download the iOS source for Vision Pro
  • setting a custom toolchain file for vcpkg to use unreal-visions-toolchain.cmake which overrides the cmake settings to build the vcpkg dependencies using VisionOS SDK
  • building cesium-native and cesium-unreal
  • packaging for VisionOS

What is odd here is that in the cesium-native build steps, it looks like ktx is being built against Vision Pro SDK so I wouldn’t have expected the library to return built for ‘iOS’ in the unreal build stage?

ld: building for 'visionOS', but linking in object file (/Users/userName/cesium-ue-devProj/Plugins/cesium-unreal/Source/ThirdParty/lib/visionOS-arm64-Release/libktx.a[2](basis_transcode.cpp.o)) built for 'iOS'
clang++: error: linker command failed with exit code 1 (use -v to see invocation)