yeow-api 0.4.2 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.4.2",
+    "version": "0.5.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

@@ -57,43 +57,27 @@ export { assets, read as assetsRead, readSync as assetsReadSync,
 export { path } from './path.js';
 export { createReadStream, createWriteStream } from './fs.js';
 export type { ReadStream, WriteStream, ReadStreamOptions, WriteStreamOptions } from './fs.js';
-export { listen, respond, close, request, requestSync } from './http.js';
-export type { RespondOptions } from './http.js';
+export { listen, respond, close, request } from './http.js';
+export type { RespondOptions, RequestOptions, HttpResponse } from './http.js';
 export { logError } from './log-error.js';
 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';
@@ -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,34 @@ 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?: Uint8Array): string;
+  }
+  const TextDecoder: {
+    new (encoding?: string): TextDecoder;
+    prototype: TextDecoder;
+  };
+
   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

@@ -22,6 +22,42 @@ export interface RespondOptions {
   headers?: Record<string, string>;
 }
 
+/** HTTP 请求选项（request）。 */
+export interface RequestOptions {
+  /** HTTP 方法（默认 `"GET"`）。 */
+  method?: string;
+  /** 请求头。 */
+  headers?: Record<string, string>;
+  /**
+   * 请求体（与 `fs.writeFile` 同语义）：`Uint8Array` 直接作为二进制；
+   * 字符串按 `encoding` 解释——缺省 UTF-8 文本，`'base64'` 时视为 base64 编码的二进制。
+   */
+  body?: string | Uint8Array;
+  /**
+   * 请求体（body 为字符串时）解释：`'utf8'`（默认）文本 / `'base64'` base64 二进制
+   * （与 `fs.writeFile` 同语义）。
+   */
+  encoding?: 'utf8' | 'base64';
+  /**
+   * 响应体形态：缺省 `Uint8Array`（原始字节，可在收到后自行解码，
+   * 如 `bytesToStringSync(body)` 或 `new TextDecoder().decode(body)`）；
+   * `'utf8'` → UTF-8 字符串；`'base64'` → base64 字符串（原样返回，不解码）。
+   */
+  responseEncoding?: 'utf8' | 'base64';
+  /** 超时（毫秒）；缺省运行时默认（连接 5s / 读取 10s）。 */
+  timeout?: number;
+}
+
+/** HTTP 响应（request）。 */
+export interface HttpResponse {
+  /** HTTP 状态码。 */
+  status: number;
+  /** 响应头（键小写）。 */
+  headers: Record<string, string>;
+  /** 响应体：缺省 `Uint8Array`；`encoding: 'utf8' | 'base64'` 时为字符串。 */
+  body: string | Uint8Array;
+}
+
 function _sendHttp(payload: Record<string, unknown>): HttpResult {
   const r = $send('http', payload);
   if (!r) return {};
@@ -75,25 +111,49 @@ _registerCallback(() => {
 
 /**
  * 异步 HTTP 请求（不阻塞 JS 线程）——底层走 `http:requestAsync` 通道。
- * 推荐用于事件处理器与高频场景。需要同步阻塞返回的用 `requestSync`。
+ *
+ * 请求体与 `fs.writeFile` 同语义（`body: string | Uint8Array`，字符串按
+ * `encoding` 解释）；响应体默认 `Uint8Array`（原始字节），可用
+ * `responseEncoding` 直接得到字符串（`'utf8'` / `'base64'`），也可在收到后
+ * 用 `bytesToStringSync` 自行解码。`timeout` 指定超时毫秒数（连接与读取，缺省
+ * 运行时默认）。
  */
-export function request(url: string, opts: Record<string, unknown> = {}): Promise<HttpResult> {
+export function request(url: string, opts: RequestOptions = {}): Promise<HttpResponse> {
   return new Promise((resolve, reject) => {
     const cbId = _registerCallback((result: unknown) => {
-      if ((result as any)?.err) reject(new Error((result as any).err));
-      else resolve(result as HttpResult);
+      const r = result as HttpResult;
+      if (r?.err || (r as any)?.error) {
+        reject(new Error(r?.err || (r as any).error));
+        return;
+      }
+      const body = r.body ?? '';
+      resolve({
+        status: r.status ?? 0,
+        headers: r.headers ?? {},
+        // 底层始终以 base64 承载原始字节；'utf8' 时 Java 侧已解码为文本，其余形态本地转换
+        body: opts.responseEncoding === 'utf8' ? body
+          : opts.responseEncoding === 'base64' ? body
+            : Uint8Array.fromBase64(body),
+      });
     });
     try {
-      _sendHttp({ t: 'requestAsync', p: { url, ...opts, cb: String(cbId) } });
+      const p: Record<string, unknown> = {
+        url,
+        method: opts.method || 'GET',
+        headers: opts.headers || {},
+      };
+      // 请求体与 fs.writeFile 同语义：Uint8Array 直接二进制（base64 承载）；
+      // 字符串按 encoding——缺省 UTF-8 文本，'base64' 视为 base64 二进制
+      if (opts.body instanceof Uint8Array) {
+        p.body = opts.body.toBase64();
+        p.encoding = 'base64';
+      } else {
+        p.body = opts.body ?? null;
+        if (opts.encoding === 'base64') p.encoding = 'base64';
+      }
+      p.responseType = opts.responseEncoding === 'utf8' ? 'text' : 'base64';
+      if (opts.timeout !== undefined) p.timeout = opts.timeout;
+      _sendHttp({ t: 'requestAsync', p: { ...p, cb: String(cbId) } });
     } catch (e) { reject(e); }
   });
 }
-
-/**
- * 同步 HTTP 请求（**阻塞 JS 线程**直到响应返回）——底层走 `http:request` 通道。
- * 阻塞期间 JS 线程无法处理事件/命令/回调（可能触发 event.timeout 告警）；
- * 仅适合低频、非事件上下文。事件处理器或高频场景请用 `request`（异步）或全局 `fetch`。
- */
-export function requestSync(url: string, opts: Record<string, unknown> = {}): HttpResult {
-  return _sendHttp({ t: 'request', p: { url, ...opts } });
-}

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 时原样返回字符串）。 */

package/src/potion.ts

@@ -1,24 +1,18 @@
-import { post } from './task.js';
-import type { TaskOptions } from './task.js';
+// 药水效果类型定义。操作已上移到 `entity.ts` 的 LivingEntity 实例方法
+// （`entity.addPotionEffect(...)` 等）——不再提供顶层 uuid 函数。
 
+/** 药水效果（`entity.addPotionEffect` 任务载荷；与 `getActivePotionEffects` 输出同结构）。 */
 export interface PotionEffect {
+  /** 药水效果类型（值域 R1 注册键，如 `minecraft:speed`；兼容旧枚举名，大小写不敏感）。 */
   type: string;
+  /** 持续时间（tick）。 */
   duration: number;
+  /** 等级（0 = 一级）。 */
   amplifier: number;
+  /** 是否环境指示剂（默认 true）。 */
   ambient?: boolean;
+  /** 是否显示粒子（默认 true）。 */
   particles?: boolean;
+  /** 是否显示图标（默认 true）。 */
   icon?: boolean;
 }
-
-export function addPotionEffect(uuid: string, effect: PotionEffect, options?: TaskOptions): Promise<void> {
-  return post('entity.addPotionEffect', { uuid, ...effect }, options);
-}
-export function removePotionEffect(uuid: string, type: string, options?: TaskOptions): Promise<void> {
-  return post('entity.removePotionEffect', { uuid, type }, options);
-}
-export function clearPotionEffects(uuid: string, options?: TaskOptions): Promise<void> {
-  return post('entity.clearPotionEffects', { uuid }, options);
-}
-export function getActivePotionEffects(uuid: string, options?: TaskOptions): Promise<PotionEffect[]> {
-  return post<PotionEffect[]>('entity.getActivePotionEffects', { uuid }, options);
-}

package/src/scoreboard.ts

@@ -1,5 +1,7 @@
-import { post } from './task.js';
+import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
+import { resolveUuid } from './target.js';
+import type { PlayerTarget } from './target.js';
 
 export interface ObjectiveInfo {
   name: string;
@@ -23,117 +25,280 @@ export interface TeamInfo {
   };
 }
 
-function boardParam(board?: string): Record<string, unknown> {
-  return board ? { board } : {};
+/** 线缆 board 参数：自定义计分板注入 `{ board: <id> }`，主计分板为空。 */
+function wireBoard(boardId: string | null): Record<string, unknown> {
+  return boardId != null ? { board: boardId } : {};
 }
 
-// ── Board ──
-
-export function createBoard(id: string, options?: TaskOptions): Promise<string> {
-  return post<string>('scoreboard.createBoard', { id }, options);
-}
-
-export function deleteBoard(id: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.deleteBoard', { id }, options);
+/** 计分板 entry 解析：Player 对象取其玩家名（Bukkit 计分板按玩家名登记），字符串原样。 */
+function resolveEntry(t: PlayerTarget): string {
+  return typeof t === 'string' ? t : t.name;
 }
 
-// ── Objectives ──
-
 /**
- * 创建计分项。⚠️ **Folia 平台限制**：Folia 不支持注册新 objective（registerNewObjective
- * 抛 UnsupportedOperationException）——在 Folia 上本调用会 reject（错误消息含
- * "Folia does not support creating new objectives"）；已存在的 objective 会更新 displayName 后返回。
+ * Scoreboard —— 计分板对象（OOP）。主计分板用 `Scoreboard.main()`，自定义用
+ * `Scoreboard.create(id)`；Objective / Team / Score 操作都在对应对象上调用，
+ * 不再反复传 `board`/裸名。
+ *
+ * ```js
+ * const board = await Scoreboard.create('myBoard');
+ * const obj = await board.createObjective('kills', 'dummy', '<red>Kills</red>');
+ * await obj.setDisplay('SIDEBAR');
+ * await obj.setScore(player, 42);          // 接受 Player 对象或 entry 字符串
+ * const team = await board.createTeam('red');
+ * await team.add(player);
+ * await board.attach(player);              // 为该玩家设置个人计分板
+ * await board.destroy();
+ * ```
+ *
+ * > **Folia 限制**：Folia 不支持注册新 objective/team（`createObjective` / `createTeam`
+ * > 会 reject）；读取与修改已存在对象（`setScore` / `setTeamPrefix` 等）可用。
  */
-export function createObjective(name: string, criteria: string, displayName: string, board?: string, options?: TaskOptions): Promise<ObjectiveInfo> {
-  return post<ObjectiveInfo>('scoreboard.createObjective', { name, criteria, displayName, ...boardParam(board) }, options);
-}
+export class Scoreboard {
+  private constructor(readonly id: string | null) {}
 
-export function deleteObjective(name: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.deleteObjective', { name, ...boardParam(board) }, options);
-}
+  /** 主计分板（服务器默认）。 */
+  static main(): Scoreboard {
+    return new Scoreboard(null);
+  }
 
-export function getObjectives(board?: string, options?: TaskOptions): Promise<ObjectiveInfo[]> {
-  return post<ObjectiveInfo[]>('scoreboard.getObjectives', { ...boardParam(board) }, options);
-}
+  /** 创建自定义计分板（返回自身句柄）。 */
+  static async create(id: string, options?: TaskOptions): Promise<Scoreboard> {
+    await post('scoreboard.createBoard', { id }, options);
+    return new Scoreboard(id);
+  }
 
-export function setObjectiveDisplay(name: string, slot: string | null, board?: string, options?: TaskOptions): Promise<boolean> {
-  return post<boolean>('scoreboard.setObjectiveDisplay', { name, slot, ...boardParam(board) }, options);
-}
+  static createSync(id: string, options?: TaskOptions): Scoreboard {
+    call('scoreboard.createBoard', { id }, options);
+    return new Scoreboard(id);
+  }
 
-export function getScore(objective: string, entry: string, board?: string, options?: TaskOptions): Promise<number | null> {
-  return post<number | null>('scoreboard.getScore', { objective, entry, ...boardParam(board) }, options);
-}
+  /** 销毁自定义计分板（主计分板不可销毁，抛错）。 */
+  destroy(options?: TaskOptions): Promise<void> {
+    if (this.id == null) return Promise.reject(new Error('cannot destroy main scoreboard'));
+    return post('scoreboard.deleteBoard', { id: this.id }, options);
+  }
+  destroySync(options?: TaskOptions): void {
+    if (this.id == null) throw new Error('cannot destroy main scoreboard');
+    call('scoreboard.deleteBoard', { id: this.id }, options);
+  }
 
-export function setScore(objective: string, entry: string, value: number, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setScore', { objective, entry, value, ...boardParam(board) }, options);
-}
+  /** 为该玩家设置其个人计分板为本计分板（接受 `Player` 对象或 uuid；重置用 `Scoreboard.main().attach(player)`）。 */
+  attach(player: PlayerTarget, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setPlayerBoard', { uuid: resolveUuid(player), ...wireBoard(this.id) }, options);
+  }
+  attachSync(player: PlayerTarget, options?: TaskOptions): void {
+    call('scoreboard.setPlayerBoard', { uuid: resolveUuid(player), ...wireBoard(this.id) }, options);
+  }
 
-export function resetScore(objective: string, entry: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.resetScore', { objective, entry, ...boardParam(board) }, options);
-}
+  // ── Objective ──
 
-// ── Teams ──
+  createObjective(name: string, criteria: string, displayName: string, options?: TaskOptions): Promise<Objective> {
+    return post<{ name: string; criteria: string }>('scoreboard.createObjective', { name, criteria, displayName, ...wireBoard(this.id) }, options)
+      .then((o) => new Objective(this.id, o.name, o.criteria, null));
+  }
+  createObjectiveSync(name: string, criteria: string, displayName: string, options?: TaskOptions): Objective {
+    const o = call<{ name: string; criteria: string }>('scoreboard.createObjective', { name, criteria, displayName, ...wireBoard(this.id) }, options);
+    return new Objective(this.id, o.name, o.criteria, null);
+  }
 
-/**
- * 创建队伍。⚠️ **Folia 平台限制**：Folia 不支持注册新 team（registerNewTeam 抛
- * UnsupportedOperationException）——在 Folia 上本调用会 reject；已存在的 team 返回其信息。
- */
-export function createTeam(name: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.createTeam', { name, ...boardParam(board) }, options);
-}
+  getObjectives(options?: TaskOptions): Promise<Objective[]> {
+    return post<ObjectiveInfo[]>('scoreboard.getObjectives', { ...wireBoard(this.id) }, options)
+      .then((list) => list.map((o) => new Objective(this.id, o.name, o.criteria, o.displaySlot)));
+  }
+  getObjectivesSync(options?: TaskOptions): Objective[] {
+    return call<ObjectiveInfo[]>('scoreboard.getObjectives', { ...wireBoard(this.id) }, options)
+      .map((o) => new Objective(this.id, o.name, o.criteria, o.displaySlot));
+  }
 
-export function deleteTeam(name: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.deleteTeam', { name, ...boardParam(board) }, options);
-}
+  // ── Team ──
 
-export function getTeam(name: string, board?: string, options?: TaskOptions): Promise<TeamInfo | null> {
-  return post<TeamInfo | null>('scoreboard.getTeam', { name, ...boardParam(board) }, options);
-}
+  createTeam(name: string, options?: TaskOptions): Promise<Team> {
+    return post('scoreboard.createTeam', { name, ...wireBoard(this.id) }, options)
+      .then(() => this.getTeam(name))
+      .then((t) => {
+        if (!t) throw new Error('team created but not found: ' + name);
+        return t;
+      });
+  }
+  createTeamSync(name: string, options?: TaskOptions): Team {
+    call('scoreboard.createTeam', { name, ...wireBoard(this.id) }, options);
+    const t = this.getTeamSync(name);
+    if (!t) throw new Error('team created but not found: ' + name);
+    return t;
+  }
 
-export function getTeams(board?: string, options?: TaskOptions): Promise<TeamInfo[]> {
-  return post<TeamInfo[]>('scoreboard.getTeams', { ...boardParam(board) }, options);
-}
+  getTeam(name: string, options?: TaskOptions): Promise<Team | null> {
+    return post<TeamInfo | null>('scoreboard.getTeam', { name, ...wireBoard(this.id) }, options)
+      .then((info) => (info ? new Team(this.id, info) : null));
+  }
+  getTeamSync(name: string, options?: TaskOptions): Team | null {
+    const info = call<TeamInfo | null>('scoreboard.getTeam', { name, ...wireBoard(this.id) }, options);
+    return info ? new Team(this.id, info) : null;
+  }
 
-export function setTeamDisplayName(name: string, displayName: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamDisplayName', { name, displayName, ...boardParam(board) }, options);
+  getTeams(options?: TaskOptions): Promise<Team[]> {
+    return post<TeamInfo[]>('scoreboard.getTeams', { ...wireBoard(this.id) }, options)
+      .then((list) => list.map((info) => new Team(this.id, info)));
+  }
+  getTeamsSync(options?: TaskOptions): Team[] {
+    return call<TeamInfo[]>('scoreboard.getTeams', { ...wireBoard(this.id) }, options)
+      .map((info) => new Team(this.id, info));
+  }
 }
 
-export function setTeamPrefix(name: string, prefix: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamPrefix', { name, prefix, ...boardParam(board) }, options);
-}
+/** 计分项（objective）句柄。 */
+export class Objective {
+  constructor(
+    private readonly boardId: string | null,
+    public readonly name: string,
+    public readonly criteria?: string,
+    public readonly displaySlot: string | null = null,
+  ) {}
 
-export function setTeamSuffix(name: string, suffix: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamSuffix', { name, suffix, ...boardParam(board) }, options);
-}
+  /** 设置显示位置（slot 为 BELOW_NAME/PLAYER_LIST/SIDEBAR；null 取消显示）。 */
+  setDisplay(slot: string | null, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('scoreboard.setObjectiveDisplay', { name: this.name, slot, ...wireBoard(this.boardId) }, options);
+  }
+  setDisplaySync(slot: string | null, options?: TaskOptions): boolean {
+    return call<boolean>('scoreboard.setObjectiveDisplay', { name: this.name, slot, ...wireBoard(this.boardId) }, options);
+  }
 
-export function setTeamColor(name: string, color: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamColor', { name, color, ...boardParam(board) }, options);
-}
+  /** 设置分数（target 为 `Player` 对象或 entry 字符串）。 */
+  setScore(target: PlayerTarget, value: number, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setScore', { objective: this.name, entry: resolveEntry(target), value, ...wireBoard(this.boardId) }, options);
+  }
+  setScoreSync(target: PlayerTarget, value: number, options?: TaskOptions): void {
+    call('scoreboard.setScore', { objective: this.name, entry: resolveEntry(target), value, ...wireBoard(this.boardId) }, options);
+  }
 
-export function setTeamFriendlyFire(name: string, allow: boolean, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamFriendlyFire', { name, allow, ...boardParam(board) }, options);
-}
+  /** 查询分数（无记录返回 null）。 */
+  getScore(target: PlayerTarget, options?: TaskOptions): Promise<number | null> {
+    return post<number | null>('scoreboard.getScore', { objective: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
+  getScoreSync(target: PlayerTarget, options?: TaskOptions): number | null {
+    return call<number | null>('scoreboard.getScore', { objective: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
 
-export function setTeamSeeInvisible(name: string, canSee: boolean, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamSeeInvisible', { name, canSee, ...boardParam(board) }, options);
-}
+  /** 重置（清除）分数。 */
+  resetScore(target: PlayerTarget, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.resetScore', { objective: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
+  resetScoreSync(target: PlayerTarget, options?: TaskOptions): void {
+    call('scoreboard.resetScore', { objective: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
 
-export function setTeamOption(name: string, option: string, value: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setTeamOption', { name, option, value, ...boardParam(board) }, options);
+  /** 删除此计分项。 */
+  delete(options?: TaskOptions): Promise<void> {
+    return post('scoreboard.deleteObjective', { name: this.name, ...wireBoard(this.boardId) }, options);
+  }
+  deleteSync(options?: TaskOptions): void {
+    call('scoreboard.deleteObjective', { name: this.name, ...wireBoard(this.boardId) }, options);
+  }
 }
 
-export function teamAddEntry(name: string, entry: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.teamAddEntry', { name, entry, ...boardParam(board) }, options);
-}
+/** 队伍（team）句柄；携带读取时刻的快照字段。 */
+export class Team {
+  readonly name: string;
+  readonly displayName: string;
+  readonly prefix: string;
+  readonly suffix: string;
+  readonly color: string;
+  readonly allowFriendlyFire: boolean;
+  readonly canSeeFriendlyInvisibles: boolean;
+  readonly entries: string[];
+  readonly options: TeamInfo['options'];
 
-export function teamRemoveEntry(name: string, entry: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.teamRemoveEntry', { name, entry, ...boardParam(board) }, options);
-}
+  constructor(private readonly boardId: string | null, info: TeamInfo) {
+    this.name = info.name;
+    this.displayName = info.displayName;
+    this.prefix = info.prefix;
+    this.suffix = info.suffix;
+    this.color = info.color;
+    this.allowFriendlyFire = info.allowFriendlyFire;
+    this.canSeeFriendlyInvisibles = info.canSeeFriendlyInvisibles;
+    this.entries = info.entries;
+    this.options = info.options;
+  }
 
-export function teamGetEntries(name: string, board?: string, options?: TaskOptions): Promise<string[]> {
-  return post<string[]>('scoreboard.teamGetEntries', { name, ...boardParam(board) }, options);
-}
+  setDisplayName(v: string, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamDisplayName', { name: this.name, displayName: v, ...wireBoard(this.boardId) }, options);
+  }
+  setDisplayNameSync(v: string, options?: TaskOptions): void {
+    call('scoreboard.setTeamDisplayName', { name: this.name, displayName: v, ...wireBoard(this.boardId) }, options);
+  }
+
+  setPrefix(v: string, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamPrefix', { name: this.name, prefix: v, ...wireBoard(this.boardId) }, options);
+  }
+  setPrefixSync(v: string, options?: TaskOptions): void {
+    call('scoreboard.setTeamPrefix', { name: this.name, prefix: v, ...wireBoard(this.boardId) }, options);
+  }
+
+  setSuffix(v: string, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamSuffix', { name: this.name, suffix: v, ...wireBoard(this.boardId) }, options);
+  }
+  setSuffixSync(v: string, options?: TaskOptions): void {
+    call('scoreboard.setTeamSuffix', { name: this.name, suffix: v, ...wireBoard(this.boardId) }, options);
+  }
+
+  setColor(v: string, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamColor', { name: this.name, color: v, ...wireBoard(this.boardId) }, options);
+  }
+  setColorSync(v: string, options?: TaskOptions): void {
+    call('scoreboard.setTeamColor', { name: this.name, color: v, ...wireBoard(this.boardId) }, options);
+  }
+
+  setFriendlyFire(allow: boolean, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamFriendlyFire', { name: this.name, allow, ...wireBoard(this.boardId) }, options);
+  }
+  setFriendlyFireSync(allow: boolean, options?: TaskOptions): void {
+    call('scoreboard.setTeamFriendlyFire', { name: this.name, allow, ...wireBoard(this.boardId) }, options);
+  }
+
+  setSeeInvisible(canSee: boolean, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamSeeInvisible', { name: this.name, canSee, ...wireBoard(this.boardId) }, options);
+  }
+  setSeeInvisibleSync(canSee: boolean, options?: TaskOptions): void {
+    call('scoreboard.setTeamSeeInvisible', { name: this.name, canSee, ...wireBoard(this.boardId) }, options);
+  }
+
+  setOption(option: string, value: string, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.setTeamOption', { name: this.name, option, value, ...wireBoard(this.boardId) }, options);
+  }
+  setOptionSync(option: string, value: string, options?: TaskOptions): void {
+    call('scoreboard.setTeamOption', { name: this.name, option, value, ...wireBoard(this.boardId) }, options);
+  }
+
+  /** 添加成员（`Player` 对象取其名，或 entry 字符串）。 */
+  add(target: PlayerTarget, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.teamAddEntry', { name: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
+  addSync(target: PlayerTarget, options?: TaskOptions): void {
+    call('scoreboard.teamAddEntry', { name: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
+
+  /** 移除成员。 */
+  remove(target: PlayerTarget, options?: TaskOptions): Promise<void> {
+    return post('scoreboard.teamRemoveEntry', { name: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
+  removeSync(target: PlayerTarget, options?: TaskOptions): void {
+    call('scoreboard.teamRemoveEntry', { name: this.name, entry: resolveEntry(target), ...wireBoard(this.boardId) }, options);
+  }
+
+  /** 成员列表（快照）。 */
+  getEntries(options?: TaskOptions): Promise<string[]> {
+    return post<string[]>('scoreboard.teamGetEntries', { name: this.name, ...wireBoard(this.boardId) }, options);
+  }
+  getEntriesSync(options?: TaskOptions): string[] {
+    return call<string[]>('scoreboard.teamGetEntries', { name: this.name, ...wireBoard(this.boardId) }, options);
+  }
 
-export function setPlayerBoard(uuid: string, board?: string, options?: TaskOptions): Promise<void> {
-  return post('scoreboard.setPlayerBoard', { uuid, ...boardParam(board) }, options);
+  /** 删除队伍。 */
+  delete(options?: TaskOptions): Promise<void> {
+    return post('scoreboard.deleteTeam', { name: this.name, ...wireBoard(this.boardId) }, options);
+  }
+  deleteSync(options?: TaskOptions): void {
+    call('scoreboard.deleteTeam', { name: this.name, ...wireBoard(this.boardId) }, options);
+  }
 }

package/src/sound.ts

@@ -1,14 +1,10 @@
 import { post } from './task.js';
 import type { TaskOptions } from './task.js';
 
+// 玩家侧 stopSound/stopAllSounds 已上移到 `player.ts` 的 Player 实例方法
+// （`player.stopSound(sound)` / `player.stopAllSounds()`）——不再提供顶层 uuid 函数。
+
+/** 世界级音效（在指定世界坐标播放，对范围内玩家生效）。 */
 export function playSound(world: string, sound: string, x: number, y: number, z: number, volume?: number, pitch?: number, options?: TaskOptions): Promise<void> {
   return post('world.playSound', { world, sound, x, y, z, volume, pitch }, options);
 }
-
-export function stopSound(uuid: string, sound: string, options?: TaskOptions): Promise<void> {
-  return post('player.stopSound', { uuid, sound }, options);
-}
-
-export function stopAllSounds(uuid: string, options?: TaskOptions): Promise<void> {
-  return post('player.stopAllSounds', { uuid }, options);
-}

package/src/target.ts

@@ -0,0 +1,20 @@
+import type { Player } from './player.js';
+import type { Entity, LivingEntity } from './entity.js';
+
+/**
+ * 以玩家/实体为目标的参数统一类型：**对象或字符串**。
+ *
+ * 传对象（`Player` / `LivingEntity` / `Entity`）时取其 `uuid`；传字符串时按原样
+ * 当作 uuid（或按具体 API 上下文为玩家名——如计分板 entry）。彻底消除
+ * 「必须手动传 uuid」的摩擦：有对象直接传对象，只有原始 id 时才传字符串。
+ */
+export type PlayerTarget = Player | string;
+
+export type LivingTarget = LivingEntity | string;
+
+export type EntityTarget = Entity | string;
+
+/** 解析目标 → uuid：对象取其 `uuid`，字符串原样返回。 */
+export function resolveUuid(t: PlayerTarget | LivingTarget | EntityTarget): string {
+  return typeof t === 'string' ? t : t.uuid;
+}

package/src/util.ts

@@ -31,25 +31,25 @@ function toB64(data: Uint8Array | string): string {
     : data.toBase64();
 }
 
-// ── 字符串 ↔ 字节（UTF-8）────────────────────────────────────────
+// ── 字符串 ↔ 字节（UTF-8；默认异步，同步加 Sync 后缀）──────────────
 
 /** UTF-8 字符串 → 字节（同步）。 */
-export function stringToBytes(text: string): Uint8Array {
+export function stringToBytesSync(text: string): Uint8Array {
   return Uint8Array.fromBase64(send<{ data: string }>('encode.utf8', { data: text }).data);
 }
 
 /** 字节 → UTF-8 字符串（同步；非法序列替换为 U+FFFD，不抛错）。 */
-export function bytesToString(bytes: Uint8Array): string {
+export function bytesToStringSync(bytes: Uint8Array): string {
   return send<{ data: string }>('decode.utf8', { data: bytes.toBase64() }).data;
 }
 
-/** UTF-8 字符串 → 字节（异步，ioExecutor 执行）。 */
-export function stringToBytesAsync(text: string): Promise<Uint8Array> {
+/** UTF-8 字符串 → 字节（异步，ioExecutor 执行；默认）。 */
+export function stringToBytes(text: string): Promise<Uint8Array> {
   return sendAsync<{ data: string }>('encode.utf8', { data: text }).then((r) => Uint8Array.fromBase64(r.data));
 }
 
-/** 字节 → UTF-8 字符串（异步）。 */
-export function bytesToStringAsync(bytes: Uint8Array): Promise<string> {
+/** 字节 → UTF-8 字符串（异步；非法序列替换为 U+FFFD）。 */
+export function bytesToString(bytes: Uint8Array): Promise<string> {
   return sendAsync<{ data: string }>('decode.utf8', { data: bytes.toBase64() }).then((r) => r.data);
 }
 

package/src/world.ts

@@ -133,6 +133,12 @@ export class World {
   isChunkLoadedSync(x: number, z: number, options?: TaskOptions): boolean {
     return call<boolean>('world.isChunkLoaded', { world: this.name, x, z }, options);
   }
+  isChunkGenerated(x: number, z: number, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('world.isChunkGenerated', { world: this.name, x, z }, options);
+  }
+  isChunkGeneratedSync(x: number, z: number, options?: TaskOptions): boolean {
+    return call<boolean>('world.isChunkGenerated', { world: this.name, x, z }, options);
+  }
   loadChunk(x: number, z: number, options?: TaskOptions): Promise<boolean> {
     return post<boolean>('world.loadChunk', { world: this.name, x, z }, options);
   }