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);

反向（消失）動畫、調用順序、參數取值與實踐要點見加載動畫。