ULCCComponentBase：3DGS Component 基类

所有 LCC Component 的基类，承载渲染、颜色、性能、碰撞、GIS 等能力。ULCCComponent（LCC1）和 ULCC2Component（LCC2）继承自它。


模块	`LCC4UnrealRuntime`
头文件	`LCCComponentBase.h`
父类	`UPrimitiveComponent`、`IInterface_CollisionDataProvider`

#include "LCCComponentBase.h"

通过 Actor 获取实例：

ULCCComponentBase* Component = LCCActor->GetLCCComponent();

本页是接口索引，说明每个方法的签名、参数与调用要点。参数该怎么调、调了有什么视觉与性能后果，见对应专题文档：

想了解	看这里
渲染模式、球谐、抗锯齿	渲染
颜色、透明度、Splat 大小	画面调节
法线模式、光照	法线与光照
性能参数取值建议	性能优化参数说明、性能优化指南
裁剪与剖切	场景编辑
碰撞	碰撞
加载动画	加载动画

两条管线的差异

部分属性与方法声明在基类上，但只有一条管线真正实现。写代码前先确认目标数据走的是哪条管线。

接口	LCC1（`ULCCComponent`）	LCC2（`ULCC2Component`）
`bReceiveShadows`、`EnableReceiveShadows`、`DisableReceiveShadows`	支持	不支持，面板隐藏
`bEnableMultipleLCCActorAutoSort`	支持	不支持，面板隐藏
`bUseCustomFOV`、`OverrideMainCameraFOV`	支持	不支持
多视口系列（`SetPlayerLoadMode`、`ModifyPlayerTransform` 等）	支持	不支持
`SetLightMode` 的材质切换	切换 Lit / Unlit 材质	不切材质，光照由着色器内部处理
`Performance.LevelFactor`	影响距离与 Level 的映射	作为屏幕空间误差缩放因子，机制不同
`Performance.bUseFullLoad`	默认开关关闭，值为 true	构造时改为开关启用、值为 false

Properties

带 BlueprintSetter 的属性，在细节面板拖动数值与在代码里调 Setter 走同一条路径。带 Interp 的属性可在 Sequencer 里做关键帧。

加载路径

属性	类型	默认	说明
`DefaultLoadPath`	`FString`	空	加载路径。在细节面板填好后关卡启动会自动加载。绝对路径如 `D:\lcc\Tower\Tower.lcc`，相对路径以 `Content` 为基准如 `Tower/Tower.lcc`。`Load()` 成功后这个值会被同步成实际加载的路径，`Refresh()` 依赖它；`UnLoad()` 会清空它

渲染属性

属性	类型	默认	Setter	说明
`RenderMode`	`ERenderMode`	`Splatting`	`SetRenderMode`	渲染为 3DGS 还是点云
`LoadMode`	`ELoadMode`	`Both`	`SetLoadMode`	渲染主体、环境、两者还是都不渲染
`LightMode`	`ELightMode`	`Unlit`	`SetLightMode`	是否参与场景光照
`SplatScale`	`float`	1.0	`SetSplatScale`	Splat 面片大小，范围 0.001~1.0。1.0 已是上限
`GlobalAlpha`	`float`	1.0	`SetGlobalAlpha`	3DGS 整体不透明度，范围 0~1
`GlobalAlpha_PointCloud`	`float`	0.2	`SetGlobalAlpha_PointCloud`	点云整体不透明度，范围 0~1
`bUseShcoef`	`bool`	true	`SetUseShcoef`	是否启用球谐。数据不含球谐时该项不可编辑
`bUseMipFilter`	`bool`	true	`SetUseMipFilter`	抗闪烁滤波
`bCanSetShcoef`	`bool`	—	—	数据是否含球谐的判据，`EditDefaultsOnly`，蓝图不可访问。运行时判断请用 CanSetShcoef()
`bAffectAntiAliasingMethod`	`bool`	true	—	开启后按项目设置自动切换抗锯齿方法，见抗锯齿
`bReceiveShadows`	`bool`	false	—	接收阴影，实验性。仅 LCC1，且仅 3DGS 模式

性能属性

Performance 字段类型为 FRenderInfo。每个数值都配一个启用开关，开关关闭时用内置默认值。字段清单见 Structs，取值建议见性能优化参数说明。

调色属性

属性	类型	默认	滑块范围	Setter
`Saturation`	`FVector4`	(1,1,1)	0~2	`SetSaturation`
`Contrast`	`FVector4`	(1,1,1)	0~2	`SetContrast`
`Gamma`	`FVector4`	(1,1,1)	0~2	`SetGamma`
`Offset`	`FVector4`	(0,0,0)	-1~1	`SetOffset`
`ColorTint`	`FLinearColor`	White	—	`SetColorTint`

四个分量依次对应 R、G、B 与整体。调色效果说明见画面调节。

注意这几项的范围只是面板滑块范围（UIMin / UIMax），没有 Clamp。代码里调 Setter 传超出范围的值不会被截断，效果自负。相比之下 SplatScale、GlobalAlpha 是真 Clamp。

点云配色属性

属性	类型	默认	Setter
`ElevationColorBottom`	`FLinearColor`	Blue	`SetElevationColorBottom`
`ElevationColorTop`	`FLinearColor`	Red	`SetElevationColorTop`

碰撞属性

属性	类型	默认	Setter	说明
`bEnableCollision`	`bool`	false	`SetLCCCollisionEnable`	是否加载碰撞数据。需要数据本身带碰撞文件

详见碰撞。

摄像机属性

以下三项仅 LCC1 管线有效，LCC2 组件的细节面板会隐藏后两项。

属性	类型	默认	说明
`bUseCustomFOV`	`bool`	false	是否覆盖首个摄像机的 FOV
`OverrideMainCameraFOV`	`float`	90.0	覆盖用的 FOV 值，范围 5~180
`bEnableMultipleLCCActorAutoSort`	`bool`	true	多个 LCC Actor 同场景时按距离排序并设置半透明优先级，见多 Actor 半透排序

GIS 属性

属性	类型	默认	说明
`bEnableGeoPlace`	`bool`	false	是否按经纬度放置场景
`GeoLocationOffset`	`FVector`	(0,0,0)	位置偏移
`GeoMultiply`	`FVector`	(1,1,1)	缩放乘数，高级项

与 Cesium 配合的搭建步骤见第三方与引擎插件集成。

裁剪与剖切属性

属性	类型	说明
`ClippingVolumes`	`TArray<TObjectPtr<ALCCClippingVolume>>`	裁剪体数组
`SectionPlanes`	`TArray<TObjectPtr<ALCCSectionPlane>>`	剖切面数组

两个数组是 BlueprintReadOnly，不要直接改元素，用 AddClippingVolume 等方法维护。

动画属性

动画分两个阶段：第一阶段延迟 FirstStageDelay 后从 0 缩放到 AnimationMinScale，第二阶段延迟 SecondStageDelay 后从 AnimationMinScale 缩放到 SplatScale。

属性	类型	默认	说明
`bEnableAnimation`	`bool`	false	启用动画。Setter `SetEnableAnimation` 会同时重置时间轴
`bInverseAnimation`	`bool`	false	反向播放，从远到中心收拢，即消失效果
`InverseMaxRangeTime`	`float`	30.0	反向动画初始可见半径对应的时间，单位秒。乘以 `AnimationSpeed` 得到实际半径
`AnimationSpeed`	`float`	100.0	动画速度
`AnimationMinScale`	`float`	0.2	第一阶段目标缩放，范围 0.0001~1.0
`FirstStageDelay`	`float`	0.0	第一阶段延迟，单位秒
`SecondStageDelay`	`float`	5.0	第二阶段延迟，单位秒
`EnvironmentDelay`	`float`	10.0	环境数据延迟，单位秒
`AnimationOriginOffset`	`FVector3f`	(0,0,0)	动画起始点偏移
`FirstStageColor`	`FLinearColor`	金色	第一阶段扫描线颜色，需 `bUseFirstStageColor`（默认开）
`SecondStageColor`	`FLinearColor`	金色	第二阶段扫描线颜色，需 `bUseSecondStageColor`（默认开）
`ScanLineThickness`	`float`	5.0	扫描线宽度

参数效果与调法见加载动画。

Loading and State

Load

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool Load(FString LCCPath);

加载数据。ALCCActorBase::Load 最终调用的就是它。

参数	类型	说明
`LCCPath`	`FString`	数据文件路径，绝对路径或相对 `Content` 目录

返回 bool：路径校验通过并启动加载流程返回 true。传空路径会执行卸载并同样返回 true。

用法要点：

返回 true 只代表流程启动，不代表数据就绪。当前版本需用 CheckIfLoaded 轮询，后续版本会提供加载完成回调。
传入路径与当前已加载路径相同时直接返回，不重复加载。
加载成功会把路径写入 DefaultLoadPath。

ULCCComponentBase* Component = LCCActor->GetLCCComponent();
if (Component && Component->Load(TEXT("D:/Data/Tower/Tower.lcc")))
{
    UE_LOG(LogTemp, Log, TEXT("Load started"));
}

UnLoad

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual void UnLoad();

卸载数据，释放节点缓存、GPU 缓冲与碰撞体，并清空 DefaultLoadPath。

两点注意：

因为会清空 DefaultLoadPath，UnLoad() 之后直接调 Refresh() 不会重新加载任何东西。
元信息不会被清空。卸载后 GetMetaInfo() 与 GetSplatNumber() 仍返回上一次加载的数据，不要用它们判断是否已卸载，用 CheckIfLoaded。

Refresh

UFUNCTION(BlueprintCallable, Category = "XGrids")
void Refresh();

重新加载当前数据。实现是 UnLoad() 加 Load(DefaultLoadPath)，开销等同完整重新加载。

数据文件在磁盘上被替换后用它重新读盘。只想让渲染更新一帧的话用 ForceUpdate。

ForceUpdate

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ForceUpdate();

标记下一帧强制更新一次场景，开销很小。

摄像机与渲染参数都没变时插件会跳过节点更新。如果从外部改了影响可见性的东西而画面没跟上，用它推一帧。不要每帧调用，那会让跳过优化失效。

CheckIfLoaded

UFUNCTION(BlueprintPure, Category = "XGrids")
virtual bool CheckIfLoaded() const;

元信息与索引结构是否已建立。BlueprintPure，蓝图里是无执行引脚的纯节点。

准确含义：LCC1 判断节点管理器是否已创建，LCC2 判断树是否已创建。返回 true 表示元信息解析完成、可以安全读取元信息和配置参数，但 Splat 数据仍在按视角流式加载，画面会继续逐步补齐。

也就是说它不代表「画面已完整」。需要等画面稳定的场合，这个函数给不了答案。

if (Component->CheckIfLoaded())
{
    // 安全地读取元信息、配置参数
}

文本蓝图，每 0.2 秒轮询一次：

[Event BeginPlay]
        │
        ▼
[Set Timer by Event]
        Time = 0.2
        Looping = true
        Event ──▶ [Custom Event: CheckLoaded]

[Custom Event: CheckLoaded]
        │
        ▼
[Get LCC Component] ──▶ [Check If Loaded]
                              │ Return Value ──┐
                              ▼                │
                        [Branch] ◀─────────────┘
                              │ True
                              ▼
                        [Clear and Invalidate Timer by Handle]
                              │
                              ▼
                        (加载完成后的配置)

GetSplatNumber

UFUNCTION(BlueprintCallable, Category = "XGrids")
int GetSplatNumber() const;

返回数据的 Splat 总数，取自元信息的 TotalSplats。

用法要点：

这是数据固有的总量，不随摄像机移动变化，不是当前帧实际渲染的数量。
首次加载前返回 0。但因为 UnLoad() 不清空元信息，卸载后仍会返回上一次的值。
想知道当前帧渲染压力，用 Actor 上的 Stats() 打开统计面板看实时数据。

if (Component->CheckIfLoaded())
{
    UE_LOG(LogTemp, Log, TEXT("Total splats in dataset: %d"),
        Component->GetSplatNumber());
}

HaveValidSplatData

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual bool HaveValidSplatData();

是否有有效的 Splat 数据可渲染。加载失败或数据为空时返回 false。

HaveValidCollisionData

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool HaveValidCollisionData();

数据是否带碰撞文件。

注意它只检查新版 collision.lci，不检查旧版 collision.bin，也不检查点云 .ply 碰撞。而实际加载碰撞时三种格式都支持，所以只带 collision.bin 的数据集会出现这个函数返回 false、但 SetLCCCollisionEnable(true) 依然能成功加载的情况。

要准确判断三种格式，用 ULCCUtilLibrary::DetermineCollisionType（传数据所在目录）。

if (Component->HaveValidCollisionData())
{
    Component->SetLCCCollisionEnable(true);
}

CanRender

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual bool CanRender() const;

当前是否满足渲染条件。判断依据是组件的可见性状态，加上子类的数据结构是否已建立（LCC1 看节点管理器，LCC2 看树）。不涉及元信息有效性。

CanSetShcoef

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool CanSetShcoef() const;

数据是否含球谐系数。实现上等价于判断文件类型为 EFileType::Quality。

调 SetUseShcoef 前用它判断，也可用于决定 UI 上球谐开关是否置灰。

GetMetaInfo

UFUNCTION(BlueprintPure, Category = "XGrids")
virtual FMetaInfoBase GetMetaInfo() const;

返回数据元信息，含名称、版本、坐标系、总 Level 数、总 Splat 数等。字段详见 Structs。

加载完成后再读，未就绪时字段是零值。返回的是基类切片，要 LCC1/LCC2 的完整字段用子类上的专用方法。

if (Component->CheckIfLoaded())
{
    const FMetaInfoBase Meta = Component->GetMetaInfo();
    UE_LOG(LogTemp, Log, TEXT("Name=%s Levels=%d RTK=%s"),
        *Meta.Name, Meta.TotalLevel, Meta.IsRTK() ? TEXT("yes") : TEXT("no"));
}

GetLocalVisibleBounds

UFUNCTION(BlueprintPure, Category = "XGrids")
virtual FBox GetLocalVisibleBounds() const;

返回模型在组件本地空间的可见包围盒。数据不可用时返回无效盒（FBox(ForceInit)），用前先查 IsValid。

要世界空间自己用 GetComponentTransform() 变换。常见用途是把摄像机自动摆到能看全场景的位置。

const FBox LocalBounds = Component->GetLocalVisibleBounds();
if (LocalBounds.IsValid)
{
    const FBox WorldBounds =
        LocalBounds.TransformBy(Component->GetComponentTransform());

    const FVector Center = WorldBounds.GetCenter();
    const float Radius = WorldBounds.GetExtent().Size();
    // 用 Center 与 Radius 计算观察位置
}

GetLccVersion

virtual ELCCVersion GetLccVersion() const;

返回数据版本，ELCCVersion::LCC 或 ELCCVersion::LCC2。仅 C++ 可用。

Rendering

各参数的视觉效果与取舍见渲染与画面调节，这里只说接口。

SetRenderMode / GetRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetRenderMode(ERenderMode InRenderMode);

UFUNCTION(BlueprintPure, Category = "XGrids")
ERenderMode GetRenderMode() const;

切换 3DGS（ERenderMode::Splatting）与点云（ERenderMode::PointCloud）。

点云模式下 3DGS 专属项不起作用，透明度改用 GlobalAlpha_PointCloud。

对应面板参数渲染模式。

Component->SetRenderMode(ERenderMode::PointCloud);

文本蓝图：

[Input Action: ToggleView]
        │ Pressed
        ▼
[Get LCC Component]
        Target = LCCActor
        │ Return Value ──┐
        ▼                │
[Set Render Mode] ◀──────┘
        Target = (Return Value)
        In Render Mode = Point Cloud

ToggleRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleRenderMode();

在 3DGS 与点云之间来回切换，不用自己判断当前状态。

SetLoadMode / GetLoadMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLoadMode(ELoadMode Mode);

UFUNCTION(BlueprintPure, Category = "XGrids")
ELoadMode GetLoadMode() const;

控制渲染主体数据、环境数据，还是两者。取值见 ELoadMode，面板说明见加载模式。

ELoadMode::None 相当于临时隐藏，但保留已加载数据在内存里，比 UnLoad 恢复快。

Component->SetLoadMode(ELoadMode::OnlyMain);

SetLightMode / GetLightMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
virtual void SetLightMode(ELightMode InLightMode);

UFUNCTION(BlueprintPure, Category = "XGrids")
ELightMode GetLightMode() const;

控制是否参与场景光照，ELightMode::Unlit 或 ELightMode::Lit。

两条管线的实现方式不同：

LCC1 通过切换 Lit / Unlit 材质实现。
LCC2 不切换材质，光照在着色器内部处理。因此 LCC2 还需要配 NormalMode 才能得到合理的明暗，详见 ULCC2Component 与法线与光照。

采集数据已经烘进了现场光照，切 Lit 容易过曝。LCC2 可用 LightingScale 压低原始亮度。

点云模式下这个 Setter 无效，内部会跳过赋值并输出一条警告日志。要改光照模式，先切回 3DGS。

对应面板参数光照模式。

ToggleLightMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleLightMode();

在 Unlit 与 Lit 之间切换。

SetUseShcoef / GetUseShcoef

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUseShcoef(bool InUseShcoef);

UFUNCTION(BlueprintPure, Category = "XGrids")
bool GetUseShcoef() const;

开关球谐。球谐提供视角相关的颜色变化，关掉后颜色固定。

用法要点：

前提是数据含球谐，用 CanSetShcoef 判断。数据为 Portable 类型时没有球谐可用，此项在面板上不可编辑。
点云模式下这个 Setter 静默无效。内部要求数据为 Quality 类型且当前不是点云模式，两个条件不满足时赋值直接被跳过。
LCC2 可以只降阶数而不完全关掉，见 SetSHBands。
面板说明见球谐系数（SH）。

if (Component->CanSetShcoef())
{
    Component->SetUseShcoef(false);
}

ToggleShcoef

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ToggleShcoef();

开关球谐，用于对比效果。

SetSplatScale / GetSplatScale

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSplatScale(float InSplatScale);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetSplatScale() const;

Splat 面片大小，范围 0.001~1.0，默认 1.0。

用法要点：

默认值 1.0 就是上限，只能往小调。
调小能减少 Overdraw、提升帧率，代价是面片变小后画面可能出现空洞。
只影响 3DGS 模式。
面板说明见 SplatScale。

// 压 Overdraw 换帧率，视情况权衡空洞
Component->SetSplatScale(0.8f);

SetGlobalAlpha / GetGlobalAlpha

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGlobalAlpha(float InGlobalAlpha);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetGlobalAlpha() const;

3DGS 整体不透明度，范围 0~1。带 Interp，可在 Sequencer 里打关键帧做淡入淡出。

点云模式请用 SetGlobalAlpha_PointCloud，两个值独立。面板说明见全局透明度。

// 逐帧淡出
const float Next = FMath::FInterpTo(
    Component->GetGlobalAlpha(), 0.0f, DeltaTime, 2.0f);
Component->SetGlobalAlpha(Next);

文本蓝图，用 Timeline 淡出：

[Timeline: FadeOut]
        Length = 2.0
        Float Track "Alpha" = 1.0 → 0.0
        │ Update
        ▼
[Set Global Alpha]
        Target = (LCC Component)
        In Global Alpha = (Timeline 的 Alpha 输出)

SetGlobalAlpha_PointCloud / GetGlobalAlpha_PointCloud

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGlobalAlpha_PointCloud(float InGlobalAlpha);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetGlobalAlpha_PointCloud() const;

点云模式的整体不透明度，范围 0~1，默认 0.2。

SetUseMipFilter / GetUseMipFilter

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetUseMipFilter(bool InUseMipFilter);

UFUNCTION(BlueprintPure, Category = "XGrids")
bool GetUseMipFilter() const;

开关抗闪烁滤波，默认开启。开启时用带不透明度补偿的低通滤波，不同缩放下更稳定；关闭时更锐利但可能走样闪烁。仅 3DGS 模式有效。

面板说明见 Mip Filter。

EnableReceiveShadows / DisableReceiveShadows

UFUNCTION(BlueprintCallable, Category = "XGrids")
void EnableReceiveShadows();

UFUNCTION(BlueprintCallable, Category = "XGrids")
void DisableReceiveShadows();

开关阴影接收，实验性功能。

用法要点：

仅 LCC1 管线支持，LCC2 组件的细节面板隐藏该属性。
仅 3DGS 模式有效，对性能影响较大。
内部通过切换到专用材质实现，因此会重新走一次材质设置。
面板说明见阴影接收。

Performance

这组 Setter 有一个共同行为：调用时会自动把对应的启用开关置为 true。Getter 返回生效值，开关关闭时返回内置默认值而不是你之前填过的值。

GetPreloadDistance 是唯一例外，它返回的是原始字段值，不是生效值。

取值建议见性能优化参数说明与性能优化指南。

SetMaxDistance / GetMaxDistance

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxDistance(const int32 InDistance);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxDistance() const;

最大渲染距离，单位米，内置默认 300。超出该距离的节点不渲染。

对应面板参数 Max Distance。

Component->SetMaxDistance(80);

SetMaxSplatNum / GetMaxSplatNum

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxSplatNum(const int32 InSplatNum);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxSplatNum() const;

每帧最大 Splat 数量，单位是万，上限 10000。传 1500 表示 1500 万。

超出 GPU 单帧能力的值会被自动限制。对应面板参数 Max Splat Num。

Component->SetMaxSplatNum(1500);   // 1500 万

SetLevelFactor / GetLevelFactor

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLevelFactor(const float InLevelFactor);

UFUNCTION(BlueprintPure, Category = "XGrids")
float GetLevelFactor() const;

LOD 缩放因子，范围 0.01~20，默认 1。值变大意味着细节减少、性能变好。

两条管线的作用机制不同：

LCC1：除在项目设置的 RangeForLevel 上，改变距离与 Level 的映射关系。
LCC2：作为屏幕空间误差的缩放因子参与节点选择。

因此同一个数值在两条管线上的视觉效果不能直接类比，各自实测。

对应面板参数 Level Factor。

Component->SetLevelFactor(1.5f);

SetStartLevel / GetStartLevel

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetStartLevel(const int32 InStartLevel);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetStartLevel() const;

起始 Level，范围 0~20，默认 0。Level 0 细节最高，上调可跳过最精细的层级，显著降低显存占用与加载量。

对应面板参数 Start Level。

SetEndLevel / GetEndLevel

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetEndLevel(const int32 InEndLevel);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetEndLevel() const;

结束 Level，范围 0~20，默认 20。限制最粗那一端的 Level，一般不需要动。

对应面板参数 End Level。

SetMaxCollisionDistance / GetMaxCollisionDistance

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetMaxCollisionDistance(const int32 InMaxCollisionDistance);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetMaxCollisionDistance() const;

碰撞加载最大距离，单位米，内置默认 300。

需要远距离射线检测时，这个值要覆盖检测范围，否则打不中。

对应面板参数 Max Load Collision Distance。

SetPreloadDistance / GetPreloadDistance

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPreloadDistance(const int32 InPreloadDistance);

UFUNCTION(BlueprintPure, Category = "XGrids")
int32 GetPreloadDistance() const;

预加载距离，单位米。

注意：当前版本生效逻辑固定为 MaxDistance + 35，Setter 设的值不参与计算，该项在面板上也未暴露。保留接口是为了兼容，日常不需要调用。

Color Adjustment

调色属性都是 FVector4，四个分量依次对应 R、G、B 与整体。所有调色 Setter 即时生效。效果说明见画面调节。

UFUNCTION(BlueprintCallable, Category = "XGrids|Color")
void SetSaturation(const FVector4 InSaturation);   // 饱和度，0~2
void SetContrast(const FVector4 InContrast);       // 对比度，0~2
void SetGamma(const FVector4 InGamma);             // Gamma，0~2
void SetOffset(const FVector4 InOffset);           // 加性偏移，-1~1
void SetColorTint(const FLinearColor InColor);     // 色调乘算

// 对应 Getter
FVector4 GetSaturation() const;
FVector4 GetContrast() const;
FVector4 GetGamma() const;
FVector4 GetOffset() const;
FLinearColor GetColorTint() const;

Offset 是加算，会把暗部一起抬起来；ColorTint 是乘算，暗部保持暗。各项效果见颜色调整。

// 降饱和 + 略微提亮
Component->SetSaturation(FVector4(0.6f, 0.6f, 0.6f, 0.6f));
Component->SetOffset(FVector4(0.05f, 0.05f, 0.05f, 0.f));

点云高程着色

UFUNCTION(BlueprintCallable, Category = "XGrids|PointCloud")
void SetElevationColorBottom(FLinearColor InElevationColorBottom);

UFUNCTION(BlueprintCallable, Category = "XGrids|PointCloud")
void SetElevationColorTop(FLinearColor InElevationColorTop);

UFUNCTION(BlueprintPure, Category = "XGrids|PointCloud")
FLinearColor GetElevationColorBottom() const;

UFUNCTION(BlueprintPure, Category = "XGrids|PointCloud")
FLinearColor GetElevationColorTop() const;

高程渐变的底部与顶部颜色，默认蓝到红。

Component->SetRenderMode(ERenderMode::PointCloud);
Component->SetElevationColorBottom(FLinearColor(0.0f, 0.2f, 1.0f, 1.0f));
Component->SetElevationColorTop(FLinearColor(1.0f, 0.1f, 0.0f, 1.0f));

Collision

SetLCCCollisionEnable

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetLCCCollisionEnable(const bool InEnable);

开关碰撞数据加载。

参数	类型	说明
`InEnable`	`bool`	`true` 加载碰撞，`false` 卸载已加载的碰撞体

用法要点：

前提是数据带碰撞文件，先用 HaveValidCollisionData 确认。
碰撞按距离流式加载，受 Performance.CollisionLoadMaxDistance 限制。
开启后可直接用引擎的 LineTraceByChannel、角色移动、物理模拟。
首次开启有一次烘焙开销，可能造成短暂卡顿。尽量在加载阶段就开好。
用 Actor 上的 ShowCollision() 可以看碰撞线框确认是否加载出来。

完整说明见碰撞。

if (Component->HaveValidCollisionData())
{
    Component->SetMaxCollisionDistance(50);
    Component->SetLCCCollisionEnable(true);
}

GIS

地理放置常与 Cesium 配合使用，把 LCC 场景摆到真实地球坐标上。搭建步骤、插件依赖与注意事项见第三方与引擎插件集成。

SetGeoPlacement

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetGeoPlacement(bool InEnable);

开关按经纬度放置场景。

启用后场景会按真实地理坐标自动摆位，手动设置的 Actor 位置会被覆盖，微调用 GeoLocationOffset。多个 LCC 场景同时启用时会按真实相对位置自动对齐。

用法要点：

内部会自动执行一次 Refresh()（卸载加重新加载），所以随时调用都能生效，不需要自己重新 Load()。代价是开销等同完整重新加载，不要频繁切换。
前提是数据含 RTK 信息。判断请用 GetMetaInfo().IsRTK()，不要用 CanUseGeoPlace()，后者要求地理放置已经启用，启用前恒为 false。

if (Component->CheckIfLoaded() && Component->GetMetaInfo().IsRTK())
{
    Component->SetGeoPlacement(true);   // 会自动重新加载
}

CanUseGeoPlace

UFUNCTION(BlueprintCallable, Category = "XGrids")
bool CanUseGeoPlace() const;

地理放置当前是否处于可用状态。三个条件必须同时满足：bEnableGeoPlace 已开启、数据含 RTK 信息、地理参考系统已创建。

这不是「数据是否支持地理放置」的判据。 因为它要求 bEnableGeoPlace 已经为 true，在启用之前调用恒返回 false。想在启用前判断数据是否支持，用 GetMetaInfo().IsRTK()。

它的实际用途是启用之后确认是否真的生效了。

GetRTKBaseLocation

UFUNCTION(BlueprintCallable, Category = "XGrids")
FVector GetRTKBaseLocation() const;

返回 RTK 基站位置换算到引擎空间后的坐标，即数据的地理原点。需要把外部地理坐标换算到引擎坐标时，这是基准点。

注意：内部会直接使用地理参考系统做坐标转换，不做空值检查。地理参考系统尚未创建时调用会崩溃。调用前先确认 CanUseGeoPlace 为 true，或 GetGeoReferencingSystem 返回非空。

GetGeoReferencingSystem

UFUNCTION(BlueprintCallable, Category = "XGrids")
ALCCGeoReferencingSystem* GetGeoReferencingSystem() const;

返回场景中的地理参考系统 Actor，启用地理放置时由插件自动创建。

ALCCGeoReferencingSystem* GeoSystem = Component->GetGeoReferencingSystem();
if (GeoSystem)
{
    // 投影坐标转引擎坐标
    FVector EngineLocation;
    GeoSystem->ProjectedToEngine(ProjectedCoord, EngineLocation);

    // 取该点的东/北/天方向
    FVector East, North, Up;
    GeoSystem->GetENUVectorsAtEngineLocation(EngineLocation, East, North, Up);
}

Multi-Viewport

同一份数据可以为不同摄像机设置不同的渲染策略，典型用途是主视口跑 3DGS 高画质、小地图用 SceneCapture 渲染点云俯视图。

注：这组接口只适用于 LCC1 管线。在 LCC2 管线（ALCC2Actor 以及 .sog / .spz / .ply）上调用不报错，但达不到预期效果。需要多视口差异化渲染或传送预加载时请使用 LCC1 数据。

接受的是对象指针，不是整数 ID。

多机位、多屏输出的整体方案（nDisplay、Aximmetry、Pixotope 等）见第三方与引擎插件集成。

SetPlayerLoadMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPlayerLoadMode(class APlayerController* PlayerController, ELoadMode InLoadMode);

为指定玩家控制器单独设置 LoadMode，下一帧生效。

APlayerController* PC2 = UGameplayStatics::GetPlayerController(GetWorld(), 1);
Component->SetPlayerLoadMode(PC2, ELoadMode::OnlyMain);

SetPlayerRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetPlayerRenderMode(class APlayerController* PlayerController, ERenderMode InRenderMode);

为指定玩家控制器单独设置 RenderMode，下一帧生效。

SetSceneCaptureLoadMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSceneCaptureLoadMode(class USceneCaptureComponent2D* InCapture2D, ELoadMode InLoadMode);

为指定 SceneCapture 单独设置 LoadMode。

需要先在项目设置里打开 SceneCaptureComponent Support，否则 SceneCapture 里不会渲染 LCC 内容。

SetSceneCaptureRenderMode

UFUNCTION(BlueprintCallable, Category = "XGrids")
void SetSceneCaptureRenderMode(class USceneCaptureComponent2D* InCapture2D, ERenderMode InRenderMode);

为指定 SceneCapture 单独设置 RenderMode。

// 小地图用点云 + 只要主体，开销最小
Component->SetSceneCaptureRenderMode(MinimapCapture, ERenderMode::PointCloud);
Component->SetSceneCaptureLoadMode(MinimapCapture, ELoadMode::OnlyMain);

ModifyPlayerTransform

UFUNCTION(BlueprintCallable, Category = "XGrids")
void ModifyPlayerTransform(class APlayerController* PlayerController, FTransform InTransform);

覆盖指定玩家在本场景中的位置，用于传送前预加载目标点的数据。

要解决的问题：直接传送到远处时目标点节点还没加载，玩家会看到主体一片空白然后逐渐补齐。

正确时序：

ModifyPlayerTransform(目的地)
        ↓ 等 0.2 秒左右，让目的地节点开始加载
实际传送玩家
        ↓ 再等 0.2 秒左右
CancelModifyPlayerTransform

void AMyTeleporter::TeleportWithPreload(APlayerController* PC, const FTransform& Destination)
{
    Component->ModifyPlayerTransform(PC, Destination);

    FTimerHandle Handle;
    GetWorld()->GetTimerManager().SetTimer(Handle,
        [this, PC, Destination]()
        {
            PC->GetPawn()->SetActorTransform(Destination);

            FTimerHandle CancelHandle;
            GetWorld()->GetTimerManager().SetTimer(CancelHandle,
                [this, PC]()
                {
                    Component->CancelModifyPlayerTransform(PC);
                },
                0.2f, false);
        },
        0.2f, false);
}

文本蓝图：

[Custom Event: TeleportTo]
        Destination (Transform)
        │
        ▼
[Modify Player Transform]
        Target = (LCC Component)
        Player Controller = Get Player Controller
        In Transform = Destination
        │
        ▼
[Delay]  Duration = 0.2
        │
        ▼
[Set Actor Transform]
        Target = Get Player Pawn
        New Transform = Destination
        │
        ▼
[Delay]  Duration = 0.2
        │
        ▼
[Cancel Modify Player Transform]
        Target = (LCC Component)
        Player Controller = Get Player Controller

CancelModifyPlayerTransform

UFUNCTION(BlueprintCallable, Category = "XGrids")
void CancelModifyPlayerTransform(class APlayerController* PlayerController);

取消位置覆盖，恢复使用玩家实时位置。

必须调用，否则该玩家的节点调度会一直停在覆盖位置上，移动时不再加载新节点。

Clipping and Section

裁剪与剖切的使用方法见场景编辑，以及 ALCCClippingVolume、ALCCSectionPlane。

AddClippingVolume

UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddClippingVolume(ALCCClippingVolume* InClippingVolume);

添加裁剪体。

ALCCClippingVolume* Volume = GetWorld()->SpawnActor<ALCCClippingVolume>(
    ALCCClippingVolume::StaticClass(), Location, FRotator::ZeroRotator);

Volume->VolumeType = EClipVolumeType::Box;
Volume->Mode = EClipType::Inside;
Volume->bEnabled = true;

Component->AddClippingVolume(Volume);

RemoveClippingVolume

UFUNCTION(BlueprintCallable, Category = "XGrids")
void RemoveClippingVolume(ALCCClippingVolume* InClippingVolume);

移除裁剪体。只是临时停用的话，改裁剪体的 bEnabled 更轻量。

AddSectionPlane

UFUNCTION(BlueprintCallable, Category = "XGrids")
void AddSectionPlane(ALCCSectionPlane* InSectionPlane);

添加剖切面。

RemoveSectionPlane

UFUNCTION(BlueprintCallable, Category = "XGrids")
void RemoveSectionPlane(ALCCSectionPlane* InSectionPlane);

移除剖切面。

Loading Animation

SetEnableAnimation / GetEnableAnimation

UFUNCTION(BlueprintCallable, Category = "XGrids|Animation")
void SetEnableAnimation(bool bInEnableAnimation);

UFUNCTION(BlueprintPure, Category = "XGrids|Animation")
bool GetEnableAnimation() const;

开关动画，同时把动画计时起点重设为当前时间。因此它不限于加载阶段，任何时刻调用都会让动画从头播一遍。

各阶段的参数直接设属性，没有单独的 Setter。想让参数完整作用于整段动画，先设参数再调这个函数。播放中改参数也生效，属于中途调整。

Component->AnimationSpeed = 30.0f;
Component->SecondStageDelay = 1.0f;
Component->SetEnableAnimation(true);

反向（消失）动画、调用顺序、参数取值与实践要点见加载动画。