yeow-api 0.4.3 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.4.3",
+    "version": "0.6.0",
     "description": "Yeow API",
     "type": "module",
     "main": "./src/index.ts",

package/src/advancement.ts

@@ -1,27 +1,8 @@
-import { post } from './task.js';
-import type { TaskOptions } from './task.js';
+// 进度操作已上移到 `player.ts` 的 Player 实例方法（`player.grantAdvancement(...)` 等）
+// ——不再提供顶层 uuid 函数。
 
+/** 进度完成情况。 */
 export interface AdvancementProgress {
   awardedCriteria: string[];
   remainingCriteria: string[];
 }
-
-export function grant(uuid: string, key: string, options?: TaskOptions): Promise<boolean> {
-  return post<boolean>('advancement.grant', { uuid, key }, options);
-}
-
-export function revoke(uuid: string, key: string, options?: TaskOptions): Promise<boolean> {
-  return post<boolean>('advancement.revoke', { uuid, key }, options);
-}
-
-export function getProgress(uuid: string, key: string, options?: TaskOptions): Promise<AdvancementProgress | null> {
-  return post<AdvancementProgress | null>('advancement.getProgress', { uuid, key }, options);
-}
-
-export function awardCriteria(uuid: string, key: string, criteria: string, options?: TaskOptions): Promise<boolean> {
-  return post<boolean>('advancement.awardCriteria', { uuid, key, criteria }, options);
-}
-
-export function revokeCriteria(uuid: string, key: string, criteria: string, options?: TaskOptions): Promise<boolean> {
-  return post<boolean>('advancement.revokeCriteria', { uuid, key, criteria }, options);
-}

package/src/assets.ts

@@ -55,18 +55,19 @@ const readSyncImpl = (path: string, options?: FsEncoding | ReadFileOptions): Uin
 export const read = readImpl as AssetsReadFn;
 export const readSync = readSyncImpl as AssetsReadSyncFn;
 
-export async function extract(path: string, dest?: string): Promise<string> {
-  const p: Record<string, unknown> = { path };
-  if (dest) p.dest = dest;
-  const r = await _sendAssetsAsync({ t: 'extract', p }) as { path: string };
+/**
+ * 解压单文件资产到磁盘。**`dest` 必填**，基于插件数据目录（`plugins/<插件名>/`）计算，
+ * 最终目标必须位于插件目录内。返回解压后的相对服务器根目录路径。
+ */
+export async function extract(path: string, dest: string): Promise<string> {
+  const r = await _sendAssetsAsync({ t: 'extract', p: { path, dest } }) as { path: string };
   return r.path;
 }
-export function extractSync(path: string, dest?: string): string {
-  const p: Record<string, unknown> = { path };
-  if (dest) p.dest = dest;
-  return (_sendAssets({ t: 'extract', p }) as { path: string }).path;
+export function extractSync(path: string, dest: string): string {
+  return (_sendAssets({ t: 'extract', p: { path, dest } }) as { path: string }).path;
 }
 
+/** 解压目录树到磁盘。`dest` 可选（默认 `assets/<path>`），基于插件数据目录计算并限定其内。 */
 export async function extractDir(path: string, dest?: string): Promise<string> {
   const p: Record<string, unknown> = { path };
   if (dest) p.dest = dest;

package/src/block.ts

@@ -9,15 +9,16 @@ import {
   keysBlock as pdcKeys, getAllBlock as pdcGetAll,
 } from './pdc.js';
 
-/** 方块状态（Minecraft 原版键值对枚举，值统一为字符串）。 */
+/** 方块状态（Minecraft 原版键值对枚举；值为字符串 / 数字 / 布尔——按原版语义保留类型）。 */
 export interface BlockState {
-  [key: string]: string;
+  [key: string]: string | number | boolean;
 }
 
 /**
  * Block —— 方块数据描述符 + 可选的世界位置（location）。
  * 对应 Minecraft 原版的方块概念：类型 + 方块状态（键值对枚举，如
- * `facing`、`waterlogged`、`level` 等，值统一为字符串）。
+ * `facing`、`waterlogged`、`level` 等；值按原版语义保留类型——布尔 `waterlogged: false`、
+ * 数字 `level: 8`、枚举串 `facing: "north"`）。
  *
  * **静态数据语义**：`type` / `state` / `location` 均为**获取时刻的快照**，
  * 之后世界变化不会自动更新；需要最新状态请重新调用 `world.getBlock`。

package/src/bossbar.ts

@@ -1,6 +1,8 @@
-import { post } from './task.js';
+import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import { BossBarHandle } from './instance-id.js';
+import { resolveUuid } from './target.js';
+import type { PlayerTarget } from './target.js';
 
 export interface BossBarOptions {
   color?: string;
@@ -9,52 +11,102 @@ export interface BossBarOptions {
   visible?: boolean;
 }
 
-export async function createBossBar(title: string, options?: BossBarOptions, taskOptions?: TaskOptions): Promise<BossBarHandle> {
-  const h = new BossBarHandle();
-  await post('bossbar.create', { id: h.toString(), title, ...options }, taskOptions);
-  return h;
-}
+/**
+ * BossBar —— 面向玩家的血条对象（OOP）。
+ *
+ * ```js
+ * const bar = await BossBar.create('<red>Loading...</red>', { color: 'RED', progress: 0.0 });
+ * await bar.addPlayer(player);          // 接受 Player 对象或 uuid
+ * await bar.setProgress(0.5);
+ * await bar.destroy();
+ * ```
+ *
+ * 事件比对：`bar.toString()` 返回底层句柄 id（与 `inventoryClick` 等比对）。
+ * BossBar 颜色/样式/Flag 值域见 [值域附录 · 直接维护的枚举清单]。
+ */
+export class BossBar {
+  private constructor(readonly id: string) {}
 
-export function destroy(id: BossBarHandle, options?: TaskOptions): Promise<void> {
-  return post('bossbar.destroy', { id: id.toString() }, options);
-}
+  /** 创建血条（title 支持 MiniMessage）。 */
+  static async create(title: string, options?: BossBarOptions, taskOptions?: TaskOptions): Promise<BossBar> {
+    const id = new BossBarHandle().toString();
+    await post('bossbar.create', { id, title, ...options }, taskOptions);
+    return new BossBar(id);
+  }
 
-export function setTitle(id: BossBarHandle, title: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.setTitle', { id: id.toString(), title }, options);
-}
+  /** 底层句柄 id（用于事件比对）。 */
+  get handle(): string { return this.id; }
+  toString(): string { return this.id; }
 
-export function setProgress(id: BossBarHandle, progress: number, options?: TaskOptions): Promise<void> {
-  return post('bossbar.setProgress', { id: id.toString(), progress }, options);
-}
+  // ── 标题 / 进度 / 颜色 / 样式 / 可见性 ──
 
-export function setColor(id: BossBarHandle, color: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.setColor', { id: id.toString(), color }, options);
-}
+  set title(v: string) { call('bossbar.setTitle', { id: this.id, title: v }); }
+  setTitle(title: string, options?: TaskOptions): Promise<void> { return post('bossbar.setTitle', { id: this.id, title }, options); }
+  setTitleSync(title: string, options?: TaskOptions): void { call('bossbar.setTitle', { id: this.id, title }, options); }
 
-export function setStyle(id: BossBarHandle, style: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.setStyle', { id: id.toString(), style }, options);
-}
+  set progress(v: number) { call('bossbar.setProgress', { id: this.id, progress: v }); }
+  setProgress(progress: number, options?: TaskOptions): Promise<void> { return post('bossbar.setProgress', { id: this.id, progress }, options); }
+  setProgressSync(progress: number, options?: TaskOptions): void { call('bossbar.setProgress', { id: this.id, progress }, options); }
 
-export function setVisible(id: BossBarHandle, visible: boolean, options?: TaskOptions): Promise<void> {
-  return post('bossbar.setVisible', { id: id.toString(), visible }, options);
-}
+  set color(v: string) { call('bossbar.setColor', { id: this.id, color: v }); }
+  setColor(color: string, options?: TaskOptions): Promise<void> { return post('bossbar.setColor', { id: this.id, color }, options); }
+  setColorSync(color: string, options?: TaskOptions): void { call('bossbar.setColor', { id: this.id, color }, options); }
 
-export function addPlayer(id: BossBarHandle, uuid: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.addPlayer', { id: id.toString(), uuid }, options);
-}
+  set style(v: string) { call('bossbar.setStyle', { id: this.id, style: v }); }
+  setStyle(style: string, options?: TaskOptions): Promise<void> { return post('bossbar.setStyle', { id: this.id, style }, options); }
+  setStyleSync(style: string, options?: TaskOptions): void { call('bossbar.setStyle', { id: this.id, style }, options); }
 
-export function removePlayer(id: BossBarHandle, uuid: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.removePlayer', { id: id.toString(), uuid }, options);
-}
+  set visible(v: boolean) { call('bossbar.setVisible', { id: this.id, visible: v }); }
+  setVisible(visible: boolean, options?: TaskOptions): Promise<void> { return post('bossbar.setVisible', { id: this.id, visible }, options); }
+  setVisibleSync(visible: boolean, options?: TaskOptions): void { call('bossbar.setVisible', { id: this.id, visible }, options); }
 
-export function removeAll(id: BossBarHandle, options?: TaskOptions): Promise<void> {
-  return post('bossbar.removeAll', { id: id.toString() }, options);
-}
+  // ── 玩家绑定 ──
 
-export function addFlag(id: BossBarHandle, flag: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.addFlag', { id: id.toString(), flag }, options);
-}
+  /** 绑定玩家（接受 `Player` 对象或 uuid）。 */
+  addPlayer(player: PlayerTarget, options?: TaskOptions): Promise<void> {
+    return post('bossbar.addPlayer', { id: this.id, uuid: resolveUuid(player) }, options);
+  }
+  addPlayerSync(player: PlayerTarget, options?: TaskOptions): void {
+    call('bossbar.addPlayer', { id: this.id, uuid: resolveUuid(player) }, options);
+  }
+
+  /** 移除玩家（接受 `Player` 对象或 uuid）。 */
+  removePlayer(player: PlayerTarget, options?: TaskOptions): Promise<void> {
+    return post('bossbar.removePlayer', { id: this.id, uuid: resolveUuid(player) }, options);
+  }
+  removePlayerSync(player: PlayerTarget, options?: TaskOptions): void {
+    call('bossbar.removePlayer', { id: this.id, uuid: resolveUuid(player) }, options);
+  }
+
+  /** 移除全部绑定的玩家。 */
+  removeAllPlayers(options?: TaskOptions): Promise<void> {
+    return post('bossbar.removeAll', { id: this.id }, options);
+  }
+  removeAllPlayersSync(options?: TaskOptions): void {
+    call('bossbar.removeAll', { id: this.id }, options);
+  }
+
+  // ── Flags ──
+
+  addFlag(flag: string, options?: TaskOptions): Promise<void> {
+    return post('bossbar.addFlag', { id: this.id, flag }, options);
+  }
+  addFlagSync(flag: string, options?: TaskOptions): void {
+    call('bossbar.addFlag', { id: this.id, flag }, options);
+  }
+
+  removeFlag(flag: string, options?: TaskOptions): Promise<void> {
+    return post('bossbar.removeFlag', { id: this.id, flag }, options);
+  }
+  removeFlagSync(flag: string, options?: TaskOptions): void {
+    call('bossbar.removeFlag', { id: this.id, flag }, options);
+  }
 
-export function removeFlag(id: BossBarHandle, flag: string, options?: TaskOptions): Promise<void> {
-  return post('bossbar.removeFlag', { id: id.toString(), flag }, options);
+  /** 销毁血条（此后句柄失效）。 */
+  destroy(options?: TaskOptions): Promise<void> {
+    return post('bossbar.destroy', { id: this.id }, options);
+  }
+  destroySync(options?: TaskOptions): void {
+    call('bossbar.destroy', { id: this.id }, options);
+  }
 }

package/src/core.ts

@@ -64,40 +64,24 @@ export { InstanceId, BossBarHandle, InventoryHandle } from './instance-id.js';
 export { ItemStack } from './item.js';
 export type { ItemMeta, PotionEffectData, AttributeModifierData } from './item.js';
 export type { PotionEffect } from './potion.js';
-export { addPotionEffect, removePotionEffect, clearPotionEffects, getActivePotionEffects } from './potion.js';
-export { playSound, stopSound, stopAllSounds } from './sound.js';
+export { playSound } from './sound.js';
 export type { ParticleOptions } from './particle.js';
 export { spawnParticle } from './particle.js';
+export type { PlayerTarget, LivingTarget, EntityTarget } from './target.js';
+export type { AdvancementProgress } from './advancement.js';
+export { BossBar } from './bossbar.js';
+export type { BossBarOptions } from './bossbar.js';
+export { Scoreboard, Objective, Team } from './scoreboard.js';
+export type { ObjectiveInfo, TeamInfo } from './scoreboard.js';
 export { get as pdcGet, set as pdcSet, has as pdcHas, remove as pdcRemove, keys as pdcKeys, getAll as pdcGetAll,
     getRaw as pdcGetRaw, setRaw as pdcSetRaw, getAllRaw as pdcGetAllRaw,
     getBlock as pdcGetBlock, setBlock as pdcSetBlock, hasBlock as pdcHasBlock, removeBlock as pdcRemoveBlock,
     keysBlock as pdcKeysBlock, getAllBlock as pdcGetAllBlock, getBlockRaw as pdcGetBlockRaw, setBlockRaw as pdcSetBlockRaw, getAllBlockRaw as pdcGetAllBlockRaw } from './pdc.js';
-export { createBossBar, destroy as destroyBossBar,
-    setTitle as setBossBarTitle, setProgress as setBossBarProgress,
-    setColor as setBossBarColor, setStyle as setBossBarStyle,
-    setVisible as setBossBarVisible, addPlayer as addBossBarPlayer,
-    removePlayer as removeBossBarPlayer, removeAll as removeAllBossBarPlayers,
-    addFlag as addBossBarFlag, removeFlag as removeBossBarFlag } from './bossbar.js';
-export type { BossBarOptions } from './bossbar.js';
-export type { AdvancementProgress } from './advancement.js';
-export { grant as grantAdvancement, revoke as revokeAdvancement,
-    getProgress as getAdvancementProgress, awardCriteria, revokeCriteria } from './advancement.js';
 export { add as addRecipe, remove as removeRecipe, getForItem as getRecipesForItem } from './recipe.js';
-export type {
-    ObjectiveInfo, TeamInfo,
-} from './scoreboard.js';
-export { createBoard as createScoreboard, deleteBoard as deleteScoreboard,
-    createObjective, deleteObjective, getObjectives,
-    setObjectiveDisplay, getScore, setScore, resetScore,
-    createTeam, deleteTeam, getTeam, getTeams,
-    setTeamDisplayName, setTeamPrefix, setTeamSuffix, setTeamColor,
-    setTeamFriendlyFire, setTeamSeeInvisible, setTeamOption,
-    teamAddEntry, teamRemoveEntry, teamGetEntries,
-    setPlayerBoard } from './scoreboard.js';
 export { Material, getMaterials, getBlocks, getItems } from './material.js';
 export type { MaterialInfo } from './material.js';
-export { registerService, registerNativeService, request as serviceRequest, subscribe as serviceSubscribe, publish as servicePublish } from './service.js';
-export type { ServiceResult, NativeServiceResult } from './service.js';
+export { Service, PluginService, NativeService, ServiceReply, registerService, registerNativeService, getService, hasService } from './service.js';
+export type { ServiceKind, ServiceRequestOptions, ServiceResponse, NativeTerminateInfo, NativePlatforms } from './service.js';
 export { log, Logger } from './log.js';
 export type { Message } from './message.js';
 export { getEnv } from './env.js';
@@ -107,8 +91,8 @@ export type { Permission, PermissionOptions, PermissionDefault } from './permiss
 export { createWorker, Worker, onMessage, postMessage } from './worker.js';
 export type { WorkerOptions } from './worker.js';
 export {
-    stringToBytes, stringToBytesAsync,
-    bytesToString, bytesToStringAsync,
+    stringToBytes, stringToBytesSync,
+    bytesToString, bytesToStringSync,
     Gzip,
 } from './util.js';
 export type { GzipCompressor, GzipDecompressor, GzipCompressOptions, GzipDecompressOptions } from './util.js';

package/src/entity.ts

@@ -1,6 +1,7 @@
 import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
+import type { PotionEffect } from './potion.js';
 
 export interface BoundingBox {
   minX: number;
@@ -113,6 +114,15 @@ export class Entity {
 }
 
 export class LivingEntity extends Entity {
+  /** 按 uuid 查找活体实体（返回 LivingEntity；目标非活体/不存在返回 null）。 */
+  static get(uuid: string, options?: TaskOptions): Promise<LivingEntity | null> {
+    return post<{ uuid: string }>('entity.get', { uuid }, options).then((d) => (d ? new LivingEntity(d.uuid) : null));
+  }
+  static getSync(uuid: string, options?: TaskOptions): LivingEntity | null {
+    const d = call<{ uuid: string }>('entity.get', { uuid }, options);
+    return d ? new LivingEntity(d.uuid) : null;
+  }
+
   get health(): number { return call<number>('entity.getHealth', { uuid: this.uuid }); }
   set health(v: number) { call('entity.setHealth', { uuid: this.uuid, value: v }); }
   getHealth(options?: TaskOptions): Promise<number> { return post<number>('entity.getHealth', { uuid: this.uuid }, options); }
@@ -142,4 +152,38 @@ export class LivingEntity extends Entity {
   setTargetSync(target: { targetUuid: string } | { world: string; x: number; y: number; z: number; speed?: number }, options?: TaskOptions): boolean {
     return call<boolean>('entity.setTarget', { uuid: this.uuid, ...target }, options);
   }
+
+  // ── 药水效果（实体级；Player 经继承自动获得） ──
+
+  /** 添加药水效果。 */
+  addPotionEffect(effect: PotionEffect, options?: TaskOptions): Promise<void> {
+    return post('entity.addPotionEffect', { uuid: this.uuid, ...effect }, options);
+  }
+  addPotionEffectSync(effect: PotionEffect, options?: TaskOptions): void {
+    call('entity.addPotionEffect', { uuid: this.uuid, ...effect }, options);
+  }
+
+  /** 移除指定类型的药水效果。 */
+  removePotionEffect(type: string, options?: TaskOptions): Promise<void> {
+    return post('entity.removePotionEffect', { uuid: this.uuid, type }, options);
+  }
+  removePotionEffectSync(type: string, options?: TaskOptions): void {
+    call('entity.removePotionEffect', { uuid: this.uuid, type }, options);
+  }
+
+  /** 清除全部药水效果。 */
+  clearPotionEffects(options?: TaskOptions): Promise<void> {
+    return post('entity.clearPotionEffects', { uuid: this.uuid }, options);
+  }
+  clearPotionEffectsSync(options?: TaskOptions): void {
+    call('entity.clearPotionEffects', { uuid: this.uuid }, options);
+  }
+
+  /** 当前生效的药水效果列表（与输入同结构）。 */
+  getActivePotionEffects(options?: TaskOptions): Promise<PotionEffect[]> {
+    return post<PotionEffect[]>('entity.getActivePotionEffects', { uuid: this.uuid }, options);
+  }
+  getActivePotionEffectsSync(options?: TaskOptions): PotionEffect[] {
+    return call<PotionEffect[]>('entity.getActivePotionEffects', { uuid: this.uuid }, options);
+  }
 }

package/src/fs.ts

@@ -1,6 +1,6 @@
 type FsLevel = 'plugin' | 'server' | 'outer';
 
-import { stringToBytes, bytesToString } from './util.js';
+import { stringToBytesSync, bytesToStringSync } from './util.js';
 
 /** 文件编码：utf8 = 文本；base64 = 将字符串视为 Base64 编码的二进制数据。 */
 export type FsEncoding = 'utf8' | 'base64';
@@ -53,7 +53,7 @@ function _makeUtf8StreamDecoder() {
     if ((b & 0xE0) === 0xC0) return 2;
     if ((b & 0xF0) === 0xE0) return 3;
     if ((b & 0xF8) === 0xF0) return 4;
-    return 1; // 非法起始字节：交给 bytesToString 以替换字符处理
+    return 1; // 非法起始字节：交给 bytesToStringSync 以替换字符处理
   };
 
   return {
@@ -84,12 +84,12 @@ function _makeUtf8StreamDecoder() {
 
       pending = cut === buf.length ? new Uint8Array(0) : buf.slice(cut);
       const complete = cut === buf.length ? buf : buf.subarray(0, cut);
-      return complete.length ? bytesToString(complete) : null;
+      return complete.length ? bytesToStringSync(complete) : null;
     },
     /** EOF：把剩余的不完整序列交给 Java 解码（通常产出 U+FFFD）。 */
     flush(): string | null {
       if (!pending.length) return null;
-      const s = bytesToString(pending);
+      const s = bytesToStringSync(pending);
       pending = new Uint8Array(0);
       return s;
     },
@@ -394,7 +394,7 @@ function _makeWriteStream(
   const check = () => { if (closed) throw new Error('write stream closed'); };
   const toBytes = (chunk: Uint8Array | string): Uint8Array => {
     if (typeof chunk !== 'string') return chunk; // Uint8Array 始终按原始字节写入
-    return encoding === 'base64' ? Uint8Array.fromBase64(chunk) : stringToBytes(chunk);
+    return encoding === 'base64' ? Uint8Array.fromBase64(chunk) : stringToBytesSync(chunk);
   };
   return {
     encoding,

package/src/global.d.ts

@@ -29,12 +29,43 @@ declare global {
     headers: { get(name: string): string | undefined };
     text(): Promise<string>;
     json(): Promise<any>;
+    base64(): Promise<string>;
+    bytes(): Promise<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
   }
   function fetch(
     url: string,
-    init?: { method?: string; headers?: Record<string, string>; body?: string | null }
+    init?: { method?: string; headers?: Record<string, string>; body?: string | Uint8Array | null; encoding?: 'utf8' | 'base64'; timeout?: number }
   ): Promise<YeowResponse>;
 
+  // ── TextEncoder / TextDecoder（utf-8，polyfill 注入；同步 API）──
+  interface TextEncoder {
+    readonly encoding: string;
+    encode(input?: string): Uint8Array;
+  }
+  const TextEncoder: {
+    new (encoding?: string): TextEncoder;
+    prototype: TextEncoder;
+  };
+
+  interface TextDecoder {
+    readonly encoding: string;
+    decode(input?: ArrayBuffer | ArrayBufferView): string;
+  }
+  const TextDecoder: {
+    new (encoding?: string): TextDecoder;
+    prototype: TextDecoder;
+  };
+
+  // ── performance（高精度单调时间）──
+  interface Performance {
+    /** 相对上下文起点的毫秒数（单调、亚毫秒精度）。 */
+    now(): number;
+    /** 上下文创建时的 epoch 毫秒。 */
+    readonly timeOrigin: number;
+  }
+  var performance: Performance;
+
   function setTimeout(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): string;
   function clearTimeout(id: string): void;
   function setInterval(handler: (...args: any[]) => void, timeout?: number, ...args: any[]): string;

package/src/http.ts

@@ -40,7 +40,7 @@ export interface RequestOptions {
   encoding?: 'utf8' | 'base64';
   /**
    * 响应体形态：缺省 `Uint8Array`（原始字节，可在收到后自行解码，
-   * 如 `bytesToString(body)` 或 `new TextDecoder().decode(body)`）；
+   * 如 `bytesToStringSync(body)` 或 `new TextDecoder().decode(body)`）；
    * `'utf8'` → UTF-8 字符串；`'base64'` → base64 字符串（原样返回，不解码）。
    */
   responseEncoding?: 'utf8' | 'base64';
@@ -115,7 +115,7 @@ _registerCallback(() => {
  * 请求体与 `fs.writeFile` 同语义（`body: string | Uint8Array`，字符串按
  * `encoding` 解释）；响应体默认 `Uint8Array`（原始字节），可用
  * `responseEncoding` 直接得到字符串（`'utf8'` / `'base64'`），也可在收到后
- * 用 `bytesToString` 自行解码。`timeout` 指定超时毫秒数（连接与读取，缺省
+ * 用 `bytesToStringSync` 自行解码。`timeout` 指定超时毫秒数（连接与读取，缺省
  * 运行时默认）。
  */
 export function request(url: string, opts: RequestOptions = {}): Promise<HttpResponse> {

package/src/inventory.ts

@@ -2,6 +2,8 @@ import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import type { ItemStack } from './item.js';
 import { InstanceId } from './instance-id.js';
+import { resolveUuid } from './target.js';
+import type { PlayerTarget } from './target.js';
 
 /**
  * Inventory —— 统一容器抽象，三种持有者：
@@ -141,9 +143,9 @@ export class Inventory {
 
   // ── 自定义 Inventory 专属 ─────────────────────────────────────────
 
-  /** 为玩家打开（自定义 Inventory）。 */
-  open(uuid: string, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('inventory.open', { ...this.address(), uuid }, options);
+  /** 为玩家打开（自定义 Inventory；接受 `Player` 对象或 uuid）。 */
+  open(player: PlayerTarget, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.open', { ...this.address(), uuid: resolveUuid(player) }, options);
   }
 
   /** 关闭所有查看者（自定义 Inventory）。 */
@@ -151,9 +153,9 @@ export class Inventory {
     return post<boolean>('inventory.close', this.address(), options);
   }
 
-  /** 仅关闭指定玩家（自定义 Inventory）。 */
-  closePlayer(uuid: string, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('inventory.closePlayer', { ...this.address(), uuid }, options);
+  /** 仅关闭指定玩家（自定义 Inventory；接受 `Player` 对象或 uuid）。 */
+  closePlayer(player: PlayerTarget, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('inventory.closePlayer', { ...this.address(), uuid: resolveUuid(player) }, options);
   }
 
   /** 当前查看者 uuid 列表（自定义 Inventory）。 */

package/src/material.ts

@@ -55,4 +55,12 @@ export const Material = {
   isAirSync(type: string, options?: TaskOptions): boolean {
     return call<boolean>('material.isAir', { type }, options);
   },
+
+  /** 最大耐久（非耐用品返回 0；未知类型抛错）。 */
+  getMaxDurability(type: string, options?: TaskOptions): Promise<number> {
+    return post<number>('material.getMaxDurability', { type }, options);
+  },
+  getMaxDurabilitySync(type: string, options?: TaskOptions): number {
+    return call<number>('material.getMaxDurability', { type }, options);
+  },
 };

package/src/player.ts

@@ -1,10 +1,12 @@
 import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
+import { LivingEntity } from './entity.js';
 import { Location, LocationData } from './location.js';
 import type { ItemStack } from './item.js';
 import { Block } from './block.js';
 import type { Message } from './message.js';
 import type { Permission } from './permission.js';
+import type { AdvancementProgress } from './advancement.js';
 import { Inventory } from './inventory.js';
 import {
   get as pdcGet, set as pdcSet, has as pdcHas, remove as pdcRemove,
@@ -16,7 +18,7 @@ interface PlayerData {
   name: string;
 }
 
-export class Player {
+export class Player extends LivingEntity {
   static get(identifier: string, options?: TaskOptions): Promise<Player | null> {
     return post<PlayerData>('player.get', { identifier }, options).then((d) => (d ? new Player(d.uuid, d.name) : null));
   }
@@ -31,7 +33,10 @@ export class Player {
     return call<PlayerData[]>('player.getAll', {}, options).map((r) => new Player(r.uuid, r.name));
   }
 
-  constructor(public readonly uuid: string, private _name?: string) {}
+  // uuid 由 Entity 基类持有（readonly）；本类扩展玩家特有字段。
+  constructor(uuid: string, private _name?: string) {
+    super(uuid);
+  }
 
   /** 玩家名。未提供时首次访问惰性同步获取并缓存（仅一次往返）。 */
   get name(): string {
@@ -153,6 +158,20 @@ export class Player {
   playSoundSync(sound: string, volume?: number, pitch?: number, options?: TaskOptions): void {
     call('player.playSound', { uuid: this.uuid, sound, volume, pitch }, options);
   }
+  /** 停止播放指定音效。 */
+  stopSound(sound: string, options?: TaskOptions): Promise<void> {
+    return post('player.stopSound', { uuid: this.uuid, sound }, options);
+  }
+  stopSoundSync(sound: string, options?: TaskOptions): void {
+    call('player.stopSound', { uuid: this.uuid, sound }, options);
+  }
+  /** 停止该玩家所有音效。 */
+  stopAllSounds(options?: TaskOptions): Promise<void> {
+    return post('player.stopAllSounds', { uuid: this.uuid }, options);
+  }
+  stopAllSoundsSync(options?: TaskOptions): void {
+    call('player.stopAllSounds', { uuid: this.uuid }, options);
+  }
   giveExp(amount: number, options?: TaskOptions): Promise<void> { return post('player.giveExp', { uuid: this.uuid, amount }, options); }
   giveExpSync(amount: number, options?: TaskOptions): void { call('player.giveExp', { uuid: this.uuid, amount }, options); }
   /** 检查权限（经 Yeow 权限检查：`permissionCheck` 事件优先，无处理时回退 Bukkit）。node 可为权限节点对象。 */
@@ -169,6 +188,41 @@ export class Player {
   performCommandSync(cmd: string, options?: TaskOptions): boolean {
     return call<boolean>('player.performCommand', { uuid: this.uuid, command: cmd.replace(/^\//, '') }, options);
   }
+  /** 授予进度全部条件。 */
+  grantAdvancement(key: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('advancement.grant', { uuid: this.uuid, key }, options);
+  }
+  grantAdvancementSync(key: string, options?: TaskOptions): boolean {
+    return call<boolean>('advancement.grant', { uuid: this.uuid, key }, options);
+  }
+  /** 撤销进度全部条件。 */
+  revokeAdvancement(key: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('advancement.revoke', { uuid: this.uuid, key }, options);
+  }
+  revokeAdvancementSync(key: string, options?: TaskOptions): boolean {
+    return call<boolean>('advancement.revoke', { uuid: this.uuid, key }, options);
+  }
+  /** 查询进度完成情况。 */
+  getAdvancementProgress(key: string, options?: TaskOptions): Promise<AdvancementProgress | null> {
+    return post<AdvancementProgress | null>('advancement.getProgress', { uuid: this.uuid, key }, options);
+  }
+  getAdvancementProgressSync(key: string, options?: TaskOptions): AdvancementProgress | null {
+    return call<AdvancementProgress | null>('advancement.getProgress', { uuid: this.uuid, key }, options);
+  }
+  /** 授予进度单个条件。 */
+  awardCriteria(key: string, criteria: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('advancement.awardCriteria', { uuid: this.uuid, key, criteria }, options);
+  }
+  awardCriteriaSync(key: string, criteria: string, options?: TaskOptions): boolean {
+    return call<boolean>('advancement.awardCriteria', { uuid: this.uuid, key, criteria }, options);
+  }
+  /** 撤销进度单个条件。 */
+  revokeCriteria(key: string, criteria: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('advancement.revokeCriteria', { uuid: this.uuid, key, criteria }, options);
+  }
+  revokeCriteriaSync(key: string, criteria: string, options?: TaskOptions): boolean {
+    return call<boolean>('advancement.revokeCriteria', { uuid: this.uuid, key, criteria }, options);
+  }
   teleport(loc: Location, options?: TaskOptions): Promise<void> { return post('player.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
   teleportSync(loc: Location, options?: TaskOptions): void { call('player.teleport', { uuid: this.uuid, ...loc.toObject() }, options); }
   /** 向玩家发送假方块变化（仅客户端视觉，不改变真实世界）。block 为 Block 对象或字符串（同 world.setBlock，字符串无状态）。 */
@@ -236,14 +290,6 @@ export class Player {
     return call<boolean>('player.setPlayerListName', { uuid: this.uuid, name }, options);
   }
 
-  /** 设置客户端世界边界（传 null 重置为服务端边界；centerX/centerZ 可选，指定边界中心）。 */
-  setBorder(size: number | null, centerX?: number, centerZ?: number, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('player.setBorder', { uuid: this.uuid, size, centerX, centerZ }, options);
-  }
-  setBorderSync(size: number | null, centerX?: number, centerZ?: number, options?: TaskOptions): boolean {
-    return call<boolean>('player.setBorder', { uuid: this.uuid, size, centerX, centerZ }, options);
-  }
-
   // ── PDC（玩家持久数据） ──
 
   /** 读取并 JSON 反序列化（无值返回 null；旧数据非 JSON 时原样返回字符串）。 */