EggyUnit

EggyUnit 是场景中的蛋形生物角色，可由玩家操控，也可作为怪物或 NPC。它提供空间变换、网络所有权、控制器以及蛋形外观和运行时自定义外观的接入能力。

概览

EggyUnit 是场景中的蛋形生物角色，可由玩家操控，也可作为怪物或 NPC。它提供空间变换、网络所有权、控制器以及蛋形外观和运行时自定义外观的接入能力。

继承自 SpaceUnit；可通过 World:CreateUnit("EggyUnit", ...) 创建；返回单个单位

函数

AddCollisionWithGroup

签名：AddCollisionWithGroup(groupName: String)

动态添加本单位与指定目标碰撞组的碰撞关系；不会把单位本身改成属于该组。目标组名称应来自已经配置好的碰撞关系，不猜测组名。

注意： 示例只从自建 EggyUnit 的已有允许碰撞列表选取目标组，不注册或修改全局组规则。列表为空时请先准备已有碰撞目标配置的测试地图，早退不代表添加行为通过；操作结束销毁自有实例。 本例创建时显式设置 EnableController=true，并在调用前确认公开 Controller 非 nil；控制器未就绪时报错并清理自有单位，不猜测等待时间，也不以缺方法或前置不满足的早退代替成功。

参数	类型	说明
groupName	String	碰撞组名

给自有蛋仔恢复一个已有的允许碰撞目标组

-- @runtime client
local world = game:GetService('World')
local eggy = world:CreateUnit('EggyUnit', { EnableController = true })
if eggy == nil then return end
local ok, err = pcall(function()
    assert(eggy.Controller ~= nil, "自建 EggyUnit 控制器未就绪，请核对创建配置和运行环境")
    local groups = eggy:GetCollisionWithGroups()
    local groupName = groups[1]
    if type(groupName) ~= 'string' or groupName == '' then
        print('请准备已有允许碰撞目标组的测试地图；本次未验证添加')
        return
    end
    eggy:RemoveCollisionWithGroup(groupName)
    eggy:AddCollisionWithGroup(groupName)
    local found = false
    for _, name in ipairs(eggy:GetCollisionWithGroups()) do
        if name == groupName then found = true end
    end
    assert(found, '允许碰撞目标组未添加')
    print('已恢复允许碰撞目标组:', groupName)
end)
eggy:Destroy()
if not ok then error(err) end

RemoveCollisionWithGroup

签名：RemoveCollisionWithGroup(groupName: String)

动态移除本单位与指定目标碰撞组的碰撞关系；不会删除全局碰撞组，也不改变其它单位的配置。

注意： 只操作自建 EggyUnit 中已经存在的允许碰撞目标，移除后读回列表并恢复原关系，最后销毁自有实例；列表为空时需要已配夹具，不能把早退视作删除效果通过。 本例创建时显式设置 EnableController=true，并在调用前确认公开 Controller 非 nil；控制器未就绪时报错并清理自有单位，不猜测等待时间，也不以缺方法或前置不满足的早退代替成功。

参数	类型	说明
groupName	String	碰撞组名

移除并恢复自有蛋仔的一个已有碰撞目标

-- @runtime client
local world = game:GetService('World')
local eggy = world:CreateUnit('EggyUnit', { EnableController = true })
if eggy == nil then return end
local ok, err = pcall(function()
    assert(eggy.Controller ~= nil, "自建 EggyUnit 控制器未就绪，请核对创建配置和运行环境")
    local groups = eggy:GetCollisionWithGroups()
    local groupName = groups[1]
    if type(groupName) ~= 'string' or groupName == '' then
        print('请准备已有允许碰撞目标组的测试地图；本次未验证移除')
        return
    end
    eggy:RemoveCollisionWithGroup(groupName)
    local found = false
    for _, name in ipairs(eggy:GetCollisionWithGroups()) do
        if name == groupName then found = true end
    end
    assert(not found, '允许碰撞目标组未移除')
    print('已移除允许碰撞目标组:', groupName)
    eggy:AddCollisionWithGroup(groupName)  -- 恢复自有实例的原关系
end)
eggy:Destroy()
if not ok then error(err) end

GetCollisionWithGroups

签名：GetCollisionWithGroups() -> Array

读取本单位当前允许发生碰撞的目标组名称列表，返回 String 数组；该列表不是单位自身所属组的列表。

注意： 空列表是合法查询结果，只表示没有配置允许碰撞目标，不能据此声称已验证一次添加或移除。示例不注册新组，只读取自建单位并在结束后销毁。

返回值 Array

查询自有蛋仔允许碰撞的目标组列表

-- @runtime client
local world = game:GetService('World')
local eggy = world:CreateUnit('EggyUnit', {})
if eggy == nil then return end
local ok, err = pcall(function()
    local groups = eggy:GetCollisionWithGroups()
    print('允许碰撞目标组数量:', #groups)
    for index, groupName in ipairs(groups) do
        print(index, groupName)
    end
end)
eggy:Destroy()
if not ok then error(err) end

SetNetworkOwner

签名：SetNetworkOwner(player: Player)

设置该 EggyUnit 的网络拥有者。需要传入一个 Player 类型的参数 player，无返回值。

注意： 该网络所有权能力属于服务端运行时，且当前 Editor Surface 不公开 Players 服务或其它稳定 Player 获取链；不要在 Editor 示例中编造 game/editor:GetService("Players")。

参数	类型	说明
player	Player	玩家

GetNetworkOwner

签名：GetNetworkOwner() -> Player

获取该 EggyUnit 的网络拥有者。方法无参数，返回值为 Player 类型，表示当前拥有该蛋形生物网络控制权的玩家。

注意： 该网络所有权能力属于服务端运行时。Editor Lua 只保留公开签名，不提供可运行示例。

返回值 Player

GetPosition

签名：GetPosition() -> Vector3

获取蛋形生物单位当前的位置。

返回值 Vector3

读取蛋仔位置

-- @runtime client
local world = game:GetService("World")
local eggy = world:CreateUnit("EggyUnit", { Position = Vector3.New(10, 5, 20) })
if eggy ~= nil then
    local position = eggy:GetPosition()
    print("当前位置:", position.x, position.y, position.z)
end

SetPosition

签名：SetPosition(pos: Vector3)

将 EggyUnit 实例的位置设置为传入的世界坐标。该方法接收一个 Vector3 参数 pos，用于指定目标位置。

参数	类型	说明
pos	Vector3	坐标

设置蛋仔位置

-- @runtime client
local world = game:GetService("World")
local eggy = world:CreateUnit("EggyUnit", {})
if eggy ~= nil then
    eggy:SetPosition(Vector3.New(10, 5, 20))
    print("当前位置:", eggy:GetPosition())
end

GetRotation

签名：GetRotation() -> Quaternion

获取蛋形生物单位当前的旋转。

返回值 Quaternion

读取蛋仔旋转的四元数分量

-- @runtime client
local World = game:GetService("World")
local eggy = World:CreateUnit("EggyUnit", { Position = Vector3.New(0, 0, 0) })
if eggy == nil then return end
local rotation = eggy:GetRotation()
print("四元数分量:", rotation.x, rotation.y, rotation.z, rotation.w)

SetRotation

签名：SetRotation(rotation: Quaternion)

设置蛋形生物单位的旋转。

参数	类型	说明
rotation	Quaternion	旋转

把蛋仔绕 Y 轴旋转 90 度

-- @runtime client
local World = game:GetService("World")
local eggy = World:CreateUnit("EggyUnit", { Position = Vector3.New(0, 0, 0) })
if eggy == nil then return end
eggy:SetRotation(Quaternion.FromEulerAngles(0, math.rad(90), 0))
print("旋转后的四元数:", eggy:GetRotation())

GetScale

签名：GetScale() -> Vector3

获取蛋形生物单位当前的缩放。

返回值 Vector3

读取蛋仔缩放

-- @runtime client
local world = game:GetService("World")
local eggy = world:CreateUnit("EggyUnit", { Scale = Vector3.New(1, 1, 1) })
if eggy ~= nil then
    local scale = eggy:GetScale()
    print("当前缩放:", scale.x, scale.y, scale.z)
end

SetScale

签名：SetScale(scale: Vector3)

SetScale 是 EggyUnit 提供的实例方法，用于设置该蛋仔单位的整体缩放。调用时需要传入一个 Vector3 类型的 scale 参数，方法按该向量对单位进行缩放，且没有返回值。

参数	类型	说明
scale	Vector3	缩放

设置蛋仔缩放

-- @runtime client
local World = game:GetService("World")
local eggy = World:CreateUnit("EggyUnit", { Scale = Vector3.New(1, 1, 1) })
if eggy == nil then return end
eggy:SetScale(Vector3.New(1.2, 1.2, 1.2))
print("当前缩放:", eggy:GetScale())

GetYaw

签名：GetYaw() -> Float

获取蛋形生物单位的 Yaw 朝向。

返回值 Float

读取蛋仔 Yaw 朝向

-- @runtime client
local world = game:GetService("World")
local eggy = world:CreateUnit("EggyUnit", {})
if eggy ~= nil then
    print("当前 Yaw:", eggy:GetYaw())
end

属性

名称	类型	默认值	说明
Position	Vector3	[0.0, 0.0, 0.0]	蛋形生物单位在世界中的位置，类型为 Vector3。
Rotation	Quaternion	[0.0, 0.0, 0.0, 1.0]	蛋形生物单位的旋转，类型为 Quaternion。
Scale	Vector3	[1.0, 1.0, 1.0]	蛋形生物单位的缩放，类型为 Vector3。
Visible	Bool	true	蛋形生物单位的可见性开关，类型为 Bool。
EnableAppearance	Bool	true	控制蛋形生物单位是否使用蛋形外观的开关，类型为 Bool。
Controller	EggyController	-	EggyUnit 的蛋形生物控制器属性，类型为 EggyController，用于访问该蛋形生物对应的控制器对象。
EnableController	Bool	false	表示该蛋形生物单位是否创建 Controller（控制器），类型为 Bool。
EggyAppearance	EggyAppearance	{}	蛋形生物的外观组件；通过其公开方法设置预设、时装、配饰、脸型、动态表情、肤色和蛋皮。
RenderMeshId	String	official://mesh/9000001	蛋形生物渲染所使用的模型资源 ID，类型为 String。
Animator	Animator	-	该蛋仔单位关联的动画控制器对象；从 EggyUnit.Animator 直接读取，不自行赋值。
UseCustomAppearance	Bool	false	是否启用 CustomAppearanceId 指定的自定义外观；设为 true 后 CustomAppearanceId 才生效。
CustomAppearanceId	String	""	自定义外观 ID；与 UseCustomAppearance=true 配合使用，可直接填写 CustomAppearanceService 返回的 ID 字符串。