ArcartXPlayer:玩家管理对象

ArcartXPlayer

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

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

模型管理

`setModel(modelID, scale)`

设置玩家模型，会触发 PlayerModelUpdateEvent 事件，并向所有能看到该玩家的其他玩家广播模型变更

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

axPlayer.setModel("knight", 1.0);

`removeModel()`

移除玩家模型，恢复默认外观

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

axPlayer.removeModel();

`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();

动画控制

`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");

相机控制

`setThirdPerson(enable)`

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

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

axPlayer.setThirdPerson(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));

与 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");

`parseShimmer(code)`

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

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

axPlayer.parseShimmer("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