ArcartXPlayer:玩家管理对象

ArcartXPlayer

ArcartXPlayer 继承自 ArcartXEntity，是ArcartX对玩家的完整管理对象。
通过 ArcartXAPI.getEntityManager().getPlayer(player) 获取。
除了继承自 ArcartXEntity 的所有方法外，还提供了大量玩家专属功能。
本类的方法分为两种发送模式：
- 点对点 — 仅向该玩家自身的客户端发送数据包（如相机、着色器、特效等）
- 广播 — 向所有能看到该玩家的客户端发送数据包（如模型、控制器、状态、额外模型、时装、变体、动画包等）

模型管理、动画控制（setState / setController）、额外模型、时装、模型变体、动画包等方法是广播模式，会同步给所有能看到该玩家的客户端。相机、着色器、天空盒、特效等方法是点对点模式，仅发送给该玩家自身。

公开属性

ArcartXPlayer 自身声明的公开属性如下（继承自父类的属性见 ArcartXEntity 页）：

player: Player — 该对象对应的 Bukkit 玩家实例（构造时传入，只读）
encryptor: AESEncryptor? — 与客户端通信使用的 AES 加密器，可能为 null
key: String? — 通信密钥，可能为 null
alt: boolean — 是否为小号（alt）客户端标记
callbacks: Map<String, CallBack> — 回调映射表，用于客户端异步回调
crc64: Set<Long> — 已发送资源的 CRC64 校验集合
area: Area? — 玩家当前所处的区域，可能为 null
playerModel: String — 当前玩家模型ID（只读，通过 setModel 更新）
playerModelScale: double — 当前玩家模型缩放比例（只读）
variant: PlayerModelVariant — 当前玩家模型变体（只读，DEFAULT_BBMODEL / CUSTOM_BBMODEL）
animationPackId: String — 当前玩家动画包ID（只读，空字符串表示无）
sentResource: boolean — 是否已向该玩家发送资源
jumpTime: long — 上一次跳跃的时间戳

模型管理

`setModel(modelID, scale)`

设置玩家模型，会触发 PlayerModelUpdateEvent 事件，并向所有能看到该玩家的其他玩家广播模型变更
重写自 ArcartXEntity.setModel，额外记录 playerModel / playerModelScale 并派发玩家专属事件

参数：
- modelID: String — 模型ID
- scale: double — 模型缩放比例
返回值：无
调用示例

axPlayer.setModel("knight", 1.0);

`removeModel()`

移除玩家模型，恢复默认外观，并重置 playerModel 与 playerModelScale
重写自 ArcartXEntity.removeModel

参数：无
返回值：无
调用示例

axPlayer.removeModel();

`setDefaultModel(scale)`

将玩家模型设置为默认玩家模型（__default_player__），并将变体切换为 DEFAULT_BBMODEL
会触发 PlayerVariantChangeEvent 事件（若被取消则不生效），并广播变体变更
DEFAULT_BBMODEL 变体会叠加原版附属物（盔甲/披风/鞘翅/时装）

参数：scale: double — 模型缩放比例（默认 1.0）
返回值：无
调用示例

axPlayer.setDefaultModel(1.0);

`setCustomModel(modelID, scale)`

将玩家模型设置为自定义模型，并将变体切换为 CUSTOM_BBMODEL
会触发 PlayerVariantChangeEvent 事件（若被取消则不生效），并广播变体变更

参数：
- modelID: String — 模型ID
- scale: double — 模型缩放比例（默认 1.0）
返回值：无
调用示例

axPlayer.setCustomModel("knight", 1.0);

`tryModel(modelID, scale, time)`

临时将玩家模型切换为指定模型，持续 time 毫秒后自动恢复为原本的 playerModel
不会修改 playerModel 记录，也不会触发变体/模型事件（仅底层临时切换）

参数：
- modelID: String — 临时模型ID
- scale: double — 模型缩放比例
- time: long — 临时持续时间（毫秒），到时后恢复原模型
返回值：无
调用示例

axPlayer.tryModel("hurt_pose", 1.0, 1000);

`addExtraModel(locator, modelID)`

为玩家添加额外模型，挂载在指定定位器上

参数：
- locator: String — 定位器名称
- modelID: String — 模型ID
返回值：无
调用示例

axPlayer.addExtraModel("back_extra", "wings_model");

`removeExtraModel(locator)`

移除玩家指定定位器上的额外模型

参数：locator: String — 定位器名称
返回值：无
调用示例

axPlayer.removeExtraModel("back_extra");

`clearExtraModels()`

清除玩家所有额外模型

参数：无
返回值：无
调用示例

axPlayer.clearExtraModels();

时装管理

时装为运行时内存态（不落库）。CostumeSlot 枚举可选值：HEAD / BODY / LEGS / FEET / DECORATION。装备套装（equipSuit）与装备单件（equipCostume）互斥：装备套装会清空单件槽位，装备单件会清除套装。相关操作会触发 PlayerCostumeChangeEvent 事件，若事件被取消则不生效。

`equipSuit(modelID, hide)`

为玩家装备整套时装，并清空所有单件时装槽位

参数：
- modelID: String — 时装套装模型ID
- hide: boolean — 是否隐藏原版对应部位（默认 true）
返回值：无
调用示例

axPlayer.equipSuit("costume_suit_a", true);

`equipCostume(slot, modelID, hide)`

为玩家在指定槽位装备单件时装，并清除已装备的套装

参数：
- slot: CostumeSlot — 时装槽位（HEAD / BODY / LEGS / FEET / DECORATION）
- modelID: String — 时装模型ID
- hide: boolean — 是否隐藏原版对应部位（默认 false）
返回值：无
调用示例

axPlayer.equipCostume(ArcartXPlayer.CostumeSlot.HEAD, "hat_a", false);

`removeCostume(slot)`

移除玩家指定槽位的单件时装

参数：slot: CostumeSlot — 时装槽位
返回值：无
调用示例

axPlayer.removeCostume(ArcartXPlayer.CostumeSlot.HEAD);

`clearCostume()`

清除玩家所有时装（套装与单件槽位）

参数：无
返回值：无
调用示例

axPlayer.clearCostume();

动画控制

`setAnimationPack(packId)`

为玩家设置动画包，会触发 PlayerAnimationPackChangeEvent 事件（若被取消则不生效），并广播给观察者

参数：packId: String — 动画包ID
返回值：无
调用示例

axPlayer.setAnimationPack("knight_anim");

`clearAnimationPack()`

清除玩家的动画包（将 animationPackId 置空），会触发 PlayerAnimationPackChangeEvent 事件（若被取消则不生效）

参数：无
返回值：无
调用示例

axPlayer.clearAnimationPack();

`playFirstPersonAnimationByTime(animation, speed, keepTime)`

为玩家播放第一人称动画，按持续时间控制

参数：
- animation: String — 动画名称
- speed: double — 播放速度
- keepTime: int — 持续时间（毫秒）
返回值：无
调用示例

axPlayer.playFirstPersonAnimationByTime("slash", 1.0, 500);

`playFirstPersonAnimationByCountOf(animation, speed, count)`

为玩家播放第一人称动画，按播放次数控制

参数：
- animation: String — 动画名称
- speed: double — 播放速度
- count: int — 播放次数
返回值：无
调用示例

axPlayer.playFirstPersonAnimationByCountOf("swing", 1.5, 3);

`setState(controller, state)`

设置玩家动作控制器的状态

参数：
- controller: String — 控制器名称
- state: String — 状态名称
返回值：无
调用示例

axPlayer.setState("combat", "attack_1");

`setState(controller, state, speed)`

设置玩家动作控制器的状态，指定播放速度

参数：
- controller: String — 控制器名称
- state: String — 状态名称
- speed: double — 播放速度
返回值：无
调用示例

axPlayer.setState("combat", "attack_1", 2.0);

`setState(controller, state, speed, moveBreak)`

设置玩家动作控制器的状态，指定播放速度和移动打断时间

参数：
- controller: String — 控制器名称
- state: String — 状态名称
- speed: double — 播放速度
- moveBreak: long — 移动打断时间（毫秒），-1为不打断
返回值：无
调用示例

axPlayer.setState("combat", "heavy_attack", 1.0, 2000);

`setController(controller)`

为玩家设置动作控制器

参数：controller: String — 控制器配置ID
返回值：无
调用示例

axPlayer.setController("combat_controller");

飞行状态

`updateFlyingState()`

轮询检测玩家飞行态，若相比上次发生变化则按 seenBy 广播给观察者
用于同步飞行态（原版不会向其他玩家同步 abilities.flying），一般由内部每 tick 调用

参数：无
返回值：无
调用示例

axPlayer.updateFlyingState();

相机控制

`setThirdPerson(enable)`

将玩家设置为第三人称视角

参数：enable: boolean — true 设置为第三人称，false 设置为第一人称
返回值：无
调用示例

axPlayer.setThirdPerson(true);

`setViewLock(enable)`

设置视角锁定开关（开启时锁定为第三人称，关闭时解除锁定）
等价于 setViewLockMode，enable 为 true 时使用模式 2，false 时使用模式 0

参数：enable: boolean — true 锁定视角，false 解除锁定
返回值：无
调用示例

axPlayer.setViewLock(true);

`setViewLockMode(mode)`

设置视角锁定模式

参数：mode: int — 锁定模式（0-关闭，1-强制锁定第一人称，2-强制锁定第三人称）
返回值：无
调用示例

axPlayer.setViewLockMode(2);

`setCameraFromPreset(id)`

从预设配置设置玩家相机

参数：id: String — 相机预设配置ID
返回值：无
调用示例

axPlayer.setCameraFromPreset("idle");

`setCameraLocation(offsetX, offsetY, offsetZ, freeView)`

设置玩家相机的偏移位置

参数：
- offsetX: double — X轴偏移
- offsetY: double — Y轴偏移
- offsetZ: double — Z轴偏移
- freeView: boolean — 是否允许自由视角
返回值：无
调用示例

axPlayer.setCameraLocation(0, 2.0, -5.0, true);

`startSceneCamera(sceneId)`

开始播放场景相机

参数：sceneId: String — 场景相机配置ID
返回值：无
调用示例

axPlayer.startSceneCamera("intro_scene");

`stopSceneCamera()`

停止场景相机播放

参数：无
返回值：无
调用示例

axPlayer.stopSceneCamera();

着色器与天空盒

`enableShader(shader)`

为玩家启用后处理着色器

参数：shader: String — 着色器名称
返回值：无
调用示例

axPlayer.enableShader("blur");

`disableShader()`

关闭玩家的着色器效果

参数：无
返回值：无
调用示例

axPlayer.disableShader();

`setSkyTexture(texturePath, forceNoCloud)`

为玩家设置自定义天空盒贴图

参数：
- texturePath: String — 天空盒贴图资源路径
- forceNoCloud: boolean — 是否强制隐藏云层
返回值：无
调用示例

axPlayer.setSkyTexture("sky/night.png", true);

`clearSkyTexture()`

清除玩家的自定义天空盒，恢复默认天空

参数：无
返回值：无
调用示例

axPlayer.clearSkyTexture();

`setClientTitle(text)`

设置玩家客户端的标题文本

参数：text: String — 标题文本
返回值：无
调用示例

axPlayer.setClientTitle("欢迎来到冒险世界");

特效

以下特效方法均为点对点发送，仅发送给该玩家自身的客户端。如果你需要让周围所有玩家都看到特效，请使用 ArcartXEffectManager 的范围广播方法。

`spawnBedrockParticle(identifier, particleID, effectPosition)`

在玩家客户端生成基岩粒子效果

参数：
- identifier: String — 粒子标识符
- particleID: String — 粒子ID
- effectPosition: EffectPosition — 特效位置
返回值：无
调用示例

axPlayer.spawnBedrockParticle("my_particle", "flame",
    EffectPosition.followEntity(player));

存在一个已弃用的旧重载 spawnBedrockParticle(id, x, y, z, yaw, pitch)（@Deprecated），请改用上面的 spawnBedrockParticle(identifier, particleID, effectPosition)。

与 ArcartXEffectManager.spawnBedrockParticle 的区别：

ArcartXPlayer.spawnBedrockParticle — 点对点，仅该玩家自身可见
ArcartXEffectManager.Entity.spawnBedrockParticle — 范围广播，所有能看到该实体的玩家可见
ArcartXEffectManager.World.spawnBedrockParticle — 范围广播，指定位置128格内所有玩家可见

选择哪个取决于你的需求：如果粒子只需要一个玩家看到，用Player版本；如果需要所有人看到（如技能特效），用EffectManager版本。

`addWorldTexture(id, builder, effectPosition)`

在玩家客户端添加世界贴图

参数：
- id: String — 贴图唯一标识
- builder: WorldTextureBuilder — 贴图构建器
- effectPosition: EffectPosition — 特效位置
返回值：无
调用示例

WorldTextureBuilder builder = new WorldTextureBuilder()
    .setTexture("effects/magic_circle.png", true, true)
    .setSize(256.0, 256.0)
    .setLifeTime(-1);
axPlayer.addWorldTexture("magic_circle", builder,
    EffectPosition.followEntity(player, 0, 0, 0, 0, 0, 0, true, true));

与 ArcartXEffectManager.spawnWorldTextureEffect 的区别：

ArcartXPlayer.addWorldTexture — 点对点，仅该玩家自身可见
ArcartXEffectManager.spawnWorldTextureEffect — 范围广播，周围所有玩家可见

`removeWorldTexture(id)`

移除玩家客户端的世界贴图

参数：id: String — 贴图唯一标识
返回值：无
调用示例

axPlayer.removeWorldTexture("magic_circle");

`playBlockAnimation(x, y, z, animation, speed, transitionTime, keepTime)`

在玩家客户端播放方块动画

参数：
- x y z: int — 方块坐标
- animation: String — 动画名称
- speed: double — 播放速度
- transitionTime: int — 过渡时间（毫秒）
- keepTime: long — 持续时间（毫秒）
返回值：无
调用示例

axPlayer.playBlockAnimation(100, 64, 200, "open", 1.0, 5, 3000);

`spawnHammerCrackEffect(x, y, z, radius, depth, in, keep, out, mode)`

在玩家客户端生成锤击裂纹特效

参数：
- x y z: int — 中心坐标
- radius: float — 裂纹半径
- depth: float — 裂纹深度
- in: int — 淡入时间（毫秒）
- keep: int — 保持时间（毫秒）
- out: int — 淡出时间（毫秒）
- mode: int — 裂纹模式
返回值：无
调用示例

axPlayer.spawnHammerCrackEffect(100, 64, 200, 3.0f, 1.0f, 200, 1000, 500, 0);

伤害显示

`addDamageDisplay(damageDisplayConfigId, x, y, z, damage)`

在指定坐标为玩家显示伤害数字

参数：
- damageDisplayConfigId: String — 伤害显示配置ID
- x y z: double — 显示坐标
- damage: double — 伤害数值
返回值：无
调用示例

axPlayer.addDamageDisplay("critical", 100.0, 65.0, 200.0, 999.0);

`addDamageDisplay(damageDisplayConfigId, target, damage)`

在目标实体位置为玩家显示伤害数字

参数：
- damageDisplayConfigId: String — 伤害显示配置ID
- target: Entity — 目标实体
- damage: double — 伤害数值
返回值：无
调用示例

axPlayer.addDamageDisplay("default", targetEntity, 50.0);

与 ArcartXEntity.broadcastDamageDisplay 的区别：

ArcartXPlayer.addDamageDisplay — 点对点，仅该玩家自身可见
ArcartXEntity.broadcastDamageDisplay — 范围广播，所有能看到该实体的玩家可见
ArcartXEntity.sendDamageDisplayToPlayers — 指定列表，仅列表中的玩家可见

路标管理

`addWayPoint(id, title, waypointConfigId, x, y, z)`

为玩家添加一个路标

参数：
- id: String — 路标唯一标识
- title: String — 路标显示标题
- waypointConfigId: String — 路标配置ID
- x y z: double — 路标坐标
返回值：无
调用示例

axPlayer.addWayPoint("quest_1", "任务目标", "default", 100.0, 64.0, 200.0);

`deleteWayPoint(id, regex)`

删除玩家的路标

参数：
- id: String — 路标标识
- regex: boolean — 是否使用正则匹配（默认false）
返回值：无
调用示例

axPlayer.deleteWayPoint("quest_1");

`clearWayPoint()`

清除玩家的所有路标

参数：无
返回值：无
调用示例

axPlayer.clearWayPoint();

额外槽位管理

`setSlotItemStack(slotID, itemStack)`

设置额外槽位的物品，同时更新数据库、客户端显示，并触发 PlayerExtraSlotUpdateEvent 事件和更新脚本

参数：
- slotID: String — 槽位ID
- itemStack: ItemStack — 物品
返回值：无
调用示例

axPlayer.setSlotItemStack("ring_1", itemStack);

`setSlotItemStackOnlyClient(slotID, itemStack)`

仅更新客户端显示的槽位物品，不写入数据库

参数：
- slotID: String — 槽位ID
- itemStack: ItemStack — 物品
返回值：无
调用示例

axPlayer.setSlotItemStackOnlyClient("preview_slot", previewItem);

`removeSlotItemStackOnlyClient(slotID, startWith)`

仅从客户端移除槽位物品显示

参数：
- slotID: String — 槽位ID
- startWith: boolean — 是否匹配以该ID开头的所有槽位
返回值：无
调用示例

axPlayer.removeSlotItemStackOnlyClient("temp_", true); // 移除所有temp_开头的槽位

`getSlotItemStack(slotID)`

获取额外槽位中的物品

参数：slotID: String — 槽位ID
返回值：ItemStack? — 物品对象，可能为null
调用示例

ItemStack item = axPlayer.getSlotItemStack("ring_1");

`syncSlotCacheToClient()`

将所有槽位缓存同步到客户端，通常在玩家重新连接时使用

参数：无
返回值：无
调用示例

axPlayer.syncSlotCacheToClient();

物品冷却

`setTagCooldown(tag, time)`

设置物品冷却标签的冷却时间

参数：
- tag: String — 冷却标签
- time: long — 冷却时间（毫秒）
返回值：无
调用示例

axPlayer.setTagCooldown("skill_1", 3000); // 3秒冷却

`getTagCooldown(tag)`

获取物品冷却标签的剩余冷却时间

参数：tag: String — 冷却标签
返回值：long — 剩余冷却时间（毫秒），0表示已冷却完毕
调用示例

long remaining = axPlayer.getTagCooldown("skill_1");

音效

`playSoundForSelf(resourcePath, soundCategory, pitch, keepTime)`

为玩家自身播放音效

参数：
- resourcePath: String — 音效资源路径
- soundCategory: String — 音效类别
- pitch: float — 音调
- keepTime: int — 持续时间（毫秒）
返回值：无
调用示例

axPlayer.playSoundForSelf("sounds/ui_click.ogg", "master", 1.0f, 1000);

其他功能

`sendCustomPacket(id, data...)`

向玩家客户端发送自定义数据包

参数：
- id: String — 数据包ID
- data: String... — 数据内容（可变参数）
返回值：无
调用示例

axPlayer.sendCustomPacket("my_plugin:update", "key1", "value1");

`parseAria(code)`

在玩家客户端执行Aria脚本代码

参数：code: String — Aria脚本代码
返回值：无
调用示例

axPlayer.parseAria("Chat.open(\"Hello!\")");

`sendChatCard(cardID, cardData)`

向玩家发送聊天卡片消息

参数：
- cardID: String — 卡片配置ID
- cardData: Map<String, String> — 卡片数据
返回值：无
调用示例

Map<String, String> data = new HashMap<>();
data.put("title", "任务完成");
data.put("reward", "100金币");
axPlayer.sendChatCard("quest_complete", data);

ArcartXPlayer:玩家管理对象

On this page