yeow-api 0.2.112 → 0.2.114

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yeow-api",
-    "version": "0.2.112",
+    "version": "0.2.114",
     "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,8 @@ 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';
+export { getEnv } from './env.js';
+export type { EnvInfo } from './env.js';
+export { createWorker, Worker, onMessage, postMessage } from './worker.js';
+export type { WorkerOptions } from './worker.js';

package/src/env.ts

@@ -0,0 +1,20 @@
+/** env 通道返回的运行时环境信息（同步）。 */
+export interface EnvInfo {
+  /** CPU 逻辑核心数。 */
+  cpus: number;
+  /** JVM 总内存（字节）。 */
+  memory: number;
+  /** 系统架构（如 `windows-x64` / `linux-x64` / `linux-arm64`）。 */
+  arch: string;
+  /** Minecraft 版本（如 `1.21.4`）。 */
+  minecraftVersion: string;
+  /** 运行时信息。 */
+  yeow: { platform: string; version: string };
+  /** epoch 微秒时间戳。 */
+  now: number;
+}
+
+/** 获取运行时环境信息（同步；含微秒时间戳）。 */
+export function getEnv(): EnvInfo {
+  return $send('env', {}) as EnvInfo;
+}

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;

package/src/global.d.ts

@@ -11,6 +11,7 @@ declare global {
   function _unregisterCallback(id: string): void;
   function _getCurrentCbStack(): { stack: string; outer: unknown } | null;
   function _attachCbStack(err: unknown): void;
+  function reportError(e: unknown): void;
 
   // ── init.js 注入的标准环境（lib 为 ESNext，不含 DOM——自行声明）──
   interface YeowConsole {

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> {
@@ -140,13 +141,23 @@ export class Player {
   hasPermissionSync(node: string, options?: TaskOptions): boolean {
     return call<boolean>('player.hasPermission', { uuid: this.uuid, permission: node }, options);
   }
+  /** 以玩家身份执行命令（**不含 `/` 前缀**，如 `say hi`；前缀会自动剥离；与服务器 `dispatchCommand`（控制台）相对）。 */
+  performCommand(cmd: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('player.performCommand', { uuid: this.uuid, command: cmd.replace(/^\//, '') }, options);
+  }
+  performCommandSync(cmd: string, options?: TaskOptions): boolean {
+    return call<boolean>('player.performCommand', { uuid: this.uuid, command: cmd.replace(/^\//, '') }, 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); }
-  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); }

package/src/worker.ts

@@ -0,0 +1,150 @@
+export interface WorkerOptions {
+  /** Worker 名（必填；不允许 'main'；同一主插件内不重复，全局可重复）。 */
+  name: string;
+  /** 资源路径（通过 `getAssetsPath` 获取）；与 `code` 互斥（不可同时传递）。 */
+  entry?: string;
+  /** 代码字符串；与 `entry` 互斥。 */
+  code?: string;
+}
+
+let _seq = 0;
+/** 本主插件已创建的 worker 名（同主插件内唯一校验；unload 后允许重建）。 */
+const _created: Record<string, boolean> = {};
+/** 主插件侧：每个 worker 的 onMessage 回调 id。 */
+const _msgCbs: Record<string, string> = {};
+
+function _sendWorker(payload: Record<string, unknown>): unknown {
+  const r = $send('worker', payload);
+  if (r == null) return undefined;
+  if ((r as any)?.err) throw new Error((r as any).err);
+  return r;
+}
+
+/** 内部：异步调用 worker 通道（cb 回调）。 */
+function _sendWorkerAsync(t: string, p: Record<string, unknown>): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const cbId = _registerCallback((result: unknown) => {
+      if ((result as any)?.err) reject(new Error((result as any).err));
+      else resolve();
+    });
+    _sendWorker({ t, p: { ...p, cb: cbId } });
+  });
+}
+
+/**
+ * Worker —— 虚拟插件（独立 QuickJS 上下文 + 线程）。
+ *
+ * - 事件/命令/服务以独立实体注册；调度器任务独立统计
+ * - 共享主插件的**数据目录**与**权限**
+ * - 不能创建新的 Worker（嵌套被拒绝）
+ * - **创建后无法销毁，只能卸载**（卸载物理销毁 JS 上下文，句柄保留——可重新 load）
+ * - 主插件卸载时连带卸载；/yeow 管理命令不覆盖 Worker；profiler 会统计（标记 created by 主插件）
+ * - Worker 的 JS 错误与主插件同样回传（dev 模式经 source-map 定位）
+ */
+export class Worker {
+  private readonly name: string;
+  private readonly entry?: string;
+  private readonly code?: string;
+  private readonly key: string;
+  private _loaded = false;
+  private _onMessage: ((msg: any) => void) | null = null;
+  /** 内部 workerId（主插件 JS 侧分配；跨主插件可重复）。 */
+  readonly id: string;
+
+  constructor(name: string, entry: string | undefined, code: string | undefined) {
+    this.name = name;
+    this.entry = entry;
+    this.code = code;
+    this.id = 'worker_' + (++_seq);
+    this.key = (__plugin?.name || 'unknown') + ':' + name;
+    // 主插件侧 onMessage 回调（worker → main 时 Java 投递到这里）
+    _msgCbs[this.id] = _registerCallback((msg: unknown) => {
+      const cb = this._onMessage;
+      if (cb) { try { cb(msg); } catch (e) { console.error('[worker] onMessage error', e); } }
+    }, { persistent: true });
+  }
+
+  /** 注册接收 Worker 发来的消息。 */
+  onMessage(cb: (msg: any) => void): void {
+    this._onMessage = cb;
+  }
+
+  /** 启动 Worker：执行 init.js → worker-inject.js → Worker 代码 → INIT → LOAD（已加载为 no-op）。 */
+  load(): Promise<void> {
+    if (this._loaded) return Promise.resolve();
+    this._loaded = true;
+    return _sendWorkerAsync('load', { name: this.name });
+  }
+
+  /** 卸载 Worker（物理销毁 JS 上下文并清理其事件/命令/服务/任务；句柄保留，可重新 load）。 */
+  unload(): Promise<void> {
+    this._loaded = false;
+    return _sendWorkerAsync('unload', { name: this.name });
+  }
+
+  /** 向 Worker 发送消息（其 onMessage 回调接收；未 load 时抛错）。 */
+  postMessage(msg: Record<string, unknown>): Promise<void> {
+    return _sendWorkerAsync('post', { name: this.name, msg });
+  }
+
+  /** 重载 Worker 代码（需已 load；旧上下文销毁、新代码重新加载）。 */
+  reload(): Promise<void> {
+    const p: Record<string, unknown> = { name: this.name };
+    if (this.entry) p.entry = this.entry;
+    else p.code = this.code;
+    return _sendWorkerAsync('reload', p);
+  }
+}
+
+/**
+ * 创建 Worker（虚拟插件）：**仅注册到注册表并返回句柄**——`worker.load()` 才真正启动
+ * （执行 init.js → worker-inject.js → Worker 代码 → INIT → LOAD）。
+ *
+ * `entry`（资源路径，经 getAssetsPath）与 `code` 二选一，同时传递抛错；
+ * `name` 必填、非 'main'、同主插件内不重复。
+ */
+export function createWorker(options: WorkerOptions): Worker {
+  const name = options?.name;
+  if (!name || typeof name !== 'string' || name.trim() === '') {
+    throw new Error('createWorker: name is required');
+  }
+  if (name === 'main') {
+    throw new Error('createWorker: name must not be "main"');
+  }
+  if (options.entry && options.code) {
+    throw new Error('createWorker: entry and code cannot be passed together');
+  }
+  if (!options.entry && !options.code) {
+    throw new Error('createWorker: either entry or code is required');
+  }
+  const key = (__plugin?.name || 'unknown') + ':' + name;
+  if (_created[key]) {
+    throw new Error('createWorker: duplicate worker name "' + name + '" in plugin ' + (__plugin?.name || 'unknown'));
+  }
+  _created[key] = true;
+  const w = new Worker(name, options.entry, options.code);
+  // 注册到运行时注册表（同步；重复/非法名抛错）
+  const p: Record<string, unknown> = { name, msgCb: _msgCbs[w.id] };
+  if (options.entry) p.entry = options.entry;
+  else p.code = options.code;
+  _sendWorker({ t: 'create', p });
+  return w;
+}
+
+// ── Worker 侧 API（仅 Worker 环境可用）──────────────────────────────
+
+const _isWorker = typeof (globalThis as any).__workerId !== 'undefined';
+
+/** Worker 侧：注册消息接收回调（主插件 `worker.postMessage` 触发）。主插件环境调用抛错。 */
+export function onMessage(cb: (msg: any) => void): void {
+  if (!_isWorker) throw new Error('onMessage is only available inside a Worker');
+  (globalThis as any)._workerOnMessage = (msg: any) => {
+    try { cb(msg); } catch (e) { reportError(e); }
+  };
+}
+
+/** Worker 侧：向主插件发送消息（主插件侧 `worker.onMessage` 回调接收）。主插件环境调用抛错。 */
+export function postMessage(msg: Record<string, unknown>): void {
+  if (!_isWorker) throw new Error('postMessage is only available inside a Worker');
+  _sendWorker({ t: 'postToMain', p: { msg } });
+}