EggyAppearance

概览

字段	值
Kind	`Data` · 数据 Data
Realm	`common`

蛋形生物的外观数据，用于描述蛋仔的盲盒外观、染色、时装散件、配饰、脸型、表情、肤色与蛋皮等可换装信息。它同时提供运行时换装、将外观件挂接到骨骼插槽、以及显示头顶气泡与表情等表现能力，是角色外观表现的核心数据对象。

适用场景

当需要让角色瞬时切换整套外观（例如按资源编号换装后复位），或对已装配的时装散件、配饰、脸型、肤色、蛋皮做单项替换与读取时使用。也可用于给角色加上头顶气泡提示，或在外观件挂接后按绑定编号单独解绑。

使用要点

该对象不可自行构造，需从公开对象获取实例后再调用其函数。常见顺序是先通过 SetAppearanceByAssetId 或 ResetAppearance 切换整套外观，再用 SetFashionPart、SetAccessoryId、SetFaceId、SetSkinColorId、SetEggShellId 做单项替换，配套的 GetFashionPart、GetAccessoryId、GetFaceId、GetFaceStatus、GetSkinColorId、GetEggShellId 用于读取当前值。若要挂接外观件，调用 BindAppearance 并保存其返回的绑定编号，后续用 UnbindAppearance 精确解绑，或用 ResetBindAppearance 整体清理；气泡方面先用 EnableBubbleMessage 开启，再以 ShowBubbleMessage、HideBubbleMessage 控制显示。

注意事项

EggyAppearance 不能使用 New 或直接构造，必须从 EggyUnit 等公开对象获取。传入的预设、外观件和装扮 ID 必须来自项目实际可用资源；BindAppearance 成功后应保存返回的绑定 ID，供 UnbindAppearance 精确解绑或 ResetBindAppearance 整体清理。

代码示例

获取角色外观组件并显示气泡

lua

-- @runtime client
local players = game:GetService("Players")
local player = players.LocalPlayer
if player == nil then return end
local character = player and player.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local appearance = character.EggyAppearance
    appearance:ShowBubbleMessage("准备出发", 2.0, 20.0)
    appearance:SetFaceStatus(Enums.FaceStatus.Happy)
end

函数 (20)

ShowBubbleMessage

签名：ShowBubbleMessage(message: String, duration: Float, hideDistance?: Float) -> void

在角色头顶显示一段文字气泡消息，消息会持续展示指定的时长后消失。

参数	类型	说明
`message`	`String`	气泡消息
`duration`	`Float`	持续时间(可选)
`hideDistance?`	`Float`	隐藏距离(可选)

返回值 void

示例代码

显示头顶气泡消息

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:ShowBubbleMessage("跟我来", 2.0, 20.0)
end

HideBubbleMessage

签名：HideBubbleMessage() -> void

隐藏当前正在显示的头顶气泡消息。

返回值 void

示例代码

隐藏头顶气泡消息

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:HideBubbleMessage()
end

SetAppearanceByAssetId

签名：SetAppearanceByAssetId(assetId: String) -> void

按生物预设整体切换角色的外观。

参数	类型	说明
`assetId`	`String`	生物预设ID

返回值 void

示例代码

切换整套蛋仔外观

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:SetAppearanceByAssetId("official://preset/9000602")
end

ResetAppearance

签名：ResetAppearance() -> void

重置角色的时装和模型外观，将此前对外观所做的更换还原为默认外观。

返回值 void

示例代码

恢复默认外观

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:ResetAppearance()
end

BindAppearance

签名：BindAppearance(appearanceId: String, socket: SkeletalSocketType, offset: Vector3, rot: Quaternion, scale: Vector3) -> Int (绑定ID)

在 EggyAppearance 实例上挂接一个外观件：通过外观标识字符串把外观件绑定到角色指定的骨骼挂点，并同时指定该外观件相对挂点的位置偏移、旋转与缩放，调用完成后返回一个整数绑定 ID 用于标识这次绑定。

参数	类型	说明
`appearanceId`	`String`	外观ID
`socket`	SkeletalSocketType	绑定点
`offset`	Vector3	位置偏移
`rot`	Quaternion	旋转
`scale`	Vector3	缩放

返回值 Int (绑定ID)

示例代码

挂接一个外观件

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local bindId = character.EggyAppearance:BindAppearance(
        "official://preset/101123",
        Enums.SkeletalSocketType.Head,
        Vector3.New(0, 0.2, 0),
        Quaternion.New(0, 0, 0, 1),
        Vector3.New(1, 1, 1)
    )
    print("外观挂接 ID:", bindId)
end

UnbindAppearance

签名：UnbindAppearance(bindId: Int) -> Bool (是否成功)

解除指定绑定ID对应的外观件挂接。

参数	类型	说明
`bindId`	`Int`	绑定ID

返回值 Bool (是否成功)

示例代码

移除指定外观挂接

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local bindId = character.EggyAppearance:BindAppearance(
        "official://preset/101123",
        Enums.SkeletalSocketType.Head,
        Vector3.New(0, 0.2, 0),
        Quaternion.New(0, 0, 0, 1),
        Vector3.New(1, 1, 1)
    )
    character.EggyAppearance:UnbindAppearance(bindId)
end

ResetBindAppearance

签名：ResetBindAppearance() -> void

解除所有通过 BindAppearance 挂接的外观件。

返回值 void

示例代码

移除所有挂接外观件

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:ResetBindAppearance()
end

SetFashionPart

签名：SetFashionPart(partId: Int) -> void

为蛋仔设置指定时装部位的外观，传入部位 ID 即可更换对应部位的时装样式。

参数	类型	说明
`partId`	`Int`	时装部位ID

返回值 void

示例代码

使用项目提供的时装部位 ID

lua

-- @runtime client
local function setFashionPart(partId)
    local players = game:GetService("Players")
    local character = players.LocalPlayer and players.LocalPlayer.Character
    if character == nil or character.EggyAppearance == nil then
        return false
    end
    character.EggyAppearance:SetFashionPart(partId)
    return true
end

GetFashionPart

签名：GetFashionPart(partType: FashionPartType) -> Int (时装散件ID)

获取角色蛋指定身体部位的时装散件ID。

参数	类型	说明
`partType`	FashionPartType	时装部位

返回值 Int (时装散件ID)

示例代码

读取头部时装散件 ID

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local partId = character.EggyAppearance:GetFashionPart(Enums.FashionPartType.Head)
    print("头部时装散件 ID:", partId)
end

SetAccessoryId

签名：SetAccessoryId(accessoryId: Int) -> void

为蛋仔设置指定的时装配饰，传入配饰 ID 即可更换当前佩戴的配饰外观。

参数	类型	说明
`accessoryId`	`Int`	配饰ID

返回值 void

示例代码

使用项目提供的配饰 ID

lua

-- @runtime client
local function setAccessory(accessoryId)
    local players = game:GetService("Players")
    local character = players.LocalPlayer and players.LocalPlayer.Character
    if character == nil or character.EggyAppearance == nil then
        return false
    end
    character.EggyAppearance:SetAccessoryId(accessoryId)
    return true
end

GetAccessoryId

签名：GetAccessoryId(bindPos: AccessoryBindType) -> Int (配饰ID)

获取角色蛋在指定挂点位置装配的配饰ID。

参数	类型	说明
`bindPos`	AccessoryBindType	配饰挂点

返回值 Int (配饰ID)

示例代码

读取头部配饰 ID

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local accessoryId = character.EggyAppearance:GetAccessoryId(Enums.AccessoryBindType.Head)
    print("头部配饰 ID:", accessoryId)
end

SetFaceId

签名：SetFaceId(faceId: Int) -> void

为蛋仔设置静态脸型外观，传入脸型编号即可切换当前脸部样式。

参数	类型	说明
`faceId`	`Int`	面部表情编号

返回值 void

示例代码

使用项目提供的脸型 ID

lua

-- @runtime client
local function setFace(faceId)
    local players = game:GetService("Players")
    local character = players.LocalPlayer and players.LocalPlayer.Character
    if character == nil or character.EggyAppearance == nil then
        return false
    end
    character.EggyAppearance:SetFaceId(faceId)
    return true
end

GetFaceId

签名：GetFaceId() -> Int (面部表情编号)

获取角色蛋当前的静态脸型编号。

返回值 Int (面部表情编号)

示例代码

读取静态脸型 ID

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local faceId = character.EggyAppearance:GetFaceId()
    print("静态脸型 ID:", faceId)
end

SetFaceStatus

签名：SetFaceStatus(faceStatus: FaceStatus) -> void

切换角色的动态表情。

参数	类型	说明
`faceStatus`	FaceStatus	动态表情编号

返回值 void

示例代码

切换角色表情

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:SetFaceStatus(Enums.FaceStatus.Happy)
end

GetFaceStatus

签名：GetFaceStatus() -> FaceStatus (动态表情)

获取角色蛋当前的动态表情状态。

返回值 FaceStatus (动态表情)

示例代码

读取动态表情状态

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local faceStatus = character.EggyAppearance:GetFaceStatus()
    print("动态表情状态:", faceStatus)
end

SetSkinColorId

签名：SetSkinColorId(skinColorId: Int) -> void

为蛋仔设置肤色外观，传入肤色 ID 即可调整蛋仔当前的肤色样式。

参数	类型	说明
`skinColorId`	`Int`	肤色ID

返回值 void

示例代码

使用项目提供的肤色 ID

lua

-- @runtime client
local function setSkinColor(skinColorId)
    local players = game:GetService("Players")
    local character = players.LocalPlayer and players.LocalPlayer.Character
    if character == nil or character.EggyAppearance == nil then
        return false
    end
    character.EggyAppearance:SetSkinColorId(skinColorId)
    return true
end

GetSkinColorId

签名：GetSkinColorId() -> Int (肤色ID)

获取角色蛋当前的肤色ID。

返回值 Int (肤色ID)

示例代码

读取肤色 ID

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local skinColorId = character.EggyAppearance:GetSkinColorId()
    print("肤色 ID:", skinColorId)
end

SetEggShellId

签名：SetEggShellId(eggShellId: Int) -> void

为蛋仔设置指定的蛋皮外观，传入蛋皮 ID 即可更换蛋仔的蛋皮样式。

参数	类型	说明
`eggShellId`	`Int`	蛋皮ID

返回值 void

示例代码

使用项目提供的蛋皮 ID

lua

-- @runtime client
local function setEggShell(eggShellId)
    local players = game:GetService("Players")
    local character = players.LocalPlayer and players.LocalPlayer.Character
    if character == nil or character.EggyAppearance == nil then
        return false
    end
    character.EggyAppearance:SetEggShellId(eggShellId)
    return true
end

GetEggShellId

签名：GetEggShellId() -> Int (蛋皮ID)

获取角色蛋当前使用的蛋皮ID。

返回值 Int (蛋皮ID)

示例代码

读取蛋皮 ID

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    local eggShellId = character.EggyAppearance:GetEggShellId()
    print("蛋皮 ID:", eggShellId)
end

EnableBubbleMessage

签名：EnableBubbleMessage(enable: Bool) -> void

设置是否启用头顶气泡消息功能。

参数	类型	说明
`enable`	`Bool`	是否启用

返回值 void

示例代码

启用头顶气泡消息

lua

-- @runtime client
local players = game:GetService("Players")
local character = players.LocalPlayer and players.LocalPlayer.Character
if character ~= nil and character.EggyAppearance ~= nil then
    character.EggyAppearance:EnableBubbleMessage(true)
end

推球撞方块

跟着做一个小游戏

边做边查

按需求查专题

疯狂农场

EggyAppearance ​

概览 ​

适用场景 ​

使用要点 ​

注意事项 ​

代码示例 ​

获取角色外观组件并显示气泡 ​

函数 (20) ​

ShowBubbleMessage ​

HideBubbleMessage ​

SetAppearanceByAssetId ​

ResetAppearance ​

BindAppearance ​

UnbindAppearance ​

ResetBindAppearance ​

SetFashionPart ​

GetFashionPart ​

SetAccessoryId ​

GetAccessoryId ​

SetFaceId ​

GetFaceId ​

SetFaceStatus ​

GetFaceStatus ​

SetSkinColorId ​

GetSkinColorId ​

SetEggShellId ​

GetEggShellId ​

EnableBubbleMessage ​

EggyAppearance

概览

适用场景

使用要点

注意事项

代码示例

获取角色外观组件并显示气泡

函数 (20)

ShowBubbleMessage

HideBubbleMessage

SetAppearanceByAssetId

ResetAppearance

BindAppearance

UnbindAppearance

ResetBindAppearance

SetFashionPart

GetFashionPart

SetAccessoryId

GetAccessoryId

SetFaceId

GetFaceId

SetFaceStatus

GetFaceStatus

SetSkinColorId

GetSkinColorId

SetEggShellId

GetEggShellId

EnableBubbleMessage