This reference describes how Gaussian Splats work in UEFN, for engineers who want more detail than Gaussian Splats in Unreal Editor for Fortnite provides. It covers importing splat files, how Gaussian Splat assets are built and stored, and how splats are rendered.
Overview
UEFN supports Gaussian Splats with:
An importer for binary PLY and SPZ splat files, which creates Gaussian Splat assets.
A compressed storage format with automatically built levels of detail (LODs).
A GPU renderer that culls, selects LODs, sorts, and draws splats every frame. It runs on all platforms that UEFN supports.
Niagara support through the Splat Renderer and the Gaussian Splat Reader data interface. See Gaussian Splats and Niagara.
Assets, Actors, and Settings
| Item | Description |
|---|---|
Gaussian Splat asset | Stores the imported splats and their levels of detail. Created when you import a splat file. |
Gaussian Splat actor | Places a Gaussian Splat asset in a level. Created when you drag a Gaussian Splat asset into the viewport. |
Gaussian Splat component | The component on the Gaussian Splat actor that renders the asset. |
Gaussian Splat Component Settings
| Setting | Default | Range | Description |
|---|---|---|---|
Asset | None | — | The Gaussian Splat asset to render. |
Point Scale Factor | 1.0 | 0–1 | Multiplies the scale of every splat on each axis before the splat is projected to the screen. |
Opacity Scale | 1.0 | 0–1 | Multiplies the opacity of every splat. The result is clamped to 0–1. |
The component isn't a primitive component. It has no collision, doesn't cast or receive shadows, and doesn't contribute to Lumen, reflections, or ray tracing. To add collision, pair a Gaussian Splat actor with a hidden collision mesh. See Add Collision.
The actor's transform, visibility, and the component's settings are updated every frame. You can move, rotate, and scale Gaussian Splat actors at runtime, including with non-uniform scale.
Gaussian Splat Asset Settings
| Setting | Default | Description |
|---|---|---|
Min LOD | 0 | Per platform. The number of finest LOD levels removed when the project is cooked for that platform. See Min LOD. |
The asset also shows read-only information: the number of splats, the spherical harmonics (SH) degree, the bounds, and the coordinate space that the SH data was authored in.
Importing Splat Files
Import Options
| Option | Default | Range | Description |
|---|---|---|---|
Import Scale | 100.0 | 0.01–1000 | Multiplies splat positions and scales during import. The default converts meters to centimeters. |
SH Max Degree | Off | 0–3 | When enabled, removes SH data above this degree. It can't raise the degree stored in the file. |
When you reimport an asset, the import options window doesn't appear.
PLY Files
The file must use the binary little-endian format (format binary_little_endian 1.0). ASCII and big-endian PLY files aren't supported.
The header can contain only element vertex, property float, comment, and end_header lines. Any other header line, including non-float properties and additional elements such as face, causes the import to fail with Unknown header line (...).
The importer reads the following vertex properties. All of them are optional, and missing properties use the default value.
| Property | Meaning | Default |
|---|---|---|
x, y, z | Position | 0 |
scale_0, scale_1, scale_2 | Log scale on each axis | 0 (a scale of 1 before Import Scale) |
rot_0, rot_1, rot_2, rot_3 | Rotation quaternion (W, X, Y, Z) | No rotation |
opacity | Opacity before the sigmoid function is applied | 1.0 (about 0.73 after the sigmoid function) |
f_dc_0, f_dc_1, f_dc_2 | SH base color (RGB) | 0 |
f_rest_0 and up | Higher SH bands, stored as all red values, then all green, then all blue. Read up to the first missing index, to a maximum of 45. | — |
The SH degree is detected from the total number of SH coefficients, including the base color: 48 or more is degree 3, 27 or more is degree 2, 12 or more is degree 1, and fewer is degree 0.
SPZ Files
SPZ versions 2, 3, and 4 are supported.
SPZ version 1 isn't supported.
Versions 2 and 3 are gzip-compressed.
Version 4 uses zstd-compressed streams.
Conversion
The importer converts every splat to Unreal's coordinate system (left-handed, X forward, Y right, Z up), based on the file type:
| File type | Assumed source coordinate system | Position (X, Y, Z) | Rotation (X, Y, Z, W) |
|---|---|---|---|
SPZ | Right-handed: X right, Y up, Z back | (−Z, X, Y) | (−Z, X, Y, −W) |
PLY | Right-handed: X right, Y down, Z forward (COLMAP) | (Z, X, −Y) | (Z, X, −Y, −W) |
The importer also:
Converts log scale to linear scale, and applies the same axis remapping as positions.
Multiplies positions and scales by Import Scale.
Applies the sigmoid function to opacity.
Normalizes rotations.
Leaves SH data in its source coordinate system. The renderer accounts for the difference when it evaluates color.
Reorders splats spatially (in Morton, or Z-order, order), so that nearby splats are stored together. This makes culling and LOD generation more effective.
The importer doesn't remove splats based on opacity, size, or count.
Import Limits
A Gaussian Splat asset, including all of its levels of detail, must fit in a single GPU buffer of up to 4 GiB. The importer estimates the total size before it builds the asset, and rejects the import if it's too large. The approximate maximum number of splats in the source file depends on the SH degree:
| SH degree | Approximate maximum splats |
|---|---|
0 | 101 million |
1 | 63 million |
2 | 39 million |
3 | 25 million |
Most platforms have lower GPU buffer limits. See Runtime resource limits.
Asset Build
When you import a splat file, UEFN builds the Gaussian Splat asset in these steps:
Groups spatially adjacent splats into clusters of 64 splats. Clusters are used for culling and LOD selection.
Builds the levels of detail.
Compresses the splat data.
Levels of detail
Each level of detail has about half as many splats as the level before it:
Adjacent splats are merged in pairs. Each merged splat preserves the combined position, shape, and color of the pair, weighted by opacity and size, so that coarser levels keep the overall appearance.
Each merge records an error value: how far the original splats are from the merged splat. A cluster's error includes the error of the levels below it, so error increases at coarser levels.
All levels are stored together, finest first. In total, an asset stores about twice as many splats as the source file.
At runtime, the renderer uses these error values to choose a level of detail for each cluster. See Culling and level of detail.
Min LOD
Min LOD is applied only when the project is cooked, separately for each platform:
A Min LOD of N removes the N finest levels from the cooked asset. Each step removes about half of the remaining splats and memory.
The editor always shows all levels.
Dedicated servers don't load splat data.
Compressed Format
Splat data is stored in a compressed format. Each splat uses 32-bit words as follows:
| Data | Encoding |
|---|---|
Position | 21 bits per axis, relative to the asset's bounds |
Scale | Logarithmic, 11, 11, and 10 bits |
Rotation | X, Y, and Z, 11, 11, and 10 bits. W is reconstructed. |
Base color and opacity | 8 bits per channel |
Higher SH bands | One 32-bit word per coefficient, 8 bits per color channel |
Memory per stored splat:
| SH degree | Bytes per splat |
|---|---|
0 | 20 |
1 | 32 |
2 | 52 |
3 | 80 |
Because all levels of detail are stored, an asset uses about twice this amount per source splat, plus a small amount for cluster data. Gaussian Splat assets used in your levels count toward the island's download size limit (400 MB). To reduce asset size, lower SH Max Degree at import, or raise Min LOD.
Rendering
When Splats are Drawn
Splats are drawn during post-processing:
After opaque geometry, lighting, fog, and translucency.
Before depth of field, temporal anti-aliasing and upscaling, motion blur, bloom, exposure, and tone mapping. These effects apply to splats.
At the render resolution, before upscaling.
Depth and Compositing
Splats are depth-tested against the scene, so opaque geometry in front of a splat hides it.
Splats don't write depth. Because translucent surfaces don't write depth either, splats draw on top of translucent surfaces such as glass and water.
Splats are blended back to front with premultiplied alpha.
Splats don't write velocity, so a moving Gaussian Splat actor doesn't produce motion blur from its own motion.
Sorting
Splats are sorted by depth on the GPU every frame, separately for each Gaussian Splat actor. Splats from different Gaussian Splat actors aren't sorted against each other. Each actor is sorted and drawn separately, so when actors overlap or intersect, one can appear to draw through the other. Improved blending between Gaussian Splat actors is planned.
Culling and Level of Detail
Frustum culling: clusters, and then individual splats, outside the camera view are skipped.
Level of detail: for each cluster, the renderer projects the cluster's error to the screen and selects the coarsest level whose error is less than about one pixel. Distant and small parts of a splat use coarser levels.
There is no distance-based culling, occlusion culling, or support for cull distance volumes.
Color
Splats are unlit. Their color comes only from their SH data, evaluated for the viewing direction. Spherical harmonics up to degree 3 are supported.
Rendering Stages
For each view, and for each Gaussian Splat actor, the renderer:
Culls clusters and selects levels of detail.
Shades splats: projects each splat to the screen and calculates its color for the viewing direction.
Sorts splats by depth.
Rasterizes splats: draws each splat as a screen-aligned quad, with a Gaussian falloff.
Composites the result into the scene.
Runtime resource limits
Each Gaussian Splat asset is stored in a single GPU buffer. The maximum buffer size depends on the platform, up to 4 GiB.
If an asset doesn't fit on a platform, the finest levels of detail are dropped until it does.
There is no limit on the total number of splats in a scene, but rendering cost grows with the number of visible splats.
Platform Support
Gaussian Splats render on all platforms that UEFN supports. On lower-end platforms, level of detail is the main way to manage cost and memory:
Min LOD removes the finest levels when the project is cooked for each platform.
Runtime LOD selection uses coarser levels for distant and small parts of a splat.
Buffer limits: if an asset is too large for a platform's GPU buffer limit, the finest levels are dropped automatically.
As a rough guide, on lower-end platforms keep each Gaussian Splat asset to about 1 million splats or fewer to hold 30 frames per second.
Particles drawn with the Niagara Splat Renderer don't use level of detail. See Gaussian Splats and Niagara.
Error Messages
| Message | Cause |
|---|---|
Not a valid PLY file | The first line of the header isn't ply. |
Unknown header line (...) | The file uses ASCII or big-endian format, has a non-float property, or has an unsupported element. |
Only binary little endian 1.0 format is currently supported | The header has no format line. |
Unexpected end of file, missing 'end_header'. | The header is incomplete. |
Expected valid 'element vertex' in header but not found. | The header has no vertex count. |
Malformed PLY file (... bytes allocated, but ... are required for ... vertices). | The file is shorter than its header indicates. |
Invalid SPZ file, file too small. or Invalid SPZ file, header magic invalid. | The file isn't a valid SPZ version 2 or 3 file. |
SPZ Version (N) is not supported | The file is SPZ version 1 or an unknown version. |
Truncated SPZ vN payload (...) | The file is shorter than its header indicates. |
Invalid SPZ v4 header or SPZ v4 stream N ... | The SPZ version 4 file is corrupt. |
Failed to import SPZ file | Appears after any SPZ import error. |
Import failure. Asset ... builds ... runtime splats across its LOD levels, requiring ... Consider importing with fewer splats or a lower SH value. | The asset would exceed the import limits. The message is followed by the maximum number of splats for each SH degree. |
Encountered non-finite positions during import. | The file contains invalid (NaN or infinite) positions. |
Gaussian splat asset '...' was built with an older version. Resave to upgrade the asset. | The asset was created with an earlier version of UEFN. Save it to upgrade it. |
Gaussian Splat '...' could not be loaded. | The cooked asset data couldn't be loaded. |