EggyUnit

概览

字段	值
Kind	Unit · 单位 Unit
Realm	common

继承关系

• Unit（4 属性 / 25 函数 / 6 事件）
  • SpaceUnit（3 属性 / 9 函数）
    • [EggyUnit]（11 属性 / 9 函数）

继承成员

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

• 来自 SpaceUnit（3 属性 / 9 函数）
  • 属性：Tags、EcaPath、Owner
  • 函数：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。

代码示例

创建蛋仔并启用控制器

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

应用运行时自定义外观

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

属性 (11)

Name	类型	默认值	说明
Position	Vector3	[0.0, 0.0, 0.0]	蛋形生物在世界空间中的位置。
Rotation	Quaternion	[0.0, 0.0, 0.0, 1.0]	EggyUnit 的旋转四元数属性，可读写。
Scale	Vector3	[1.0, 1.0, 1.0]	蛋形生物的缩放比例。
Visible	Bool	true	蛋形生物的可见性。
EnableAppearance	Bool	true	是否使用蛋形外观渲染该蛋形单元。
Controller	EggyController	-	蛋形生物控制器实例，提供蛋形生物的移动、跳跃、冲撞、投掷等行为控制能力。
EnableController	Bool	false	是否在创建时自动启用控制器。
EggyAppearance	EggyAppearance	{}	蛋形生物的外观组件；通过其公开方法设置预设、时装、配饰、脸型、动态表情、肤色和蛋皮。
RenderMeshId	String	official://mesh/9000001	蛋形单元使用的模型资源 ID，用于指定该单元的网格渲染资源。
UseCustomAppearance	Bool	false	是否启用 CustomAppearanceId 指定的自定义外观；设为 true 后 CustomAppearanceId 才生效。
CustomAppearanceId	String	""	自定义外观 ID；与 UseCustomAppearance=true 配合使用，可直接填写 CustomAppearanceService 返回的 ID 字符串。

关联类型

• SpaceUnit
• EggyAppearance
• EggyController
• Quaternion
• Vector3

函数 (9)

SetNetworkOwner

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

为蛋形生物单元设置网络拥有者，将指定玩家绑定为该单元的网络控制方。

参数	类型	说明
player	Player	玩家

返回值 void

示例代码

设置蛋仔网络拥有者

-- @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 (网络拥有者；没有明确所有者时可能没有有效结果)

获取蛋形生物单元当前指定的网络拥有者。网络拥有者是对该单元拥有网络控制权的玩家。

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

示例代码

读取蛋仔网络拥有者

-- @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 (位置)

示例代码

读取蛋仔位置

-- @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 世界坐标；可用 GetPosition() 读取设置后的值。

参数	类型	说明
pos	Vector3	坐标

返回值 void

示例代码

设置蛋仔位置

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

示例代码

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

-- @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.FromEulerAngles 使用点语法，三个参数按公开签名传入弧度。

参数	类型	说明
rotation	Quaternion	旋转

返回值 void

示例代码

把蛋仔绕 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 (缩放)

返回当前 EggyUnit 的缩放比例。

返回值 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) -> void

设置 EggyUnit 实例的缩放比例。

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

参数	类型	说明
scale	Vector3	缩放

返回值 void

示例代码

设置蛋仔缩放

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

返回当前 EggyUnit 绕世界 Y 轴的旋转角度（Yaw）。

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

返回值 Float (Yaw朝向)

示例代码

读取蛋仔 Yaw 朝向

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