repository·main·Indexed 22 days ago
https://github.com/cesiumgs/cesium-unrealA plugin that integrates the 3D geospatial ecosystem into Unreal Engine, providing a high-accuracy WGS84 globe and support for streaming real-world 3D content such as terrain, imagery, and buildings using 3D Tiles and Cesium ion. The plugin supports multiple Unreal Engine versions (from 4.26 to 5.5) and provides development setup guides for Windows, Linux, and macOS.
Compiling Cesium for Unreal requires that the vcpkg-based third-party dependencies, the cesium-native code, and the Cesium for Unreal plugin code itself are all compiled using the same (or compatible) versions of the MSVC compiler.
Key Compatibility Rules:
.lib files or object files being linked.To avoid confusion when passing values, adhere to these unit standards:
When a UObject property is replaced by a different type or logic, use Custom Versions to resolve differences during the loading process. This involves using an enum (defined in CesiumCustomVersion.h) to track the plugin's state.
Serialize: Use this for simple properties like bools or enums. You can intercept the value during the load/save process.PostLoad: Use this for properties that refer to other objects (e.g., pointers). These must be resolved in PostLoad because they may be overwritten later in the load process if handled in Serialize.Versions enum in CesiumCustomVersion.h. Place it between the last custom version and VersionPlusOne.[CoreRedirects] if necessary.Serialize, use Ar.UsingCustomVersion(FCesiumCustomVersion::GUID) and Ar.CustomVer(...) to check the version and set the new property based on the old one.PostLoad, use GetLinkerCustomVersion(FCesiumCustomVersion::GUID) to check the version and resolve pointer-based properties.// Example: Handling a version change in Serialize
void UCesiumWebMapTileServiceRasterOverlay::Serialize(FArchive& Ar) {
Super::Serialize(Ar);
Ar.UsingCustomVersion(FCesiumCustomVersion::GUID);
const int32 CesiumVersion = Ar.CustomVer(FCesiumCustomVersion::GUID);
if (CesiumVersion < FCesiumCustomVersion::WebMapTileServiceProjectionAsEnum) {
this->Projection = this->UseWebMercatorProjection_DEPRECATED
? ECesiumWebMapTileServiceRasterOverlayProjection::WebMercator
: ECesiumWebMapTileServiceRasterOverlayProjection::Geographic;
}
}
// Example: Handling a version change in PostLoad for pointers
void ACesium3DTileset::PostLoad() {
Super::PostLoad();
#if WITH_EDITOR
const int32 CesiumVersion = this->GetLinkerCustomVersion(FCesiumCustomVersion::GUID);
PRAGMA_DISABLE_DEPRECATION_WARNINGS
if (CesiumVersion < FCesiumCustomVersion::CesiumIonServer) {
this->CesiumIonServer = UCesiumIonServer::GetBackwardCompatibleServer(
this->IonAssetEndpointUrl_DEPRECATED);
}
PRAGMA_ENABLE_DEPRECATION_WARNINGS
#endif
}Property tables (from EXT_structural_metadata) define how metadata values apply to features.
name. If no name is provided, the component uses the class name (e.g., a buildings class becomes a buildings property table).normalized status, offset, and scale. These details inform how the component encodes values into textures.When analyzing the Timings panel, look for these two patterns to find optimization opportunities:
These are regions where the application is running but not utilizing available resources (like background threads).
Game Frames in All Tracks, disable Compact Mode, set Depth Limit to 4 lanes, and zoom into periods where background workers are inactive.Depth Limit to Unlimited and zoom into busy background workers.To optimize memory and performance, Cesium for Unreal uses a specialized system for texture creation that handles shared images across different tiles:
ExtensionImageAssetUnreal::getOrCreate is called. It uses a mutex to ensure only one thread performs the actual load. Other threads receive a SharedFuture that resolves once the first thread completes the load, preventing redundant work and blocking.FCesiumPreCreatedRHITextureResource. The GPU upload is triggered immediately by the worker thread via RHIAsyncCreateTexture2D.FCesiumCreateNewTextureResource, which queues a command to the render thread to perform the upload via RHICreateTexture.FTextureResource instances (like FCesiumUseExistingTextureResource) that all reference a single underlying FRHITexture via reference counting.A full development environment for Cesium for Unreal consists of three primary components:
cesium-native: Engine-independent libraries for 3D Tiles and geospatial functionality. Most plugin functionality is built upon these.cesium-unreal: The source code for the Cesium for Unreal plugin itself.cesium-unreal-samples repository is recommended for quick starts and regression testing.Note: While cesium-native can be developed independently, modifications to it must be carefully checked for breaking changes in the cesium-unreal API or build process.
When developing with or extending Cesium for Unreal, understand the distinction between the Runtime and Editor source directories:
Editor folder: Contains elements used exclusively within the Unreal Editor (e.g., UI components or editor-only functionality). Warning: Do not place code here that is required for the application to run at runtime, as these files will not be included in a packaged build.Runtime folder: Contains all logic required for the application to function. These classes are accessible to the Unreal Editor but are not exclusive to it.To make C++ members accessible to the Unreal Editor or Blueprints, you must use specific macros:
UPROPERTY)Use the UPROPERTY macro above member variables to expose them to the Editor UI or Blueprints.
UFUNCTION)Use the UFUNCTION macro to make C++ functions accessible to Blueprints or as buttons in the Editor interface.
USTRUCT)Use USTRUCT to expose C++ structs.
USTRUCTs are not managed by Garbage Collection.USTRUCT(BlueprintType) to enable the Make node in Blueprints.Break node, use BlueprintReadOnly or BlueprintReadWrite specifiers.UENUM)Use UENUM for enum classes used in a UObject context. These must be defined as an enum class of uint8 type.
UENUM()
enum class EMyEnum : uint8
{
...
};The Runtime directory is further organized into Public and Private subfolders to manage API visibility:
Public folder: Should contain files related to the public API.Private folder: Contains implementation details, private classes, and functions that are not part of the public interface.Dependency Rules:
Private can reference files in Public.Public cannot reference files in Private.If a class in the Public folder requires a type defined in Private (for example, as a member variable), you should use a forward declaration to avoid the dependency. If a forward declaration is not possible, you must move the required class to the Public folder, even if it is not intended to be part of the public API.
In v2.0, ECesiumMetadataTrueType is deprecated. Metadata types are now defined by the FCesiumMetadataValueType struct, which models the EXT_structural_metadata specification.
An FCesiumMetadataValueType consists of:
VECN, and MATN types. Set to None for others.