GaussianSplatNode3D API Reference¶

Purpose¶

Use GaussianSplatNode3D to render Gaussian splat assets or procedural splat arrays in a Node3D scene (modules/gaussian_splatting/nodes/gaussian_splat_node_3d.h:73).

Usage¶

Task	Primary API	Implementation
Assign preprocessed asset.	`set_splat_asset(asset)`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:511`
Load from file path (compatibility path).	`set_ply_file_path(path)`, `set_auto_load(enabled)`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:496`
Push procedural data.	`set_splat_data(...)`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:548`
Run manual updates.	`set_update_mode(UPDATE_MODE_MANUAL)`, `update_splats()`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:881`
Inspect live metrics.	`get_visible_splat_count()`, `get_statistics()`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:988`

API¶

Enums¶

Enum	Values	Source
`QualityPreset`	`QUALITY_PERFORMANCE`, `QUALITY_BALANCED`, `QUALITY_QUALITY`, `QUALITY_CUSTOM`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.h:81`
`ViewportUpdateMode`	`UPDATE_MODE_ALWAYS`, `UPDATE_MODE_WHEN_VISIBLE`, `UPDATE_MODE_WHEN_PARENT_VISIBLE`, `UPDATE_MODE_MANUAL`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.h:92`
`DebugDrawMode`	`DEBUG_DRAW_OFF`, `DEBUG_DRAW_WIREFRAME`, `DEBUG_DRAW_POINTS`, `DEBUG_DRAW_HEATMAP`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.h:103`

Properties¶

Inspector path	Type	Accessors	Notes	Source
`ply_file_path`	`String`	`set_ply_file_path`, `get_ply_file_path`	Deprecated compatibility path. Accepts `.ply` and `.spz` by file hint, but new scene workflows should prefer `splat_asset`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:89`
`splat_asset`	`GaussianSplatAsset`	`set_splat_asset`, `get_splat_asset`	Assign a preprocessed resource instead of a file path.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:93`
`auto_load`	`bool`	`set_auto_load`, `is_auto_load_enabled`	Loads automatically only when the node is inside the tree.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:536`
`quality/preset`	`int (QualityPreset)`	`set_quality_preset`, `get_quality_preset`	Preset values are applied through quality helper config.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:913`
`quality/lod_bias`	`float`	`set_lod_bias`, `get_lod_bias`	Clamped to `0.1..4.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:798`
`quality/max_render_distance`	`float`	`set_max_render_distance`, `get_max_render_distance`	Clamped to `>= 0.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:804`
`quality/max_splat_count`	`int`	`set_max_splat_count`, `get_max_splat_count`	Clamped to `>= 1000`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:810`
`painterly/enabled`	`bool`	`set_enable_painterly`, `is_painterly_enabled`	Enables painterly tuning and streaming flags.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:819`
`painterly/edge_threshold`	`float`	`set_edge_threshold`, `get_edge_threshold`	Clamped to `0.0..1.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:833`
`painterly/stroke_opacity`	`float`	`set_stroke_opacity`, `get_stroke_opacity`	Clamped to `0.0..1.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:842`
`painterly/stroke_width`	`float`	`set_stroke_width`, `get_stroke_width`	Clamped to `0.1..5.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:850`
`painterly/temporal_blend`	`float`	`set_temporal_blend`, `get_temporal_blend`	Clamped to `0.01..1.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:866`
`painterly/seed`	`int`	`set_painterly_seed`, `get_painterly_seed`	Clamped to `0..65535`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:875`
`rendering/update_mode`	`int (ViewportUpdateMode)`	`set_update_mode`, `get_update_mode`	Manual mode disables automatic processing.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:895`
`rendering/cast_shadow`	`bool`	`set_cast_shadow`, `get_cast_shadow`	Applies cast shadow state to render instance.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:902`
`rendering/frustum_culling`	`bool`	`set_use_frustum_culling`, `is_frustum_culling_enabled`	Applies immediately to renderer settings.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:916`
`rendering/opacity`	`float`	`set_opacity`, `get_opacity`	Clamped to `0.0..1.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:927`
`rendering/color_grading`	`ColorGradingResource`	`set_color_grading`, `get_color_grading`	Used by real-time grading and baking API.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1788`
`debug/preview_enabled`	`bool`	`set_preview_enabled`, `is_preview_enabled`	Controls editor preview visibility path.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:935`
`debug/show_bounds`	`bool`	`set_show_bounds`, `is_showing_bounds`	Toggles gizmo bounds rendering.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:941`
`debug/show_statistics`	`bool`	`set_show_statistics`, `is_showing_statistics`	Exposes read-only `stats/*` inspector fields when active.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:486`
`debug/show_tile_grid`	`bool`	`set_show_tile_grid`, `is_showing_tile_grid`	Persists via settings manager and updates renderer when allowed.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:585`
`debug/show_density_heatmap`	`bool`	`set_show_density_heatmap`, `is_showing_density_heatmap`	Persists via settings manager and updates renderer when allowed.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:599`
`debug/show_performance_hud`	`bool`	`set_show_performance_hud`, `is_showing_performance_hud`	Persists via settings manager and updates renderer when allowed.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:613`
`debug/show_lod_spheres`	`bool`	`set_show_lod_spheres`, `is_showing_lod_spheres`	Updates gizmos only.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:631`
`debug/show_performance_overlay`	`bool`	`set_show_performance_overlay`, `is_showing_performance_overlay`	Updates gizmos only.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:640`
`debug/overlay_opacity`	`float`	`set_debug_overlay_opacity`, `get_debug_overlay_opacity`	Clamped to `0.0..1.0`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:649`
`debug/debug_draw_mode`	`int (DebugDrawMode)`	`set_debug_draw_mode`, `get_debug_draw_mode`	Swaps renderer preview mode unless runtime preview override is enabled.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:662`
`debug/runtime_preview`	`bool`	`set_runtime_preview_enabled`, `is_runtime_preview_enabled`	Temporarily forces runtime modification preview mode in renderer.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:682`
`debug/show_residency_hud`	`bool`	`set_show_residency_hud`, `is_showing_residency_hud`	Persists via settings manager and updates renderer when allowed.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:701`

Methods¶

Method	Behavior	Source
`reload_asset()`	Triggers the same load path as setting a new file path.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:544`
`is_asset_loading()`	Returns asynchronous load state managed by the asset helper.	`modules/gaussian_splatting/nodes/gaussian_splat_node_helpers.cpp:90`
`set_splat_data(...)`	Builds a runtime asset from arrays after validating all optional array lengths.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:589`
`bake_color_grading()`	Bakes grading into data, disables grading resource, and returns `Error`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1794`
`restore_color_grading()`	Restores original colors and re-enables grading resource if present.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1821`
`is_color_grading_baked()`	Reports whether bake state is present in current renderer data.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1837`
`get_visible_splat_count()`	Returns node-level visible splat count after sync with renderer stats.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1106`
`get_total_splat_count()`	Returns node-level total splat count from asset or procedural data.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1111`
`get_last_update_time_ms()`	Returns elapsed update time measured in `update_splats()`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1230`
`get_gpu_memory_mb()`	Returns estimated GPU memory derived from loaded or procedural buffers.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1129`
`get_statistics()`	Returns node counters and merges any renderer stats dictionary keys.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:988`
`get_configuration_warnings()`	Returns warnings for missing assets, missing files, zero distance, and non-uniform scale.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1273`
`get_renderer()`	Returns the shared renderer instance for the node world.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1779`
`update_splats()`	Performs the full render update path and refreshes timing and metrics.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1026`
`force_update()`	Calls `update_splats()` and emits `viewport_visibility_changed`.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1268`

Signals¶

Signal	Parameters	Source
`asset_loaded`	None	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:281`
`asset_loading_failed`	`error: String`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:282`
`viewport_visibility_changed`	`visible: bool`	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:283`

Examples¶

extends Node3D

@onready var splat: GaussianSplatNode3D = $GaussianSplatNode3D

func _ready() -> void:
    var asset := load("res://splats/scene.ply") as GaussianSplatAsset
    splat.set_splat_asset(asset)
    splat.set_quality_preset(GaussianSplatNode3D.QUALITY_BALANCED)
    splat.set_update_mode(GaussianSplatNode3D.UPDATE_MODE_WHEN_VISIBLE)

extends Node3D

@onready var splat: GaussianSplatNode3D = $GaussianSplatNode3D

func _ready() -> void:
    var positions := PackedVector3Array([Vector3.ZERO])
    var colors := PackedColorArray([Color(1.0, 1.0, 1.0, 1.0)])
    splat.set_splat_data(positions, colors)
    splat.set_update_mode(GaussianSplatNode3D.UPDATE_MODE_MANUAL)
    splat.update_splats()

Troubleshooting¶

Problem	Action	Source
No splats appear after scene start.	Check `get_configuration_warnings()` for missing asset/path and zero render distance cases.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:1273`
`set_splat_data()` does nothing.	Ensure every optional array has the same length as `positions` when provided.	`modules/gaussian_splatting/nodes/gaussian_splat_node_3d.cpp:589`