EggyUnit

概览

字段	值
Kind	`Unit` · 单位 Unit
Realm	`common`

继承关系

Unit（4 属性 / 25 函数 / 6 事件）
- SpaceUnit（2 属性 / 9 函数）
  - [EggyUnit]（12 属性 / 12 函数）

继承成员

2 个来源 / 6 属性 / 34 函数 / 6 事件

来自 SpaceUnit（2 属性 / 9 函数）
- 属性：Tags、EcaPath
- 函数：HasTag、AddTag、RemoveTag、GetPivot、PivotTo、ApplyPivotDelta、TranslateBy、IsTopLevel、FindTopLevel
来自 Unit（4 属性 / 25 函数 / 6 事件）
- 属性：AssetId、Name、Desc、Parent
- 函数：ClearAllChildren、GetChildren、GetDescendants、IsAncestorOf、IsDescendantOf、FindFirstAncestor、FindFirstAncestorWhichIsA、FindFirstAncestorOfClass、FindFirstChild、FindFirstChildWhichIsA、FindFirstChildOfClass、HasChildren、GetChildCount、GetChildAtIndex、SetAttribute、GetAttribute、GetAllProps、Clone、IsA、Destroy、GetPropertyChangedSignal、GetAttributeChangedSignal、FindFromPath、GetFullPath、GetDebugId
- 事件：ChildAdded、ChildRemoved、DescendantAdded、DescendantRemoving、AncestryChanged、Destroying

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

适用场景

创建玩家角色或 NPC 时配置位置、朝向和控制器；需要换装时通过 EggyAppearance 修改蛋形外观，或把 CustomAppearanceService 返回的运行时外观 ID 应用到 CustomAppearanceId。

使用要点

通过 World:CreateUnit("EggyUnit", config) 创建实例；EnableController=true 时可从 Controller 属性取得控制器。应用运行时自定义外观时，先由 CustomAppearanceService 取得外观 ID 字符串，再设置 UseCustomAppearance=true 和 CustomAppearanceId=appearanceId。

注意事项

创建单位应使用 World:CreateUnit，不使用 game:CreateUnit。EggyAppearance 用于蛋形换装接口；CustomAppearanceId 只有在 UseCustomAppearance=true 时生效。访问控制器前应确认 Controller 非 nil。

代码示例

创建蛋仔并启用控制器

lua

-- @runtime client
local world = game:GetService("World")
local eggy = world:CreateUnit("EggyUnit", {
    Name = "TrainingEggy",
    Position = Vector3.New(0, 0, 0),
    EnableController = true,
})
if eggy ~= nil and eggy.Controller ~= nil then
    eggy.Controller:Jump()
end

应用运行时自定义外观

lua

-- @runtime client
local world = game:GetService("World")
local appearances = game:GetService("CustomAppearanceService")
-- 客户端创建的运行时外观仅本端可见；需全端同步时请在服务端执行同一流程
local appearanceId = appearances:CreateCustomAppearance({ Name = "TrainingAppearance" })
local eggy = world:CreateUnit("EggyUnit", { Position = Vector3.New(0, 0, 0) })
if appearanceId ~= nil and appearanceId ~= "" and eggy ~= nil then
    eggy.UseCustomAppearance = true
    eggy.CustomAppearanceId = appearanceId
end

属性 (12)

Name	类型	默认值	说明
`Position`	Vector3	`[0.0, 0.0, 0.0]`	EggyUnit 的位置属性，类型为 Vector3，默认为 (0, 0, 0)，可读可写。
`Rotation`	Quaternion	`[0.0, 0.0, 0.0, 1.0]`	EggyUnit 的旋转属性，类型为 Quaternion，默认为 (0, 0, 0, 1)，可读可写。
`Scale`	Vector3	`[1.0, 1.0, 1.0]`	EggyUnit 的缩放属性，类型为 Vector3，默认为 (1, 1, 1)，可读可写。
`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 字符串。

关联类型

函数 (12)

AddCollisionWithGroup

签名：AddCollisionWithGroup(groupName: String) -> void

动态添加本单位与指定已注册碰撞组的碰撞关系，允许本单位与该目标组发生碰撞；不是把本单位加入该组。

⚙ groupName 使用已注册组名称字符串；GetCollisionWithGroups 返回允许碰撞的目标组。本例仅操作本端自建单位，PhysicsService 只读取当前已注册组，不注册、删除或修改全局组配置。需要全端同步时，应由服务端执行相同的公开获取与调用链。完成或异常后均 Destroy 自有实例；不对真实玩家或既有地图对象做清理。本例创建时显式设置 EnableController=true，并在调用前确认公开 Controller 非 nil；控制器未就绪时报错并清理自有单位，不猜测等待时间，也不以缺方法或前置不满足的早退代替成功。

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

返回值 void

示例代码

添加与已注册目标组的碰撞关系

lua

-- @runtime client
local World = game:GetService("World")
local PhysicsService = game:GetService("PhysicsService")

-- 只使用当前已注册组；不虚构组名，也不注册、删除或修改全局碰撞组。
local groupName = PhysicsService:GetRegisteredCollisionGroups()[1]
if type(groupName) ~= "string" or groupName == "" then
    print("没有可用的已注册碰撞组，请先完成地图的碰撞组配置")
    return
end

-- World:CreateUnit 将自有示例单位挂到 World；不改变玩家角色或既有地图对象。
local eggy = World:CreateUnit("EggyUnit", { Name = "CollisionRelationDemo", EnableController = true })
if eggy == nil then return end

local ok, err = pcall(function()
    assert(eggy.Controller ~= nil, "自建 EggyUnit 控制器未就绪，请核对创建配置和运行环境")
    eggy:AddCollisionWithGroup(groupName)
    print("允许碰撞的目标组:", table.concat(eggy:GetCollisionWithGroups(), ", "))
end)
-- 只清理本例创建的单位；方法异常时也先释放自有资源。
eggy:Destroy()
if not ok then error(err) end

RemoveCollisionWithGroup

签名：RemoveCollisionWithGroup(groupName: String) -> void

动态移除本单位与指定碰撞组的碰撞关系；不是移除本单位的所属组。

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

返回值 void

示例代码

添加后移除与已注册目标组的碰撞关系

lua

-- @runtime client
local World = game:GetService("World")
local PhysicsService = game:GetService("PhysicsService")

-- 只使用当前已注册组；不虚构组名，也不注册、删除或修改全局碰撞组。
local groupName = PhysicsService:GetRegisteredCollisionGroups()[1]
if type(groupName) ~= "string" or groupName == "" then
    print("没有可用的已注册碰撞组，请先完成地图的碰撞组配置")
    return
end

-- World:CreateUnit 将自有示例单位挂到 World；不改变玩家角色或既有地图对象。
local eggy = World:CreateUnit("EggyUnit", { Name = "CollisionRelationDemo", EnableController = true })
if eggy == nil then return end

local ok, err = pcall(function()
    assert(eggy.Controller ~= nil, "自建 EggyUnit 控制器未就绪，请核对创建配置和运行环境")
    eggy:AddCollisionWithGroup(groupName)
    eggy:RemoveCollisionWithGroup(groupName)
    print("允许碰撞的目标组:", table.concat(eggy:GetCollisionWithGroups(), ", "))
end)
-- 只清理本例创建的单位；方法异常时也先释放自有资源。
eggy:Destroy()
if not ok then error(err) end

GetCollisionWithGroups

签名：GetCollisionWithGroups() -> Array<String>

获取本单位当前允许碰撞的目标组名称列表，返回 Array<String>；该列表不是本单位的所属组。

返回值 Array<String>

示例代码

读取允许碰撞的目标组名称列表

lua

-- @runtime client
local World = game:GetService("World")
local PhysicsService = game:GetService("PhysicsService")

-- 只使用当前已注册组；不虚构组名，也不注册、删除或修改全局碰撞组。
local groupName = PhysicsService:GetRegisteredCollisionGroups()[1]
if type(groupName) ~= "string" or groupName == "" then
    print("没有可用的已注册碰撞组，请先完成地图的碰撞组配置")
    return
end

-- World:CreateUnit 将自有示例单位挂到 World；不改变玩家角色或既有地图对象。
local eggy = World:CreateUnit("EggyUnit", { Name = "CollisionRelationDemo", EnableController = true })
if eggy == nil then return end

local ok, err = pcall(function()
    assert(eggy.Controller ~= nil, "自建 EggyUnit 控制器未就绪，请核对创建配置和运行环境")
    eggy:AddCollisionWithGroup(groupName)
    -- 返回允许碰撞的目标组名称，不是本单位的所属组。
    for _, targetGroup in ipairs(eggy:GetCollisionWithGroups()) do
        print("允许碰撞的目标组:", targetGroup)
    end
end)
-- 只清理本例创建的单位；方法异常时也先释放自有资源。
eggy:Destroy()
if not ok then error(err) end

SetNetworkOwner

签名：SetNetworkOwner(player: Player) -> void

把该 EggyUnit 的网络拥有者设置为指定的 Player，由该玩家负责此单位的网络同步。

参数	类型	说明
`player`	Player	玩家

返回值 void

示例代码

设置蛋仔网络拥有者

lua

-- @runtime server
local Players = game:GetService("Players")
local World = game:GetService("World")

local player = Players:GetPlayers()[1]
local eggy = World:CreateUnit("EggyUnit", { Position = Vector3.New(0, 0, 0) })
if player ~= nil and eggy ~= nil then
    eggy:SetNetworkOwner(player)
end

GetNetworkOwner

签名：GetNetworkOwner() -> Player (网络拥有者；没有明确所有者时可能没有有效结果)

获取该 EggyUnit 当前的网络拥有者，返回一个 Player 对象。

返回值 Player (网络拥有者；没有明确所有者时可能没有有效结果)

示例代码

读取蛋仔网络拥有者

lua

-- @runtime server
local World = game:GetService("World")

local eggy = World:CreateUnit("EggyUnit", { Position = Vector3.New(0, 0, 0) })
local owner = eggy:GetNetworkOwner()
if owner ~= nil then
    print("网络拥有者:", owner:GetName())
end

GetPosition

签名：GetPosition() -> Vector3 (位置)

获取 EggyUnit 当前的位置，返回类型为 Vector3。

返回值 Vector3 (位置)

示例代码

读取蛋仔位置

lua

-- @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) -> void

设置 EggyUnit 的位置，参数为 Vector3 类型的 pos，无返回值。

⚙ 传入 Vector3 世界坐标；可用 GetPosition() 读取设置后的值。

参数	类型	说明
`pos`	Vector3	坐标

返回值 void

示例代码

设置蛋仔位置

lua

-- @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 (旋转)

获取 EggyUnit 当前的旋转，返回类型为 Quaternion（四元数）。

返回值 Quaternion (旋转)

示例代码

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

lua

-- @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) -> void

设置 EggyUnit 的旋转，参数为 Quaternion 类型的 rotation，无返回值。

⚙ Quaternion.FromEulerAngles 使用点语法，三个参数按公开签名传入弧度。

参数	类型	说明
`rotation`	Quaternion	旋转

返回值 void

示例代码

把蛋仔绕 Y 轴旋转 90 度

lua

-- @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 (缩放)

获取 EggyUnit 当前的缩放，返回类型为 Vector3。

返回值 Vector3 (缩放)

示例代码

读取蛋仔缩放

lua

-- @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) -> void

设置 EggyUnit 的缩放，参数为 Vector3 类型的 scale，无返回值。

⚙ 传入 Vector3 三轴缩放值；可用 GetScale() 读取设置后的值。

参数	类型	说明
`scale`	Vector3	缩放

返回值 void

示例代码

设置蛋仔缩放

lua

-- @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朝向)

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

⚙ 返回当前 Yaw 朝向；当前 Meta 未标注角度单位，显示或换算前应以目标运行包约定为准。

返回值 Float (Yaw朝向)

示例代码

读取蛋仔 Yaw 朝向

lua

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

技能资源包

基础教程

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

数据

枚举

服务

单位

枚举 Enum

数据 Data

服务 Service

单位 Unit

EggyUnit

概览

继承关系

继承成员

适用场景

使用要点

注意事项

代码示例

创建蛋仔并启用控制器

应用运行时自定义外观

属性 (12)

关联类型

函数 (12)

AddCollisionWithGroup

RemoveCollisionWithGroup

GetCollisionWithGroups

SetNetworkOwner

GetNetworkOwner

GetPosition

SetPosition

GetRotation

SetRotation

GetScale

SetScale

GetYaw

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

EggyUnit ​

概览 ​

继承关系 ​

继承成员 ​

适用场景 ​

使用要点 ​

注意事项 ​

代码示例 ​

创建蛋仔并启用控制器 ​

应用运行时自定义外观 ​

属性 (12) ​

关联类型 ​

函数 (12) ​

AddCollisionWithGroup ​

RemoveCollisionWithGroup ​

GetCollisionWithGroups ​

SetNetworkOwner ​

GetNetworkOwner ​

GetPosition ​

SetPosition ​

GetRotation ​

SetRotation ​

GetScale ​

SetScale ​

GetYaw ​

EggyUnit

概览

继承关系

继承成员

适用场景

使用要点

注意事项

代码示例

创建蛋仔并启用控制器

应用运行时自定义外观

属性 (12)

关联类型

函数 (12)

AddCollisionWithGroup

RemoveCollisionWithGroup

GetCollisionWithGroups

SetNetworkOwner

GetNetworkOwner

GetPosition

SetPosition

GetRotation

SetRotation

GetScale

SetScale

GetYaw