yeow-api 0.4.3 → 0.6.0

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);
+  }
 }