--- title: ZEPETO.Character.Controller slug: world-sdk-guide-ch/ofjx-zepetocharactercontroller docTags: createdAt: 2026-09-04T06:58:04.526Z --- | 类型 | 说明 | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | [ZepetoPlayers](./#zepetoplayers) | 用于同时控制 ZEPETO 玩家与 ZEPETO 角色的管理器类。 | | [SpawnInfo](./#spawninfo) | 表示 ZEPETO 角色的生成位置。 | | [ZepetoCharacter](./#zepetocharacter) | 表示可在 ZEPETO World 中加载并控制的 ZEPETO 角色。 | | [CameraData](./#cameradata) | 表示 `ZepetoCamera` 的初始配置。 | | [CharacterData](./#characterdata) | 表示 `ZepetoCharacter` 的初始配置。 | | [ControllerData](./#controllerdata) | 表示 `ZepetoPlayerControl` 的配置。 | | [FloatingUIData](./#floatinguidata) | 负责管理角色相关 UI 设置的类。 | | [LocalPlayer](./#localplayer) | 用于管理本地玩家动作的类，涵盖移动、服装自定义以及 ZEPETO 摄像机交互。 | | [ZepetoCamera](./#zepetocamera) | 为 ZEPETO Character Controller 内使用而设计的摄像机控制类。 | | [ZepetoPlayer](./#zepetoplayer) | 表示 ZEPETO 玩家。 | | [ZepetoPlayerControl](./#zepetoplayercontrol) | 管理 ZEPETO 玩家的输入控制。 | | [ZepetoCameraControl](./#zepetocameracontrol) | 管理 ZEPETO 环境中的摄像机控制，包括摄像机移动与缩放的输入处理。 | | [CharacterState](./#characterstate) | 表示 ZEPETO 角色的状态。 | | [CharacterMoveState](./#charactermovestate) | 表示 ZEPETO 角色的详细移动状态。 | | [CharacterJumpState](./#characterjumpstate) | 表示 ZEPETO 角色的详细跳跃状态。 | | [CharacterLandingState](./#characterlandingstate) | 表示 ZEPETO 角色的详细落地状态。 | | [KnowSockets](./#knowsockets) | 定义角色上一组已知的挂点（socket）。 | | [MotionState](./#motionstate) | 用于管理角色动作状态与配置的类。 | | [CharacterStateMachine](./#characterstatemachine) | 负责将 animator 与 ZEPETO 角色的角色状态保持同步的类。 | | [StateMachine](./#statemachine) | `StateMachine` 用于管理 `States`、`Transitions` 和 `Events`。它会根据指定条件和经过时间更新状态，从而实现对对象各种状态的定义与控制。 | | [StateStatus](./#statestatus) | 表示状态机中某个状态可能处于的状况，用于指示该状态生命周期的当前阶段。 | | [CustomMotionData](./#custommotiondata) | 表示角色动作的自定义配置。 | | [CharacterShadow](./#charactershadow) | 负责管理 ZEPETO 角色阴影的类。 | | [CameraState](./#camerastate) | 表示 `ZepetoCamera` 的状态。 | | [ZepetoScreenStick](./#zepetoscreenstick) | 用于处理 ZEPETO 环境中摇杆交互的类。 | | [ZepetoScreenControl](./#zepetoscreencontrol) | 用于在 ZEPETO 环境中创建 UI 控件的抽象类。 | | [ZepetoScreenButton](./#zepetoscreenbutton) | 用于处理 ZEPETO 环境中按钮交互的类。 | | [ZepetoScreenTouchpad](./#zepetoscreentouchpad) | 用于处理 ZEPETO 环境中触摸板交互的类。 | | [UIZepetoPlayerControl](./#uizepetoplayercontrol) | 为本地玩家角色提供基于 UI 的控制的类。 | | [InputHelper](./#inputhelper) | 用于辅助输入处理的工具类。 | | [EventReceiver](./#eventreceiver) | 负责处理 ZEPETO World 内角色相关事件或通用事件的类。 | | [TransitionBase](./#transitionbase) | 用于定义状态机中状态之间转换的基类。 | | [State](./#state) | 表示状态机中的一个状态。 | | [Transition](./#transition) | 用于定义状态机中状态之间转换的泛型类。 | | [ZepetoCharacter.LoadingStatus](./#zepetocharacterloadingstatus) | ZEPETO 角色的加载状态。 | | [PlayerControlMode](./#playercontrolmode) | *enum* | ## ZepetoPlayers `class` 用于同时控制 ZEPETO 玩家与 ZEPETO 角色的管理器类。 ### 属性 | 名称 | 类型 | 说明 | | ----------------- | ----------------------------------- | -------------------------- | | cameraData | [CameraData](./#cameradata) | `ZepetoCamera` 的配置。 | | characterData | [CharacterData](./#characterdata) | `ZepetoCharacter` 的配置。 | | controllerData | [ControllerData](./#controllerdata) | `ZepetoPlayerControl` 的配置。 | | floatingUIData | [FloatingUIData](./#floatinguidata) | 角色相关的 UI 设置。 | | instance (static) | [ZepetoPlayers](./#zepetoplayers) | `ZepetoPlayers` 的单例实例。 | | LocalPlayer | [LocalPlayer](./#localplayer) | 本地玩家。 | | ZepetoCamera | [ZepetoCamera](./#zepetocamera) | ZEPETO 摄像机。 | ### 事件 | 名称 | 类型 | 说明 | | ------------------ | -------------------- | --------------- | | OnAddedLocalPlayer | `UnityEvent` | 创建本地玩家实例时触发的事件。 | | OnAddedPlayer | `UnityEvent` | 创建玩家实例时触发的事件。 | | OnRemovedPlayer | `UnityEvent` | 移除玩家实例时触发的事件。 | ### 方法 ### add\_onInitialized `static add_onInitialized(value: Action) → void` 为 `ZepetoPlayers` 初始化时调用的事件添加处理函数。 | 参数 | 类型 | | ----- | -------- | | value | `Action` | ### remove\_onInitialized `static remove_onInitialized(value: Action) → void` 移除 `ZepetoPlayers` 初始化时调用的事件的处理函数。 | 参数 | 类型 | | ----- | -------- | | value | `Action` | ### HasPlayer `HasPlayer(id: string) → boolean` 检查是否存在与指定会话 ID 关联的玩家实例。 | 参数 | 类型 | 说明 | | -- | -------- | ----- | | id | `string` | 会话 ID | **返回值：** `boolean` ### GetPlayer `GetPlayer(id: string) → ZepetoPlayer` 获取与指定会话 ID 关联的玩家实例。 | 参数 | 类型 | 说明 | | -- | -------- | ----- | | id | `string` | 会话 ID | **返回值：** [ZepetoPlayer](./#zepetoplayer) — 与指定 ID 关联的玩家对象。 若不存在该 ID 对应的玩家，则返回 `null`。 ### GetPlayerWithUserId `GetPlayerWithUserId(userId: string) → ZepetoPlayer` 获取与指定用户 ID 关联的玩家实例。 | 参数 | 类型 | 说明 | | ------ | -------- | ----- | | userId | `string` | 用户 ID | **返回值：** [ZepetoPlayer](./#zepetoplayer) — 与指定用户 ID 关联的玩家对象。 ### RemovePlayer `RemovePlayer(id: string) → void` 移除与指定会话 ID 关联的玩家实例。 | 参数 | 类型 | 说明 | | -- | -------- | ----- | | id | `string` | 会话 ID | ### DeformDefaultCostume `DeformDefaultCostume() → void` 移除所有玩家角色所穿戴的体型变形道具。 恢复为默认体型并应用默认 ZEPETO 服装。 ### DeformDefaultProperties `DeformDefaultProperties() → void` 移除所有玩家角色所穿戴的体型变形道具。 ## SpawnInfo `class` 表示 ZEPETO 角色的生成位置。 ### 属性 | 名称 | 类型 | 说明 | | ---------------- | ------------------------- | ---------------- | | Default (static) | [SpawnInfo](./#spawninfo) | 默认生成位置。 | | position | `Vector3` | ZEPETO 角色生成时的位置。 | | rotation | `Quaternion` | ZEPETO 角色生成时的旋转。 | ## ZepetoCharacter `class` 表示可在 ZEPETO World 中加载并控制的 ZEPETO 角色。 ### 属性 | 名称 | 类型 | 说明 | | ------------------- | ------------------------------------------------- | ---------------------- | | additionalWalkSpeed | `number` | 获取附加的行走速度。 | | additionalRunSpeed | `number` | 获取附加的奔跑速度。 | | additionalJumpPower | `number` | 获取附加的跳跃力。 | | constraintRotation | `boolean` | 决定是否限制角色的旋转。 | | ZepetoAnimator | `Animator` | ZEPETO 角色的 Animator。 | | WalkSpeed | `number` | 获取总行走速度，即基础速度与附加速度之和。 | | RunSpeed | `number` | 获取总奔跑速度，即基础速度与附加速度之和。 | | JumpPower | `number` | 获取总跳跃力，即基础跳跃力与附加跳跃力之和。 | | baseWalkSpeed | `number` | 获取基础行走速度。 | | baseRunSpeed | `number` | 获取基础奔跑速度。 | | baseJumpPower | `number` | 获取基础跳跃力。 | | tryMove | `boolean` | 表示角色是否正在尝试移动。 | | tryJump | `boolean` | 表示角色是否正在尝试跳跃。 | | tryDoubleJump | `boolean` | 表示角色是否正在尝试二段跳。 | | motionState | [MotionState](./#motionstate) | 角色的动作状态与配置。 | | loadingStatus | [LoadingStatus](./#zepetocharacterloadingstatus) | 角色的加载状态。 | | Context | `ZepetoContext` | 角色的 ZEPETO Context。 | | StateMachine | [CharacterStateMachine](./#characterstatemachine) | 角色的状态机。 | | CurrentState | [CharacterState](./#characterstate) | 状态机中定义的角色当前状态。 | | CurrentStateStatus | [StateStatus](./#statestatus) | 状态机中定义的角色当前状态的状况。 | | ElapsedTime | `number` | 自角色初始化以来经过的时间（秒）。 | ### 事件 | 名称 | 类型 | 说明 | | -------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------- | | OnChangedState | `UnityEvent` | 角色状态发生变化时触发的事件。已注册的监听器会收到两个参数： - 新的角色状态。（类型：`CharacterState`） - 之前的角色状态。（类型：`CharacterState`） | | OnUpdateState | `UnityEvent` | 角色状态处于 `StateStatus.Update` 状况时触发的事件。已注册的监听器会收到一个参数： - 当前的角色状态。（类型：`CharacterState`） | ### 方法 ### SyncStateAnimation `SyncStateAnimation() → void` 将 animator 与 ZEPETO 角色的当前角色状态同步。 ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState) → void` 在 animator 上播放与所提供角色状态相对应的动画。 | 参数 | 类型 | 说明 | | ----- | ----------------------------------- | ------------- | | state | [CharacterState](./#characterstate) | 表示要播放动画的角色状态。 | ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState, moveState: CharacterMoveState) → void` 在 animator 上播放与所提供角色状态相对应的动画。 | 参数 | 类型 | 说明 | | --------- | ------------------------------------------- | ------------------------------------------------- | | state | [CharacterState](./#characterstate) | 表示要播放动画的角色状态。 | | moveState | [CharacterMoveState](./#charactermovestate) | 当 `state` 为 `CharacterState.Move` 时用于动画的移动状态（可选）。 | ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState, jumpState: CharacterJumpState) → void` 在 animator 上播放与所提供角色状态相对应的动画。 | 参数 | 类型 | 说明 | | --------- | ------------------------------------------- | ------------------------------------------------- | | state | [CharacterState](./#characterstate) | 表示要播放动画的角色状态。 | | jumpState | [CharacterJumpState](./#characterjumpstate) | 当 `state` 为 `CharacterState.Jump` 时用于动画的跳跃状态（可选）。 | ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState, landingState: CharacterLandingState) → void` 在 animator 上播放与所提供角色状态相对应的动画。 | 参数 | 类型 | 说明 | | ------------ | ------------------------------------------------- | ---------------------------------------------------- | | state | [CharacterState](./#characterstate) | 表示要播放动画的角色状态。 | | landingState | [CharacterLandingState](./#characterlandingstate) | 当 `state` 为 `CharacterState.Landing` 时用于动画的落地状态（可选）。 | ### Move `Move(dir: Vector2) → void` 使角色朝指定方向移动。 | 参数 | 类型 | 说明 | | --- | --------- | --------- | | dir | `Vector2` | 角色应移动的方向。 | ### Move `Move(dir: Vector3) → void` 使角色朝指定方向移动。 | 参数 | 类型 | 说明 | | --- | --------- | --------- | | dir | `Vector3` | 角色应移动的方向。 | ### MoveContinuously `MoveContinuously(dir: Vector2) → void` 以角色当前朝向为基准，使其朝指定方向持续移动。 | 参数 | 类型 | 说明 | | --- | --------- | -------------------- | | dir | `Vector2` | 以角色当前朝向为基准，角色应移动的方向。 | ### MoveContinuously `MoveContinuously(dir: Vector3) → void` 以角色当前朝向为基准，使其朝指定方向持续移动。 | 参数 | 类型 | 说明 | | --- | --------- | -------------------- | | dir | `Vector3` | 以角色当前朝向为基准，角色应移动的方向。 | ### MoveToPosition `MoveToPosition(pos: Vector3) → void` 使角色移动到指定位置。 | 参数 | 类型 | 说明 | | --- | --------- | ----------- | | pos | `Vector3` | 角色应移动到的目的地。 | ### StopMoving `StopMoving() → void` 停止角色的移动。 ### Jump `Jump() → void` 使角色跳跃。 ### DoubleJump `DoubleJump() → void` 使角色进行二段跳。 ### Teleport `Teleport(pos: Vector3, rot: Quaternion) → void` 将角色瞬间移动到指定的 transform。 | 参数 | 类型 | 说明 | | --- | ------------ | ----------- | | pos | `Vector3` | 角色将被传送到的位置。 | | rot | `Quaternion` | 角色传送后的旋转。 | ### SetGesture `SetGesture(gesture: AnimationClip) → void` 播放角色对应指定手势的动作。 | 参数 | 类型 | 说明 | | ------- | --------------- | --------- | | gesture | `AnimationClip` | 角色将执行的手势。 | ### CancelGesture `CancelGesture() → void` 停止手势的播放。 ### GetSocket `GetSocket(socket: KnowSockets) → Transform` 获取角色某个挂点的 `Transform`。 | 参数 | 类型 | 说明 | | ------ | ----------------------------- | ----------- | | socket | [KnowSockets](./#knowsockets) | 挂点（socket）。 | **返回值：** `Transform` — 与指定挂点关联的 `Transform` 组件。 ### GetSocket `GetSocket(socket: string) → Transform` 获取角色某个挂点的 `Transform`。 | 参数 | 类型 | 说明 | | ------ | -------- | -------------- | | socket | `string` | 挂点（socket）的名称。 | **返回值：** `Transform` — 与指定挂点关联的 `Transform` 组件。 ### GetBodyModifierProperties `GetBodyModifierProperties() → ZepetoPropertyFlag[]` 获取与角色所穿戴体型变形道具关联的角色属性。 **返回值：** `ZepetoPropertyFlag[]` — 与角色所穿戴体型变形道具关联的角色属性。 ### DeformDefaultProperties `DeformDefaultProperties() → void` 移除角色所穿戴的体型变形道具，并恢复为默认体型。 ### DeformDefaultCostume `DeformDefaultCostume() → void` 移除角色所穿戴的体型变形道具，恢复为默认体型，并应用默认 ZEPETO 服装。 ### add\_loadedCharacter `add_loadedCharacter(value: Action) → void` 添加用于处理角色加载完成的回调函数。 | 参数 | 类型 | | ----- | -------- | | value | `Action` | ### remove\_loadedCharacter `remove_loadedCharacter(value: Action) → void` 移除用于处理角色加载完成的回调函数。 | 参数 | 类型 | | ----- | -------- | | value | `Action` | ## CameraData `class` 表示 `ZepetoCamera` 的初始配置。 ### 属性 | 名称 | 类型 | 说明 | | ---------------------- | ------------ | ----------------------------- | | cameraPrefab | `GameObject` | 用于初始化 `ZepetoCamera` 的预制件。 | | maxZoomDistance | `number` | 摄像机可从目标拉远的默认最大距离。 | | minZoomDistance | `number` | 摄像机可向目标拉近的默认最小距离。 | | maxPitch | `number` | 摄像机绕目标旋转的最大垂直角度。 | | minPitch | `number` | 摄像机绕目标旋转的最小垂直角度。 | | offset | `Vector3` | 摄像机相对于目标的默认偏移。 | | lockXAxis | `boolean` | 表示摄像机的 X 轴旋转是否被锁定。 | | layer | `LayerMask` | 定义摄像机可与之发生碰撞的层。 | | collisionTimeThreshold | `number` | 摄像机碰撞检测的时间阈值，影响摄像机对碰撞的响应速度。 | | zoomSpeed | `number` | 缩放的速度。 | | zoomDampSpeed | `number` | 缩放的插值速度。 | | rotationSpeed | `number` | 旋转的速度。 | | rotationDampSpeed | `number` | 旋转的插值速度。 | | characterCulling | `boolean` | 表示是否启用角色剔除，以避免摄像机距离过近时出现渲染问题。 | | targetScaleWeight | `number` | 应用于目标缩放的权重，用于调整摄像机的位置与行为。 | ## CharacterData `class` 表示 `ZepetoCharacter` 的初始配置。 ### 属性 | 名称 | 类型 | 说明 | | ------------------ | --------------------------------------- | ------------------------- | | slopeLimit | `number` | 角色可攀爬的最大坡度。 | | stepOffset | `number` | 角色可跨越的最大垂直高度差。 | | skinWidth | `number` | 用于碰撞检测的皮肤宽度，可防止角色陷入其他碰撞体。 | | minMoveDistance | `number` | 角色可通过的最小间隙。 | | center | `Vector3` | 角色碰撞体的中心点。 | | radius | `number` | 角色胶囊碰撞体的半径。 | | height | `number` | 角色胶囊碰撞体的高度。 | | layer | `LayerMask` | 定义角色可与之发生碰撞的层。 | | shadow | `GameObject` | 角色阴影的视觉表现。 | | animatorController | `RuntimeAnimatorController` | 角色的 Animator Controller。 | | walkSpeed | `number` | 角色的行走速度。 | | runSpeed | `number` | 角色的奔跑速度。 | | jumpPower | `number` | 角色的跳跃力。 | | customMotionData | [CustomMotionData](./#custommotiondata) | 角色动作的自定义配置。 | ## ControllerData `class` 表示 `ZepetoPlayerControl` 的配置。 ### 属性 | 名称 | 类型 | 说明 | | --------------------------- | ------------------ | --------------------------------- | | inputAsset | `InputActionAsset` | 用于管理复杂输入配置的输入操作与绑定容器。 | | eventSystem | `GameObject` | 处理用户输入并传递给 UI 组件。负责按钮点击、拖动、放置等交互。 | | useDefaultVirtualController | `boolean` | 决定是否使用默认 V-Pad。 | | useDefaultInputController | `boolean` | 决定是否使用默认输入控制器。 | | verticalController | `GameObject` | 用于竖屏方向的 V-Pad 控制器预制件。 | | horizontalController | `GameObject` | 用于横屏方向的 V-Pad 控制器预制件。 | ## FloatingUIData `class` 负责管理角色相关 UI 设置的类。 ### 属性 | 名称 | 类型 | 说明 | | -------------------------- | --------- | --------------------- | | showNickNameLocalPlayer | `boolean` | 决定是否显示本地玩家角色的昵称 UI。 | | showNickNameOtherPlayers | `boolean` | 决定是否显示其他玩家角色的昵称 UI。 | | showBubbleChatLocalPlayer | `boolean` | 决定是否显示本地玩家角色的气泡聊天 UI。 | | showBubbleChatOtherPlayers | `boolean` | 决定是否显示其他玩家角色的气泡聊天 UI。 | | useMiniProfileOnApp | `boolean` | 决定点击角色时是否显示迷你资料弹窗 UI。 | ## LocalPlayer `class` 用于管理本地玩家动作的类，涵盖移动、服装自定义以及 ZEPETO 摄像机交互。 ### 属性 | 名称 | 类型 | 说明 | | ------------ | ------------------------------- | ---------------------- | | movingAxis | `Transform` | 本地玩家 ZEPETO 角色的移动中心轴。 | | zepetoCamera | [ZepetoCamera](./#zepetocamera) | 与本地玩家关联的 ZEPETO 摄像机实例。 | | zepetoPlayer | [ZepetoPlayer](./#zepetoplayer) | 与本地玩家关联的 ZEPETO 玩家实例。 | ### 方法 ### SetCostume `SetCostume(itemCode: string, complete?: Action) → void` 更改本地玩家 ZEPETO 角色的服装。会抛出通用 `Exception`。 | 参数 | 类型 | 说明 | | ------------- | -------- | -------------- | | itemCode | `string` | 服装的道具 ID。 | | complete （可选） | `Action` | 用于处理完成事件的回调函数。 | ### Jump `Jump() → void` 使本地玩家的 ZEPETO 角色跳跃。 ### DoubleJump `DoubleJump() → void` 使本地玩家的 ZEPETO 角色进行二段跳。 ### Move `Move(dir: Vector2) → void` 使本地玩家的 ZEPETO 角色朝指定方向移动。 | 参数 | 类型 | 说明 | | --- | --------- | --------- | | dir | `Vector2` | 角色应移动的方向。 | ### Move `Move(dir: Vector3) → void` 使本地玩家的 ZEPETO 角色朝指定方向移动。 | 参数 | 类型 | 说明 | | --- | --------- | --------- | | dir | `Vector3` | 角色应移动的方向。 | ### StopMoving `StopMoving() → void` 停止本地玩家的 ZEPETO 角色。 ## ZepetoCamera `class` 为 ZEPETO Character Controller 内使用而设计的摄像机控制类。 ### 属性 | 名称 | 类型 | 说明 | | ------------------------- | --------------------------------------------- | ----------------------------------------------- | | additionalMaxZoomDistance | `number` | 在默认最大缩放值基础上追加的距离。 | | additionalMinZoomDistance | `number` | 在默认最小缩放值基础上追加的距离。 | | additionalOffset | `Vector3` | 应用于摄像机相对目标位置的额外偏移。 | | currentState | [CameraState](./#camerastate) | 获取当前的摄像机状态。 | | currentStateStatus | [StateStatus](./#statestatus) | 获取当前摄像机状态的状况。 | | position | `Vector3` | 获取当前摄像机的位置值。 | | rotation | `Quaternion` | 获取当前摄像机的旋转值。 | | distance | `number` | 与目标之间的距离。 | | cameraParent | `Transform` | 摄像机父物体的 `Transform`。 | | isFollow | `boolean` | 获取表示摄像机是否正在跟随目标的标志。 | | StateMachine | [StateMachine\](./#statemachine) | 获取摄像机的状态机。 | | FollowTarget | `Transform` | 获取目标的 `Transform`。默认情况下设置为本地玩家角色的 `HEAD_UPPER`。 | | MaxZoomDistance | `number` | 经计算得出的摄像机可从目标拉远的最大距离。 | | MinZoomDistance | `number` | 经计算得出的摄像机可向目标拉近的最小距离。 | | LookOffset | `Vector3` | 经计算得出的摄像机相对于目标的偏移。 | | LockXAxis | `boolean` | 表示摄像机的 X 轴旋转是否被锁定。 | | CollisionLayer | `LayerMask` | 定义摄像机可与之发生碰撞的层。 | | targetScaleWeight | `number` | 应用于目标缩放的权重，用于调整摄像机的位置与行为。 | | useCharacterCulling | `boolean` | 表示是否启用角色剔除，以避免摄像机距离过近时出现渲染问题。 | | zoomSpeed | `number` | 缩放的速度。 | | zoomDampSpeed | `number` | 缩放的插值速度。 | | rotationSpeed | `number` | 旋转的速度。 | | rotationDampSpeed | `number` | 旋转的插值速度。 | | camera | `Camera` | Unity 的 `Camera`。 | ### 事件 | 名称 | 类型 | 说明 | | -------------- | -------------------------------------- | ------------------------------------------------------------------------------------------ | | OnChangedState | `UnityEvent` | 摄像机状态发生变化时触发的事件。已注册的监听器会收到两个参数： - 新的摄像机状态。（类型：`CameraState`） - 之前的摄像机状态。（类型：`CameraState`） | | OnUpdateState | `UnityEvent` | 当前摄像机状态处于 `StateStatus.Update` 状况时触发的事件。已注册的监听器会收到一个参数： - 当前的摄像机状态。（类型：`CameraState`） | ### 方法 ### Create `static Create(camera: Camera, data: CameraData) → ZepetoCamera` 创建 `ZepetoCamera` 实例。 | 参数 | 类型 | 说明 | | ------ | --------------------------- | ---------------------------------------- | | camera | `Camera` | 作为 `ZepetoCamera` 基础的 Unity `Camera` 对象。 | | data | [CameraData](./#cameradata) | `ZepetoCamera` 的初始配置。 | **返回值：** [ZepetoCamera](./#zepetocamera) — `ZepetoCamera` 的新实例。 ### SetFollowTarget `SetFollowTarget(target: Transform, scaleReference?: Transform) → void` 设置摄像机的跟随目标。 | 参数 | 类型 | 说明 | | ------------------- | ----------- | ------------------------------------------------------------ | | target | `Transform` | 表示摄像机应跟随对象的 `Transform`。 | | scaleReference （可选） | `Transform` | 用作缩放摄像机跟随行为参考的 `Transform`。若提供该参数，摄像机会根据此参考对象的缩放来调整与目标之间的距离。 | ### Rotate `Rotate(delta: Vector2) → void` 旋转摄像机。 | 参数 | 类型 | 说明 | | ----- | --------- | ---- | | delta | `Vector2` | 旋转量。 | ### DoZoom `DoZoom(delta: number) → void` 缩放摄像机。 | 参数 | 类型 | 说明 | | ----- | -------- | ---- | | delta | `number` | 缩放量。 | ## ZepetoPlayer `class` 表示 ZEPETO 玩家。 ### 属性 | 名称 | 类型 | 说明 | | ------------- | ------------------------------------- | --------------------------- | | userId | `string` | 玩家的用户 ID，是在创建账号时随机分配的唯一 ID。 | | name | `string` | 玩家的用户名，由用户在 ZEPETO 应用中设置。 | | character | [ZepetoCharacter](./#zepetocharacter) | 玩家的 ZEPETO 角色。 | | isLocalPlayer | `boolean` | 表示是否为本地玩家。 | ### 方法 ### GetProfileTextureAsync `GetProfileTextureAsync(complete: Action) → void` 获取玩家的头像。会抛出通用 `Exception`。 | 参数 | 类型 | 说明 | | -------- | ------------------- | --------------- | | complete | `Action` | 用于处理所获取头像的回调函数。 | ### Release `Release() → void` 释放 ZEPETO 玩家对象。 ## ZepetoPlayerControl `class` 管理 ZEPETO 玩家的输入控制。 ### 方法 ### Create `static Create(playerActions: PlayerActions) → ZepetoPlayerControl` 创建 `ZepetoPlayerControl` 实例。 | 参数 | 类型 | 说明 | | ------------- | --------------- | ----------------------------------- | | playerActions | `PlayerActions` | 要与 `ZepetoPlayerControl` 关联的输入操作集合。 | **返回值：** [ZepetoPlayerControl](./#zepetoplayercontrol) — `ZepetoPlayerControl` 的新实例。 该实例已挂载到新的游戏对象上，可以处理玩家的输入操作。 ## ZepetoCameraControl `class` 管理 ZEPETO 环境中的摄像机控制，包括摄像机移动与缩放的输入处理。 ### 方法 ### Create `static Create(cameraActions: CameraActions) → ZepetoCameraControl` 创建 `ZepetoCameraControl` 实例。 | 参数 | 类型 | 说明 | | ------------- | --------------- | ------------------------------------------------------- | | cameraActions | `CameraActions` | 要与 `ZepetoCameraControl` 关联的摄像机操作集合。这些操作定义了摄像机如何响应用户输入。 | **返回值：** [ZepetoCameraControl](./#zepetocameracontrol) — `ZepetoCameraControl` 的新实例。 该实例已挂载到新的游戏对象上，可以处理摄像机的输入操作。 ## CharacterState `enum` 表示 ZEPETO 角色的状态。 | 名称 | 值 | 说明 | | -------- | --- | --------------------------- | | Invalid | 0 | 未初始化或无效。 | | Idle | 1 | 角色未进行任何移动或动作。 | | Walk | 2 | 角色正在缓慢移动。 | | Run | 3 | 角色正在快速移动。 | | JumpIdle | 4 | 角色正在原地跳跃。 | | JumpMove | 5 | 角色正朝某一方向跳跃，将垂直起跳与水平移动结合在一起。 | | Teleport | 20 | 角色正从一个位置移动到另一个位置，且不经过中间的空间。 | | Gesture | 30 | 角色正在执行手势。 | | Move | 102 | 一般移动状态。 | | MoveTurn | 103 | 角色正在改变移动方向。 | | Jump | 104 | 一般跳跃状态。 | | Stamp | 106 | 角色正在进行踏地动作。 | | Falling | 108 | 角色正处于自由落体状态。 | | Landing | 109 | 角色在下落后回到地面。 | ## CharacterMoveState `enum` 表示 ZEPETO 角色的详细移动状态。 | 名称 | 值 | 说明 | | -------- | -- | ----- | | None | -1 | None. | | MoveWalk | 0 | 缓慢移动。 | | MoveRun | 1 | 快速移动。 | ## CharacterJumpState `enum` 表示 ZEPETO 角色的详细跳跃状态。 | 名称 | 值 | 说明 | | ---------- | -- | ------------------------ | | None | -1 | None. | | JumpIdle | 0 | 原地跳跃。 | | JumpMove | 1 | 朝某一方向跳跃，将垂直起跳与水平移动结合在一起。 | | JumpDash | 2 | 快速跳跃。 | | JumpDouble | 3 | 在跳跃过程中进行第二次跳跃。 | ## CharacterLandingState `enum` 表示 ZEPETO 角色的详细落地状态。 | 名称 | 值 | 说明 | | ------------- | -- | -------- | | None | -1 | None. | | LandingSlight | 0 | 轻微冲击的落地。 | | LandingDeep | 1 | 强烈冲击的落地。 | | LandingRoll | 2 | 翻滚落地。 | ## KnowSockets `enum` 定义角色上一组已知的挂点（socket）。 | 名称 | 值 | 说明 | | ----------- | - | ------------ | | HEAD\_UPPER | 0 | 表示角色头部的上半部分。 | ## MotionState `class` 用于管理角色动作状态与配置的类。 ### 属性 | 名称 | 类型 | 说明 | | ------------------- | ------------------------------------------------- | ------------------- | | useDoubleJump | `boolean` | 决定角色是否可以进行二段跳。 | | doubleJumpPower | `number` | 二段跳时施加的额外力。 | | useLanding | `boolean` | 决定是否应用落地动作。 | | useLandingRoll | `boolean` | 决定角色落地时是否进行翻滚。 | | landingRollSpeed | `number` | 获取或设置角色的落地翻滚速度。 | | useMoveTurn | `boolean` | 决定是否播放角色改变移动方向时的动作。 | | gravity | `number` | 施加于角色的重力。 | | currentJumpState | [CharacterJumpState](./#characterjumpstate) | 获取角色当前的跳跃状态。 | | currentLandingState | [CharacterLandingState](./#characterlandingstate) | 获取角色当前的落地状态。 | | currentMoveState | [CharacterMoveState](./#charactermovestate) | 获取角色当前的移动状态。 | ## CharacterStateMachine `class` · extends [StateMachine\](./#statemachine) 负责将 animator 与 ZEPETO 角色的角色状态保持同步的类。 ### 属性 | 名称 | 类型 | 说明 | | ------------------------ | --------- | -------------------------------------------------------------------------- | | constraintStateAnimation | `boolean` | 决定是否将 animator 与 ZEPETO 角色的当前角色状态同步。若设为 `true`，animator 状态将不会根据当前角色状态进行更新。 | ### 方法 ### SyncStateAnimation `SyncStateAnimation() → void` 将 animator 与 ZEPETO 角色的当前角色状态同步。 ### ChangeStateAnimation `ChangeStateAnimation(state: CharacterState) → void` 在 animator 上播放与所提供角色状态相对应的动画。 | 参数 | 类型 | 说明 | | ----- | ----------------------------------- | ------------- | | state | [CharacterState](./#characterstate) | 表示要播放动画的角色状态。 | ## StateMachine `class` `StateMachine` manages the `States`, `Transitions`, and `Events`. 通过根据指定条件和经过时间更新状态，实现对对象各种状态的定义与控制。 ### 属性 | 名称 | 类型 | 说明 | | --------------- | ----------------------------------------------- | ------------------------------------------------ | | OnChangedState | `Action` | 摄像机状态发生变化时触发的事件。已注册的监听器会收到两个参数： - 新的状态。 - 之前的状态。 | | Events | [TransitionBase\\[\]](./#transitionbase) | 提供状态机中定义的所有事件的数组。 | | Current | [State\](./#state) | 获取当前状态。 | | Prev | [State\](./#state) | 获取之前的状态。 | | IsRunning | `boolean` | 表示状态机是否正在处理状态与转换。 | | stateCount | `number` | 获取状态机中定义的状态数量。 | | transitionCount | `number` | 获取状态机中定义的转换数量。 | ### 方法 ### FindState `FindState(state: TEnum, success: Action>, failed: Action) → void` 在状态机中查找状态，成功时执行回调。 | 参数 | 类型 | 说明 | | ------- | ---------------------- | ---------------------- | | state | `TEnum` | 要在状态机中查找的状态。 | | success | `Action>` | 用于处理所找到 `State` 的回调函数。 | | failed | `Action` | 用于处理未找到该状态情况的回调函数。 | ### FindTransitions `FindTransitions(from: TEnum, success: Action[]>, failed: Action) → void` 在状态机中查找转换，成功时执行回调。 | 参数 | 类型 | 说明 | | ------- | ----------------------------- | ----------------------------- | | from | `TEnum` | 转换的起始状态。 | | success | `Action[]>` | 用于处理所找到 `Transition` 数组的回调函数。 | | failed | `Action` | 用于处理未找到转换情况的回调函数。 | ### FindTransition `FindTransition(from: TEnum, to: TEnum, success: Action>, failed: Action) → void` 在状态机中查找某个转换，成功时执行回调。 | 参数 | 类型 | 说明 | | ------- | --------------------------- | --------------------------- | | from | `TEnum` | 转换的起始状态。 | | to | `TEnum` | 转换将要到达的状态。 | | success | `Action>` | 用于处理所找到 `Transition` 的回调函数。 | | failed | `Action` | 用于处理未找到该转换情况的回调函数。 | ### Start `Start(state: TEnum) → void` 启动状态机的处理。 | 参数 | 类型 | 说明 | | ----- | ------- | -------------- | | state | `TEnum` | 状态机开始处理时所处的状态。 | ### Update `Update(deltaTime: number) → void` 更新状态机的当前状态与转换。 | 参数 | 类型 | 说明 | | --------- | -------- | -------------------------- | | deltaTime | `number` | 自上次调用 `Update` 以来经过的时间（秒）。 | ### Stop `Stop() → void` 停止状态机的处理。 ### EnterState `EnterState(state: TEnum) → void` 将状态机转换到指定状态。 | 参数 | 类型 | 说明 | | ----- | ------- | ------------ | | state | `TEnum` | 状态机将要转换到的状态。 | ### LeaveState `LeaveState(nextState: TEnum) → void` 状态机退出当前状态。 | 参数 | 类型 | 说明 | | --------- | ------- | -------------------------- | | nextState | `TEnum` | 由当前状态的 `OnLeave` 处理的下一个状态。 | ## StateStatus `enum` 表示状态机中某个状态可能处于的状况，用于指示该状态生命周期的当前阶段。 | 名称 | 值 | 说明 | | ------ | - | ----------------- | | Wait | 0 | 状态处于非激活状态，等待被进入。 | | Enter | 1 | 状态正处于进入过程中。 | | Update | 2 | 状态处于激活状态，其逻辑正在执行。 | | End | 3 | 状态已完成其激活阶段，准备结束。 | | Leave | 4 | 状态正处于退出过程中。 | ## CustomMotionData `class` 表示角色动作的自定义配置。 ### 属性 | 名称 | 类型 | 说明 | | ----------------------------- | --------- | ------------------------- | | useDoubleJump | `boolean` | 决定角色是否可以进行二段跳。 | | doubleJumpPower | `number` | 二段跳时施加的额外力。 | | useLanding | `boolean` | 决定是否应用落地动作。 | | useLandingRoll | `boolean` | 决定角色落地时是否进行翻滚。 | | landingRollSpeed | `number` | 落地翻滚动作的播放速度。 | | useMoveTurn | `boolean` | 决定是否播放角色改变移动方向时的动作。 | | gravity | `number` | 施加于角色的重力。 | | walkThreshold | `number` | 触发行走动作加速所需的最小输入值。 | | runThreshold | `number` | 从行走动作切换为奔跑动作所需的最小输入值。 | | fallingTimeThreshold | `number` | 判定角色是否进入下落状态所需的最短下落时间。 | | fallingSpeedThreshold | `number` | 判定角色是否进入下落状态所需的最小下落速度。 | | landingTimeThreshold | `number` | 判定角色是否已落地所需的最短着地时间。 | | landingSpeedThreshold | `number` | 判定角色落地时能否执行额外动作所需的最小下落速度。 | | landingImpactSpeedThreshold | `number` | 判定角色落地时是否受到更大冲击所需的最小下落速度。 | | landingRollSpeedThreshold | `number` | 触发落地翻滚所需的最大下落速度。 | | moveTurnAngleThreshold | `number` | 触发转身动作所需的最小转向角度。 | | moveTurnSpeedThreshold | `number` | 触发转身动作所需的最小移动速度。 | | moveTurnTimeThreshold | `number` | 转身动作的持续时间。 | | jumpDashSpeedThreshold | `number` | 触发冲刺所需的最小跳跃速度。 | | walkClipBaseSpeed | `number` | 行走动作的基础速度。 | | stampClipNormalizedTime | `number` | 踏地动作的持续时间。 | | landingClipNormalizedTime | `number` | 落地动作的持续时间。 | | landingRollClipNormalizedTime | `number` | 落地翻滚动作的持续时间。 | | moveTurnClipNormalizedTime | `number` | 转身动作的持续时间。 | ## CharacterShadow `class` 负责管理 ZEPETO 角色阴影的类。 ### 属性 | 名称 | 类型 | 说明 | | ----------------- | ----------- | --------------------- | | target | `Transform` | 表示作为 transform 参考的对象。 | | autoSyncTransform | `boolean` | 决定是否将阴影位置同步到目标。 | ## CameraState `enum` 表示 `ZepetoCamera` 的状态。 | 名称 | 值 | 说明 | | ------ | - | ---------- | | Idle | 0 | 摄像机未跟随目标。 | | Follow | 1 | 摄像机正在跟随目标。 | ## ZepetoScreenStick `class` · extends [ZepetoScreenControl](./#zepetoscreencontrol) 用于处理 ZEPETO 环境中摇杆交互的类。 ### 事件 | 名称 | 类型 | 说明 | | ------------------ | --------------------- | ----------- | | OnPointerDownEvent | `UnityEvent` | 按下摇杆时触发的事件。 | | OnDragEvent | `UnityEvent` | 拖动摇杆时触发的事件。 | | OnPointerUpEvent | `UnityEvent` | 松开摇杆时触发的事件。 | ### 方法 ### OnDrag `OnDrag(eventData: PointerEventData) → void` 管理拖动行为，计算位置增量并将其限制在指定的移动范围内。 以归一化后的位置值触发 `OnDragEvent`。 会抛出 `ArgumentNullException`。 | 参数 | 类型 | 说明 | | --------- | ------------------ | ----------- | | eventData | `PointerEventData` | 与拖动事件相关的数据。 | ## ZepetoScreenControl `class` 用于在 ZEPETO 环境中创建 UI 控件的抽象类。 ### 方法 ### OnPointerDown `OnPointerDown(eventData: PointerEventData) → void` 处理用户按下 UI 控件时的事件。 | 参数 | 类型 | 说明 | | --------- | ------------------ | ------------- | | eventData | `PointerEventData` | 与指针按下事件相关的数据。 | ### OnPointerUp `OnPointerUp(eventData: PointerEventData) → void` 处理用户松开 UI 控件时的事件。 | 参数 | 类型 | 说明 | | --------- | ------------------ | ------------- | | eventData | `PointerEventData` | 与指针松开事件相关的数据。 | ## ZepetoScreenButton `class` · extends [ZepetoScreenControl](./#zepetoscreencontrol) 用于处理 ZEPETO 环境中按钮交互的类。 ### 事件 | 名称 | 类型 | 说明 | | ---------------- | ------------ | ----------- | | OnPointDownEvent | `UnityEvent` | 按下按钮时触发的事件。 | | OnPointUpEvent | `UnityEvent` | 松开按钮时触发的事件。 | ## ZepetoScreenTouchpad `class` · extends [ZepetoScreenControl](./#zepetoscreencontrol) 用于处理 ZEPETO 环境中触摸板交互的类。 ### 属性 | 名称 | 类型 | 说明 | | ----------------------------- | ---------------- | ---------------------------------- | | canvasGroupTouchPadBackground | `CanvasGroup` | 用于管理触摸板背景不透明度与交互的 Canvas Group 组件。 | | touchPadBackgroundCurve | `AnimationCurve` | 用于触摸板背景淡入淡出效果的动画曲线。 | | touchHandle | `RectTransform` | 表示触摸手柄的 `RectTransform` 组件。 | | touchHandleAnimator | `Animator` | 用于为触摸手柄制作动画的 Animator 组件。 | | touchHandleOrigin | `RectTransform` | 表示触摸手柄原始位置的 `RectTransform`。 | | touchHandleOriginAnimator | `Animator` | 用于触摸手柄原点的 Animator 组件。 | ### 事件 | 名称 | 类型 | 说明 | | ------------------ | --------------------- | ------------ | | OnPointerDownEvent | `UnityEvent` | 按下触摸板时触发的事件。 | | OnDragEvent | `UnityEvent` | 拖动触摸板时触发的事件。 | | OnPointerUpEvent | `UnityEvent` | 松开触摸板时触发的事件。 | ### 方法 ### OnPointerClick `OnPointerClick(eventData: PointerEventData) → void` 处理触摸板上的点击事件。会抛出 `ArgumentNullException`。 | 参数 | 类型 | 说明 | | --------- | ------------------ | ----------- | | eventData | `PointerEventData` | 与拖动事件相关的数据。 | ### OnDrag `OnDrag(eventData: PointerEventData) → void` 管理拖动行为，计算位置增量并将其限制在指定的移动范围内。 以归一化后的位置值触发 `OnDragEvent`。 会抛出 `ArgumentNullException`。 | 参数 | 类型 | 说明 | | --------- | ------------------ | ----------- | | eventData | `PointerEventData` | 与拖动事件相关的数据。 | ## UIZepetoPlayerControl `class` 为本地玩家角色提供基于 UI 的控制的类。 ### 方法 ### StartMoving `StartMoving() → void` 将本地玩家角色的移动标志设为 `true`。 ### Move `Move(delta: Vector2) → void` 设置本地玩家 ZEPETO 角色的移动方向。 | 参数 | 类型 | | ----- | --------- | | delta | `Vector2` | ### StopMoving `StopMoving() → void` 停止本地玩家的 ZEPETO 角色。 ### Jump `Jump() → void` 使本地玩家的 ZEPETO 角色跳跃。 ### DoubleJump `DoubleJump() → void` 使本地玩家的 ZEPETO 角色进行二段跳。 ### Update `Update() → void` 更新本地玩家 ZEPETO 角色的移动方向。 ## InputHelper `class` 用于辅助输入处理的工具类。 ### 方法 ### IsPointerOverUIObjectCurrentPosition `static IsPointerOverUIObjectCurrentPosition() → boolean` 判断指针当前是否位于 UI 对象之上。 **返回值：** `boolean` — 若指针位于 UI 对象之上，则返回 `true`。 ### IsPointerOverUIObject `static IsPointerOverUIObject(position: Vector2) → boolean` 检查屏幕上的指定位置是否位于 UI 元素之上。 | 参数 | 类型 | 说明 | | -------- | --------- | ------- | | position | `Vector2` | 屏幕上的位置。 | **返回值：** `boolean` — 若该位置位于 UI 对象之上，则返回 `true`。 ## EventReceiver `class` 负责处理 ZEPETO World 内角色相关事件或通用事件的类。 ### 事件 | 名称 | 类型 | 说明 | | -------------------------------- | ----------------------------------- | ----------------- | | OnCharacterClick (static) | `UnityEvent` | 点击角色时触发的事件。 | | OnCharacterProfileClick (static) | `UnityEvent` | 点击角色资料时触发的事件。 | | OnClick (static) | `UnityEvent` | 可用于各类交互元素的通用点击事件。 | ## TransitionBase `class` 用于定义状态机中状态之间转换的基类。 ### 属性 | 名称 | 类型 | 说明 | | --------- | ----------------------------- | ---------------------------------------------------------- | | To | `TEnum` | 转换将要到达的状态。 | | Duration | `number` | 转换从开始到结束应持续的时间（秒）。 | | Status | [StateStatus](./#statestatus) | 转换的状况。 | | IsRunning | `boolean` | 表示该转换当前是否处于 `StateStatus.Enter` 或 `StateStatus.Update` 状况。 | ### 方法 ### Check `Check() → boolean` 检查触发转换的条件是否满足。 **返回值：** `boolean` — 若转换的条件已满足，则为 `true`。 ## State `class` 表示状态机中的一个状态。 ### 属性 | 名称 | 类型 | 说明 | | ------------- | ----------------------------- | -------------- | | OnUpdateState | `Action` | 用于处理状态更新的回调函数。 | | stateType | `TEnum` | 状态的类型。 | | Status | [StateStatus](./#statestatus) | 状态的状况。 | ## Transition `class` · extends [TransitionBase\](./#transitionbase) 用于定义状态机中状态之间转换的泛型类。 ### 属性 | 名称 | 类型 | 说明 | | ---- | ------- | -------- | | From | `TEnum` | 转换的起始状态。 | ## ZepetoCharacter.LoadingStatus `enum` ZEPETO 角色的加载状态。 | 名称 | 值 | 说明 | | --------- | - | ----------- | | NotLoaded | 0 | 角色尚未开始加载过程。 | | Loading | 1 | 角色正处于加载过程中。 | | Loaded | 2 | 角色已完全加载。 | | Error | 3 | 加载过程中发生错误。 | ## PlayerControlMode `enum` | 名称 | 值 | | -------- | - | | Default | 0 | | WalkOnly | 1 | | RunOnly | 2 |