yeow-api 0.2.111 → 0.2.113

package/package.json

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

package/src/core.ts

@@ -51,6 +51,7 @@ export { assets, read as assetsRead, readSync as assetsReadSync,
     extractDir as assetsExtractDir, extractDirSync as assetsExtractDirSync } from './assets.js';
 export { path } from './path.js';
 export { listen, respond, close, request, requestSync } from './http.js';
+export type { RespondOptions } from './http.js';
 export { logError } from './log-error.js';
 export { InstanceId, GUIHandle, BossBarHandle, InventoryHandle } from './instance-id.js';
 export type { ItemStack } from './item.js';
@@ -90,3 +91,4 @@ 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 { log, Logger } from './log.js';
+export type { Message } from './message.js';

package/src/event.ts

@@ -1,6 +1,7 @@
 import { call } from './task.js';
 import { Player } from './player.js';
 import { Location } from './location.js';
+import type { Message } from './message.js';
 
 // ── Event Data Interfaces ──────────────────────────────────────────
 
@@ -40,7 +41,8 @@ export interface PlayerCommandEvent {
 }
 export interface PlayerDeathEvent {
   player: Player;
-  deathMessage: string;
+  /** 死亡消息（Message 对象）：`{key, args}` 可翻译组件（客户端本地化）+ `{text}` 纯文本兜底，同时传递。 */
+  deathMessage: Message;
   deathType: string;
   cancelled?: boolean;
 }
@@ -179,6 +181,10 @@ export interface PlayerItemConsumeEvent {
 export interface PlayerAdvancementDoneEvent {
   player: Player;
   advancement: string;
+  /** 进度标题（Message 对象，`{text}` 纯文本；隐藏进度时缺失）。 */
+  title?: Message;
+  /** 进度描述（Message 对象，`{text}` 纯文本；隐藏进度时缺失）。 */
+  description?: Message;
 }
 export interface PlayerToggleSneakEvent {
   player: Player;
@@ -378,7 +384,7 @@ export function eventOn<K extends keyof EventMap>(
 
   const cbId = _registerCallback((data: RawEvent) => {
     const wrapped = adaptEvent(eventType, data);
-    const dispatchId = data?._dispatchId;
+    const eventId = data?._eventId;
     const cancellable = data?._cancellable;
     const localMods: { cancelled?: boolean } = {};
 
@@ -394,7 +400,7 @@ export function eventOn<K extends keyof EventMap>(
       const complete = (result?: Record<string, unknown>) => {
         $send('task', {
           type: 'event.complete',
-          params: { callbackId: cbId, dispatchId, mods: result },
+          params: { eventId, mods: result },
           cb: '',
         });
       };
@@ -407,7 +413,7 @@ export function eventOn<K extends keyof EventMap>(
       ...(result && typeof result === 'object' ? result : {}),
     };
     if (localMods.cancelled) mods.cancelled = true;
-    $send('task', { type: 'event.complete', params: { callbackId: cbId, dispatchId, mods }, cb: '' });
+    $send('task', { type: 'event.complete', params: { eventId, mods }, cb: '' });
   }, { persistent: true });
 
   const gh = globalThis as any;

package/src/http.ts

@@ -7,6 +7,18 @@ interface HttpResult {
   err?: string;
 }
 
+/** HTTP 响应选项（respond）。 */
+export interface RespondOptions {
+  /** HTTP 状态码（默认 200）。 */
+  status?: number;
+  /** 文本响应体（UTF-8）。 */
+  body?: string;
+  /** base64 编码的**二进制**响应体（与 body 互斥，优先）——如从 assets 读取的资源包等。 */
+  bodyBase64?: string;
+  /** 响应头。 */
+  headers?: Record<string, string>;
+}
+
 function _sendHttp(payload: Record<string, unknown>): HttpResult {
   const r = $send('http', payload);
   if (!r) return {};
@@ -31,7 +43,7 @@ export function listen(callback: (req: Record<string, unknown>) => void, port?:
   return result;
 }
 
-export function respond(serverId: string, connId: string, opts: Record<string, unknown> = {}): void {
+export function respond(serverId: string, connId: string, opts: RespondOptions = {}): void {
   _sendHttp({ t: 'respond', p: { serverId, connId, ...opts } });
 }
 

package/src/message.ts

@@ -0,0 +1,19 @@
+/**
+ * Message —— 可翻译组件 / 纯文本的统一消息对象。
+ *
+ * - `{ key, args? }`：Minecraft 翻译键组件（如死亡消息 `death.attack.player`），
+ *   由客户端按语言本地化；`args` 为翻译参数（字符串/数字/嵌套 Message）
+ * - `{ text }`：纯文本（MiniMessage/legacy 解析）——所有实现**至少应支持 text 字段**
+ * - 两者同时存在时 `key` 优先
+ *
+ * 发送消息 API（`player.sendMessage`、`broadcast`、`sendActionBar` 等）与
+ * 事件字段（如 `playerDeath.deathMessage`）均接受该对象或纯字符串。
+ */
+export interface Message {
+  /** Minecraft 翻译键（如 `death.attack.player`）。 */
+  key?: string;
+  /** 翻译参数（字符串/数字/嵌套 Message）。 */
+  args?: (string | number | Message)[];
+  /** 纯文本（MiniMessage 解析；key 缺失时使用）。 */
+  text?: string;
+}

package/src/player.ts

@@ -2,6 +2,7 @@ import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
 import type { ItemStack } from './item.js';
+import type { Message } from './message.js';
 
 interface PlayerData {
   uuid: string;
@@ -116,8 +117,8 @@ export class Player {
   get totalExperience(): number { return call<number>('player.getTotalExperience', { uuid: this.uuid }); }
   getTotalExperience(options?: TaskOptions): Promise<number> { return post<number>('player.getTotalExperience', { uuid: this.uuid }, options); }
 
-  sendMessage(msg: string, options?: TaskOptions): Promise<void> { return post('player.sendMessage', { uuid: this.uuid, message: msg }, options); }
-  sendMessageSync(msg: string, options?: TaskOptions): void { call('player.sendMessage', { uuid: this.uuid, message: msg }, options); }
+  sendMessage(msg: string | Message, options?: TaskOptions): Promise<void> { return post('player.sendMessage', { uuid: this.uuid, message: msg }, options); }
+  sendMessageSync(msg: string | Message, options?: TaskOptions): void { call('player.sendMessage', { uuid: this.uuid, message: msg }, options); }
   kick(reason?: string, options?: TaskOptions): Promise<void> { return post('player.kick', { uuid: this.uuid, reason }, options); }
   kickSync(reason?: string, options?: TaskOptions): void { call('player.kick', { uuid: this.uuid, reason }, options); }
   sendTitle(title?: string, subtitle?: string, fadeIn?: number, stay?: number, fadeOut?: number, options?: TaskOptions): Promise<void> {
@@ -142,11 +143,14 @@ export class Player {
   }
   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); }
-  sendActionBar(message: string, options?: TaskOptions): Promise<void> { return post('player.sendActionBar', { uuid: this.uuid, message }, options); }
-  sendActionBarSync(message: string, options?: TaskOptions): void { call('player.sendActionBar', { uuid: this.uuid, message }, options); }
-  sendResourcePack(url: string, hash?: string, prompt?: string, force?: boolean, options?: TaskOptions): Promise<void> {
+  sendActionBar(message: string | Message, options?: TaskOptions): Promise<void> { return post('player.sendActionBar', { uuid: this.uuid, message }, options); }
+  sendActionBarSync(message: string | Message, options?: TaskOptions): void { call('player.sendActionBar', { uuid: this.uuid, message }, options); }
+  sendResourcePack(url: string, hash?: string, prompt?: string | Message, force?: boolean, options?: TaskOptions): Promise<void> {
     return post('player.sendResourcePack', { uuid: this.uuid, url, hash, prompt, force }, options);
   }
+  sendResourcePackSync(url: string, hash?: string, prompt?: string | Message, force?: boolean, options?: TaskOptions): void {
+    call('player.sendResourcePack', { uuid: this.uuid, url, hash, prompt, force }, options);
+  }
   getItemInMainHand(options?: TaskOptions): Promise<ItemStack | null> { return post<ItemStack | null>('player.getItemInMainHand', { uuid: this.uuid }, options); }
   getItemInMainHandSync(options?: TaskOptions): ItemStack | null { return call<ItemStack | null>('player.getItemInMainHand', { uuid: this.uuid }, options); }
   getItemInOffHand(options?: TaskOptions): Promise<ItemStack | null> { return post<ItemStack | null>('player.getItemInOffHand', { uuid: this.uuid }, options); }

package/src/server.ts

@@ -1,8 +1,9 @@
 import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
+import type { Message } from './message.js';
 
-export function broadcast(msg: string, options?: TaskOptions): Promise<void> { return post('server.broadcast', { message: msg }, options); }
-export function broadcastSync(msg: string, options?: TaskOptions): void { call('server.broadcast', { message: msg }, options); }
+export function broadcast(msg: string | Message, options?: TaskOptions): Promise<void> { return post('server.broadcast', { message: msg }, options); }
+export function broadcastSync(msg: string | Message, options?: TaskOptions): void { call('server.broadcast', { message: msg }, options); }
 export function dispatchCommand(cmd: string, options?: TaskOptions): Promise<boolean> { return post<boolean>('command.dispatch', { command: cmd }, options); }
 export function dispatchCommandSync(cmd: string, options?: TaskOptions): boolean { return call<boolean>('command.dispatch', { command: cmd }, options); }
 export function setMotd(motd: string, options?: TaskOptions): Promise<void> { return post('server.setMotd', { motd }, options); }