XCEngine/docs/api/XCEngine/Components/GameObject/SetLayer.md

GameObject::SetLayer

设置当前对象的 layer。

void SetLayer(uint8_t layer);

行为说明

当前 native 实现等价于：

m_layer = std::min<uint8_t>(layer, 31u);

因此对 C++ 调用者来说，精确语义是：

• 参数类型本身就是 uint8_t
• 0..31 会原样保留
• 大于 31 的值会被写成 31

原生与托管的差异

很多文档会把它简写成“clamp 到 [0, 31]”。这对托管调用链是正确的，但对原生头文件还不够精确：

• 原生公开 API 没有负数输入通道，因为参数已经是 uint8_t
• 托管 GameObject.layer / Component.layer 先在 internal call 里把 int32 显式限制到 [0, 31]
• 然后托管层再调用这个 native setter

所以：

• C++ 视角：这是“uint8_t + 上界 clamp”
• C# 视角：这是完整的 [0, 31] clamp

参数

• layer - 目标 layer 值。

返回值

• 无。

设计提示

把 layer 收敛为 0..31 的轻量整数，可以让渲染过滤、对象分类、脚本暴露与场景序列化共享同一套最小稳定模型，而不必提前引入更重的 LayerMask 资产系统。

相关文档

• GameObject
• GetLayer
• Serialize