<GSplat/>

The <GSplat> component is used to render Gaussian Splats. Gaussian Splats are a new way of capturing and rendering high quality 3D content. They capture the shape and lighting of a scene in a way that produces incredibly high quality results.

The useSplat hooks accepts ply or sog files or any other files that can be loaded by the engine.

Usage

You can load a Gaussian Splat asset with the useSplat hook and then use the <GSplat> component to render it.

const { asset } = useSplat('/assets/toy-cat.sog');
<GSplat asset={asset} />

Demo

Load and render a Gaussian Splat - View Code

Code

gsplat-example.jsx

import { Entity } from '@playcanvas/react';
import { GSplat, Camera } from '@playcanvas/react/components';
import { useSplat } from '@playcanvas/react/hooks';

export const GSplatExample = () => {
    // Load the Gaussian Splat asset
    const { asset } = useSplat('/assets/toy-cat.sog');

    // If the asset is not loaded, return null
    if (!asset) return null;

    // Return the GSplat component
    return (
        <Entity rotation={[180, 180, 0]} position={[0, -0.7, 0]} >
            <GSplat asset={asset} />
        </Entity>
    );
};

Learn more about the GSplat Component in the PlayCanvas documentation.

Properties

Name	Type	Default
customAabb?	BoundingBox | null Sets a custom object space bounding box for visibility culling of the attached gsplat. Gets the custom object space bounding box for visibility culling of the attached gsplat. Returns the custom AABB if set, otherwise falls back to the resource's AABB.	-
material?	ShaderMaterial | null Sets the material used to render the gsplat. **Note:** This setter is only supported when unified is `false`. When it's true, multiple gsplat components share a single material per camera/layer combination. To access materials in unified mode, use GSplatComponentSystem#getMaterial . Gets the material used to render the gsplat. **Note:** This getter returns `null` when unified is `true`. In unified mode, materials are organized per camera/layer combination rather than per component. To access materials in unified mode, use GSplatComponentSystem#getMaterial .	-
highQualitySH?	boolean Sets whether to use the high quality or the approximate (but fast) spherical-harmonic calculation when rendering SOG data. The low quality approximation evaluates the scene's spherical harmonic contributions along the camera's Z-axis instead of using each gaussian's view vector. This results in gaussians being accurate at the center of the screen and becoming less accurate as they appear further from the center. This is a good trade-off for performance when rendering large SOG datasets, especially on mobile devices. Defaults to false. Gets whether the high quality (true) or the fast approximate (false) spherical-harmonic calculation is used when rendering SOG data.	-
castShadows?	boolean Sets whether gsplat will cast shadows for lights that have shadow casting enabled. Defaults to false. Gets whether gsplat will cast shadows for lights that have shadow casting enabled.	-
lodDistances?	number[] | null Sets LOD distance thresholds used by octree-based gsplat rendering. The provided array is copied. Gets a copy of LOD distance thresholds previously set, or null when not set.	-
splatBudget?	number Sets the target number of splats to render for this component. The system will adjust LOD levels bidirectionally to reach this budget: - When over budget: degrades quality for less important geometry - When under budget: upgrades quality for more important geometry This ensures optimal use of available rendering budget while prioritizing quality for closer/more important geometry. Set to 0 to disable the budget (default). When disabled, optimal LOD is determined purely by distance and configured LOD parameters. Only applies to octree-based gsplat rendering in unified mode. Gets the splat budget limit for this component.	-
unified?	boolean Sets whether to use the unified gsplat rendering. Default is false. Note: Material handling differs between modes. When unified is false, use GSplatComponent#material . When unified is true, materials are shared per camera/layer - use GSplatComponentSystem#getMaterial instead. Gets whether to use the unified gsplat rendering.	-
workBufferUpdate?	number Sets the work buffer update mode. Only applicable in unified rendering mode. In unified mode, splat data is rendered to a work buffer only when needed (e.g., when transforms change). Can be: - WORKBUFFER_UPDATE_AUTO: Update only when needed (default). - WORKBUFFER_UPDATE_ONCE: Force update this frame, then switch to AUTO. - WORKBUFFER_UPDATE_ALWAYS: Update every frame. This is typically useful when using custom shader code via workBufferModifier that depends on external factors like time or animated uniforms. Note: WORKBUFFER_UPDATE_ALWAYS has a performance impact as it re-renders all splat data to the work buffer every frame. Where possible, consider using shader customization on the unified gsplat material (`app.scene.gsplat.material`) which is applied during final rendering without re-rendering the work buffer. Gets the work buffer update mode.	-
layers?	number[] Sets an array of layer IDs (Layer#id ) to which this gsplat should belong. Don't push, pop, splice or modify this array. If you want to change it, set a new one instead. Gets the array of layer IDs (Layer#id ) to which this gsplat belongs.	-
asset?	number | Asset Sets the gsplat asset for this gsplat component. Can also be an asset id. Gets the gsplat asset id for this gsplat component.	-
resource?	GSplatResourceBase | null Sets a GSplat resource directly (for procedural/container splats). When set, this takes precedence over the asset property. Gets the GSplat resource. Returns the directly set resource if available, otherwise returns the resource from the assigned asset.	-
system?	ComponentSystem The ComponentSystem used to create this Component.	-
entity?	Entity The Entity that this Component is attached to.	-
enabled?	boolean Sets the enabled state of the component. Gets the enabled state of the component.	-