yeow-api 0.3.10 → 0.4.1

package/package.json

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

package/src/assets.ts

@@ -1,3 +1,5 @@
+import type { FsEncoding, ReadFileOptions } from './fs.js';
+
 function _sendAssets(payload: Record<string, unknown>): unknown {
   const r = $send('assets', payload);
   if (r == null) return undefined;
@@ -15,21 +17,43 @@ function _sendAssetsAsync(payload: Record<string, unknown>): Promise<unknown> {
   });
 }
 
-export async function read(path: string): Promise<string> {
-  const r = await _sendAssetsAsync({ t: 'read', p: { path } }) as { data: string };
-  return r.data;
-}
-export function readSync(path: string): string {
-  return (_sendAssets({ t: 'read', p: { path } }) as { data: string }).data;
+/** 归一化 encoding 参数（与 fs 一致：缺省 = Uint8Array；utf8/base64 → 字符串）。 */
+function _encoding(options?: FsEncoding | ReadFileOptions): FsEncoding | undefined {
+  if (options == null) return undefined;
+  const e = typeof options === 'string' ? options : options.encoding;
+  if (e != null && e !== 'utf8' && e !== 'base64') {
+    throw new Error('Unsupported encoding: ' + String(e));
+  }
+  return e;
 }
 
-export async function readBase64(path: string): Promise<string> {
-  const r = await _sendAssetsAsync({ t: 'readBase64', p: { path } }) as { data: string };
-  return r.data;
-}
-export function readBase64Sync(path: string): string {
-  return (_sendAssets({ t: 'readBase64', p: { path } }) as { data: string }).data;
-}
+// 与 fs.readFile 相同语义：默认返回 Uint8Array；显式 utf8/base64 返回字符串。
+type AssetsReadFn = {
+  (path: string): Promise<Uint8Array>;
+  (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): Promise<string>;
+  (path: string, options: ReadFileOptions): Promise<Uint8Array | string>;
+};
+type AssetsReadSyncFn = {
+  (path: string): Uint8Array;
+  (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): string;
+  (path: string, options: ReadFileOptions): Uint8Array | string;
+};
+
+const readImpl = async (path: string, options?: FsEncoding | ReadFileOptions): Promise<Uint8Array | string> => {
+  const enc = _encoding(options);
+  const r = await _sendAssetsAsync({ t: enc === 'utf8' ? 'read' : 'readBase64', p: { path } }) as { data: string };
+  if (enc === 'utf8' || enc === 'base64') return r.data;
+  return Uint8Array.fromBase64(r.data);
+};
+const readSyncImpl = (path: string, options?: FsEncoding | ReadFileOptions): Uint8Array | string => {
+  const enc = _encoding(options);
+  const r = _sendAssets({ t: enc === 'utf8' ? 'read' : 'readBase64', p: { path } }) as { data: string };
+  if (enc === 'utf8' || enc === 'base64') return r.data;
+  return Uint8Array.fromBase64(r.data);
+};
+
+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 };
@@ -55,4 +79,4 @@ export function extractDirSync(path: string, dest?: string): string {
   return (_sendAssets({ t: 'extractDir', p }) as { path: string }).path;
 }
 
-export const assets = { read, readSync, readBase64, readBase64Sync, extract, extractSync, extractDir, extractDirSync };
+export const assets = { read, readSync, extract, extractSync, extractDir, extractDirSync };

package/src/block.ts

@@ -58,8 +58,6 @@ export class Block {
 
   isSolid(options?: TaskOptions): Promise<boolean> { return Material.isSolid(this.type, options); }
   isSolidSync(options?: TaskOptions): boolean { return Material.isSolidSync(this.type, options); }
-  isLiquid(options?: TaskOptions): Promise<boolean> { return Material.isLiquid(this.type, options); }
-  isLiquidSync(options?: TaskOptions): boolean { return Material.isLiquidSync(this.type, options); }
   isAir(options?: TaskOptions): Promise<boolean> { return Material.isAir(this.type, options); }
   isAirSync(options?: TaskOptions): boolean { return Material.isAirSync(this.type, options); }
 

package/src/core.ts

@@ -1,7 +1,7 @@
 /// <reference path="global.d.ts" />
 /// <reference path="yeow-dev.d.ts" />
 
-export { call, callBatch, postBatch } from './task.js';
+export { call, post, callBatch, postBatch } from './task.js';
 export type { BatchTask } from './task.js';
 export { Location } from './location.js';
 export { Player } from './player.js';
@@ -43,16 +43,15 @@ export {
 export type { TpsInfo } from './server.js';
 export {
     fs,
-    readFile, readFileSync, readFileBase64, readFileBase64Sync,
-    writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
+    readFile, readFileSync,
+    writeFile, writeFileSync,
     appendFile, appendFileSync,
     exists, existsSync, stat, statSync,
     isDirectory, isDirectorySync,
     deleteFile, deleteFileSync, mkdir, mkdirSync, list, listSync,
 } from './fs.js';
-export type { FileStat } from './fs.js';
+export type { FileStat, FsEncoding, FsData, ReadFileOptions, WriteFileOptions } from './fs.js';
 export { assets, read as assetsRead, readSync as assetsReadSync,
-    readBase64 as assetsReadBase64, readBase64Sync as assetsReadBase64Sync,
     extract as assetsExtract, extractSync as assetsExtractSync,
     extractDir as assetsExtractDir, extractDirSync as assetsExtractDirSync } from './assets.js';
 export { path } from './path.js';

package/src/env.ts

@@ -12,6 +12,8 @@ export interface EnvInfo {
   yeow: { platform: string; version: string };
   /** epoch 微秒时间戳。 */
   now: number;
+  /** 插件数据目录路径（如 `plugins/my-plugin`；Worker 中为主插件目录）。 */
+  pluginDir: string;
 }
 
 /** 获取运行时环境信息（同步；含微秒时间戳）。 */

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 { ItemStack } from './item.js';
 import type { Message } from './message.js';
 
 // ── Event Data Interfaces ──────────────────────────────────────────
@@ -31,7 +32,7 @@ export interface PlayerInteractEvent {
   player: Player;
   action: string;
   material: string | null;
-  block: { x: number; y: number; z: number; type: string } | null;
+  block: { location: Location; type: string } | null;
   cancelled?: boolean;
 }
 export interface PlayerCommandEvent {
@@ -53,14 +54,12 @@ export interface PlayerRespawnEvent {
 }
 export interface PlayerDropItemEvent {
   player: Player;
-  itemType: string;
-  amount: number;
+  item: ItemStack;
   cancelled?: boolean;
 }
 export interface PlayerPickupItemEvent {
   player: Player;
-  itemType: string;
-  amount: number;
+  item: ItemStack;
   cancelled?: boolean;
 }
 export interface PlayerBucketFillEvent {
@@ -111,10 +110,7 @@ export interface EntityDeathEvent {
 export interface EntitySpawnEvent {
   entity: string;
   entityType: string;
-  x: number;
-  y: number;
-  z: number;
-  world: string;
+  location: Location;
   cancelled?: boolean;
 }
 export interface ProjectileLaunchEvent {
@@ -126,18 +122,14 @@ export interface ProjectileLaunchEvent {
 export interface BlockBreakEvent {
   player: Player;
   block: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   cancelled?: boolean;
 }
 export interface BlockPlaceEvent {
   player: Player;
   block: string;
   blockAgainst: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   cancelled?: boolean;
 }
 export interface InventoryOpenEvent {
@@ -177,7 +169,7 @@ export interface PlayerTeleportEvent {
 }
 export interface PlayerItemConsumeEvent {
   player: Player;
-  itemType: string;
+  item: ItemStack;
   cancelled?: boolean;
 }
 export interface PlayerAdvancementDoneEvent {
@@ -199,9 +191,7 @@ export interface PlayerToggleFlightEvent {
 export interface EntityExplodeEvent {
   entity: string;
   entityType: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   blockCount: number;
   cancelled?: boolean;
 }
@@ -220,35 +210,27 @@ export interface ProjectileHitEvent {
   entity: string;
   projectileType: string;
   hitEntity: string | null;
-  hitBlock: { x: number; y: number; z: number; type: string } | null;
+  hitBlock: { location: Location; type: string } | null;
   cancelled?: boolean;
 }
 export interface BlockFadeEvent {
   block: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   cancelled?: boolean;
 }
 export interface BlockGrowEvent {
   block: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   cancelled?: boolean;
 }
 export interface BlockSpreadEvent {
   block: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   cancelled?: boolean;
 }
 export interface BlockExplodeEvent {
   block: string;
-  x: number;
-  y: number;
-  z: number;
+  location: Location;
   cancelled?: boolean;
 }
 export interface ServerCommandEvent {
@@ -286,16 +268,12 @@ export interface InventoryClickEvent {
   isLeftClick: boolean;
   isRightClick: boolean;
   isShiftClick: boolean;
-  clickedItem: ItemData | null;
-  cursorItem: ItemData | null;
+  clickedItem: ItemStack | null;
+  cursorItem: ItemStack | null;
   /** 若点击发生在 Yeow 自定义 Inventory（Inventory.create 创建）：该 Inventory 的句柄 id（inventory.toString()）；否则缺省。 */
   inventoryId?: string;
   cancelled?: boolean;
 }
-interface ItemData {
-  type: string;
-  amount: number;
-}
 export interface PlayerResourcePackStatusEvent {
   player: Player;
   status: string;
@@ -382,6 +360,28 @@ function adaptEvent<K extends keyof EventMap>(type: K, data: RawEvent): { event:
   if (data.to) initial.to = loc(data.to as Record<string, unknown>);
   if (data.respawnLocation) initial.respawnLocation = loc(data.respawnLocation as Record<string, unknown>);
 
+  // 平铺坐标事件（entitySpawn / blockBreak 等）→ 统一 `location: Location`（与 from/to 同形；
+  // 原始 x/y/z/world 字段保留在事件对象上，兼容旧代码读取）。
+  if (typeof data.x === 'number' && typeof data.y === 'number' && typeof data.z === 'number') {
+    initial.location = loc(data);
+  }
+  // 嵌套方块坐标 → `{ location, type }`
+  if (type === 'playerInteract' && data.block && typeof data.block === 'object') {
+    const b = data.block as Record<string, unknown>;
+    initial.block = { type: b.type as string, location: loc(b) };
+  }
+  if (type === 'projectileHit' && data.hitBlock && typeof data.hitBlock === 'object') {
+    const b = data.hitBlock as Record<string, unknown>;
+    initial.hitBlock = { type: b.type as string, location: loc(b) };
+  }
+  // 物品事件字段统一为 ItemStack（{type, amount} 数据快照；原始 itemType/amount 保留）
+  if ((type === 'playerDropItem' || type === 'playerPickupItem') && data.itemType) {
+    initial.item = { type: data.itemType as string, amount: (data.amount as number) ?? 1 };
+  }
+  if (type === 'playerItemConsume' && data.itemType) {
+    initial.item = { type: data.itemType as string };
+  }
+
   // 修改收集：所有字段经 getter/setter——handler 直接赋值（e.xxx = ...）即记录为回写 mods。
   // cancelled 单独处理（仅可取消事件暴露；读取语义保持原状：未设置时返回 false）。
   const mods: Record<string, unknown> = {};
@@ -436,26 +436,42 @@ export function eventOn<K extends keyof EventMap>(
     const { event: wrapped, mods: mutatedMods } = adaptEvent(eventType, data);
     const eventId = data?._eventId;
 
-    if (manualRelease) {
-      const complete = (result?: Record<string, unknown>) => {
+    // 释放事件（event.complete）。处理器抛错时也必须释放——否则事件桥等待 complete
+    // 直到 5s 超时（EventBridge.timeoutMs），每次抛错都会卡住该事件并产生 event.timeout 噪音。
+    const release = (mods?: Record<string, unknown>) => {
+      try {
         $send('task', {
           type: 'event.complete',
-          params: { eventId, mods: result },
+          params: { eventId, mods },
           cb: '',
         });
-      };
-      (handler as ManualHandler<typeof eventType>)(wrapped, complete);
+      } catch { /* 桥故障：保留原始错误（若有），事件由 Java 侧超时兜底 */ }
+    };
+
+    if (manualRelease) {
+      const complete = (result?: Record<string, unknown>) => release(result);
+      try {
+        (handler as ManualHandler<typeof eventType>)(wrapped, complete);
+      } catch (e) {
+        release(); // 处理器同步抛错：立即释放（complete 幂等，重复调用无副作用）
+        throw e;
+      }
       return;
     }
 
-    const result = (handler as EventHandler<typeof eventType>)(wrapped);
-    // 回写合并：返回值（mods）优先合并，事件参数直接赋值（e.xxx = ...）覆盖之——
-    // 返回 Promise 时视为无修改（Promise 不展开），事件立即释放
-    const mods: Record<string, unknown> = {
-      ...(result && typeof result === 'object' ? result : {}),
-      ...mutatedMods,
-    };
-    $send('task', { type: 'event.complete', params: { eventId, mods }, cb: '' });
+    let result: unknown;
+    try {
+      result = (handler as EventHandler<typeof eventType>)(wrapped);
+    } finally {
+      // 回写合并：返回值（mods）优先合并，事件参数直接赋值（e.xxx = ...）覆盖之——
+      // 返回 Promise 时视为无修改（Promise 不展开），事件立即释放。
+      // finally 保证处理器抛错时也释放事件。
+      const mods: Record<string, unknown> = {
+        ...(result && typeof result === 'object' ? result : {}),
+        ...mutatedMods,
+      };
+      release(mods);
+    }
   }, { persistent: true });
 
   const gh = globalThis as any;

package/src/fs.ts

@@ -1,6 +1,21 @@
 type FsLevel = 'plugin' | 'server' | 'outer';
 
-import { stringToBytes } from './util.js';
+import { stringToBytes, bytesToString } from './util.js';
+
+/** 文件编码：utf8 = 文本；base64 = 将字符串视为 Base64 编码的二进制数据。 */
+export type FsEncoding = 'utf8' | 'base64';
+
+/** readFile 选项（Node 风格：缺省 encoding = 返回 Uint8Array）。 */
+export interface ReadFileOptions {
+  encoding?: FsEncoding;
+}
+
+/** writeFile / appendFile 选项：字符串默认 utf8；可指定 base64 将字符串视为二进制。 */
+export interface WriteFileOptions {
+  encoding?: FsEncoding;
+}
+
+export type FsData = string | Uint8Array;
 
 function _sendFs(payload: Record<string, unknown>): unknown {
   const r = $send('fs', payload);
@@ -19,46 +34,138 @@ function _sendFsAsync(payload: Record<string, unknown>): Promise<unknown> {
   });
 }
 
+/** 归一化 encoding 参数（string | { encoding }）；未知编码抛错。 */
+function _encoding(options?: FsEncoding | { encoding?: FsEncoding }): FsEncoding | undefined {
+  if (options == null) return undefined;
+  const e = typeof options === 'string' ? options : options.encoding;
+  if (e != null && e !== 'utf8' && e !== 'base64') {
+    throw new Error('Unsupported encoding: ' + String(e));
+  }
+  return e;
+}
+
+/** UTF-8 流式解码器：跨块保留不完整的多字节序列，EOF 时冲刷（非法序列替换为 U+FFFD）。 */
+function _makeUtf8StreamDecoder() {
+  let pending: Uint8Array = new Uint8Array(0);
+
+  const seqLen = (b: number) => {
+    if (b < 0x80) return 1;
+    if ((b & 0xE0) === 0xC0) return 2;
+    if ((b & 0xF0) === 0xE0) return 3;
+    if ((b & 0xF8) === 0xF0) return 4;
+    return 1; // 非法起始字节：交给 bytesToString 以替换字符处理
+  };
+
+  return {
+    push(chunk: Uint8Array): string | null {
+      const buf = pending.length
+        ? (() => { const b = new Uint8Array(pending.length + chunk.length); b.set(pending, 0); b.set(chunk, pending.length); return b; })()
+        : chunk;
+      if (!buf.length) return null;
+
+      let cut = buf.length;
+      const last = buf.length - 1;
+      if ((buf[last] & 0x80) !== 0) {
+        // 回溯找到可能的多字节序列起点（最多 3 个续字节）
+        let start = last;
+        let cont = 0;
+        while (cont < 3 && start > 0 && (buf[start] & 0xC0) === 0x80) { start--; cont++; }
+        const need = seqLen(buf[start]);
+        const have = buf.length - start;
+        if (need > 1 && have < need && need <= 4) {
+          // 仅当确实是合法起始字节时视为“序列未结束”，留给下一块
+          const validLead =
+            (need === 2 && (buf[start] & 0xE0) === 0xC0) ||
+            (need === 3 && (buf[start] & 0xF0) === 0xE0) ||
+            (need === 4 && (buf[start] & 0xF8) === 0xF0);
+          if (validLead) cut = start;
+        }
+      }
+
+      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;
+    },
+    /** EOF：把剩余的不完整序列交给 Java 解码（通常产出 U+FFFD）。 */
+    flush(): string | null {
+      if (!pending.length) return null;
+      const s = bytesToString(pending);
+      pending = new Uint8Array(0);
+      return s;
+    },
+  };
+}
+
 /** 按 fs 级别（plugin/server/outer）生成全套文件操作。 */
 function _makeFs(level: FsLevel) {
   const t = (op: string) => `${level}.${op}`;
 
-  async function readFile(path: string): Promise<string> {
-    const r = await _sendFsAsync({ t: t('readFile'), p: { path } }) as { data: string };
-    return r.data;
-  }
-  function readFileSync(path: string): string {
-    return (_sendFs({ t: t('readFile'), p: { path } }) as { data: string }).data;
-  }
-
-  async function readFileBase64(path: string): Promise<string> {
-    const r = await _sendFsAsync({ t: t('readBase64'), p: { path } }) as { data: string };
-    return r.data;
-  }
-  function readFileBase64Sync(path: string): string {
-    return (_sendFs({ t: t('readBase64'), p: { path } }) as { data: string }).data;
-  }
+  // ── 读文件：默认 Uint8Array；encoding 指定后返回字符串 ──────────
+  type ReadFileFn = {
+    (path: string): Promise<Uint8Array>;
+    (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): Promise<string>;
+    (path: string, options: ReadFileOptions): Promise<Uint8Array | string>;
+  };
+  type ReadFileSyncFn = {
+    (path: string): Uint8Array;
+    (path: string, options: FsEncoding | (ReadFileOptions & { encoding: FsEncoding })): string;
+    (path: string, options: ReadFileOptions): Uint8Array | string;
+  };
 
-  async function writeFile(path: string, data: string): Promise<void> {
-    await _sendFsAsync({ t: t('writeFile'), p: { path, data } });
-  }
-  function writeFileSync(path: string, data: string): void {
-    _sendFs({ t: t('writeFile'), p: { path, data } });
-  }
+  const readFileImpl = async (path: string, options?: FsEncoding | ReadFileOptions): Promise<Uint8Array | string> => {
+    const enc = _encoding(options);
+    const r = await _sendFsAsync({ t: t(enc === 'utf8' ? 'readFile' : 'readBase64'), p: { path } }) as { data: string };
+    if (enc === 'utf8' || enc === 'base64') return r.data;
+    return Uint8Array.fromBase64(r.data);
+  };
+  const readFileSyncImpl = (path: string, options?: FsEncoding | ReadFileOptions): Uint8Array | string => {
+    const enc = _encoding(options);
+    const r = _sendFs({ t: t(enc === 'utf8' ? 'readFile' : 'readBase64'), p: { path } }) as { data: string };
+    if (enc === 'utf8' || enc === 'base64') return r.data;
+    return Uint8Array.fromBase64(r.data);
+  };
+  const readFile = readFileImpl as ReadFileFn;
+  const readFileSync = readFileSyncImpl as ReadFileSyncFn;
 
-  async function writeFileBase64(path: string, data: string): Promise<void> {
-    await _sendFsAsync({ t: t('writeBase64'), p: { path, data } });
-  }
-  function writeFileBase64Sync(path: string, data: string): void {
-    _sendFs({ t: t('writeBase64'), p: { path, data } });
-  }
+  // ── 写文件：string 默认 utf8（可指定 base64），Uint8Array 写原始字节 ──
+  const writeFile = async (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): Promise<void> => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') await _sendFsAsync({ t: t('writeBase64'), p: { path, data } });
+      else await _sendFsAsync({ t: t('writeFile'), p: { path, data } });
+    } else {
+      await _sendFsAsync({ t: t('writeBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
+  const writeFileSync = (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): void => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') _sendFs({ t: t('writeBase64'), p: { path, data } });
+      else _sendFs({ t: t('writeFile'), p: { path, data } });
+    } else {
+      _sendFs({ t: t('writeBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
 
-  async function appendFile(path: string, data: string): Promise<void> {
-    await _sendFsAsync({ t: t('appendFile'), p: { path, data } });
-  }
-  function appendFileSync(path: string, data: string): void {
-    _sendFs({ t: t('appendFile'), p: { path, data } });
-  }
+  // ── 追加：与 writeFile 相同的数据/编码语义 ────────────────────────
+  const appendFile = async (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): Promise<void> => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') await _sendFsAsync({ t: t('appendBase64'), p: { path, data } });
+      else await _sendFsAsync({ t: t('appendFile'), p: { path, data } });
+    } else {
+      await _sendFsAsync({ t: t('appendBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
+  const appendFileSync = (path: string, data: FsData, options?: FsEncoding | WriteFileOptions): void => {
+    const enc = _encoding(options);
+    if (typeof data === 'string') {
+      if (enc === 'base64') _sendFs({ t: t('appendBase64'), p: { path, data } });
+      else _sendFs({ t: t('appendFile'), p: { path, data } });
+    } else {
+      _sendFs({ t: t('appendBase64'), p: { path, data: data.toBase64() } });
+    }
+  };
 
   async function exists(path: string): Promise<boolean> {
     const r = await _sendFsAsync({ t: t('exists'), p: { path } });
@@ -123,19 +230,47 @@ function _makeFs(level: FsLevel) {
     return (_sendFs({ t: t('getServerPath') }) as { path: string }).path;
   }
 
-  async function createReadStream(path: string, options?: ReadStreamOptions): Promise<ReadStream> {
-    const r = await _sendFsAsync({ t: t('openRead'), p: { path, ...options } }) as { id: string };
-    return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id);
-  }
+  // ── 读流：encoding 在创建时固定（默认 Uint8Array；utf8/base64 → string）──
+  type CreateReadStreamFn = {
+    (path: string): Promise<ReadStream<Uint8Array>>;
+    (path: string, options: ReadStreamOptions & { encoding?: undefined }): Promise<ReadStream<Uint8Array>>;
+    (path: string, options: ReadStreamOptions & { encoding: FsEncoding }): Promise<ReadStream<string>>;
+    (path: string, options: ReadStreamOptions): Promise<ReadStream<Uint8Array> | ReadStream<string>>;
+  };
 
+  const createReadStreamImpl = async (path: string, options?: ReadStreamOptions): Promise<ReadStream<Uint8Array> | ReadStream<string>> => {
+    const enc = _encoding(options);
+    const r = await _sendFsAsync({ t: t('openRead'), p: { path, start: options?.start, end: options?.end } }) as { id: string };
+    if (enc === 'base64') {
+      return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, {
+        push: (b64: string) => b64,
+        flush: () => null,
+      });
+    }
+    if (enc === 'utf8') {
+      const dec = _makeUtf8StreamDecoder();
+      return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, {
+        push: (b64: string) => dec.push(Uint8Array.fromBase64(b64)),
+        flush: () => dec.flush(),
+      });
+    }
+    return _makeReadStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, {
+      push: (b64: string) => Uint8Array.fromBase64(b64),
+      flush: () => null,
+    });
+  };
+  const createReadStream = createReadStreamImpl as CreateReadStreamFn;
+
+  // ── 写流：与 writeFile 相同的数据/编码语义（encoding 创建时固定）──
   async function createWriteStream(path: string, options?: WriteStreamOptions): Promise<WriteStream> {
-    const r = await _sendFsAsync({ t: t('openWrite'), p: { path, ...options } }) as { id: string };
-    return _makeWriteStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id);
+    const enc = _encoding(options);
+    const r = await _sendFsAsync({ t: t('openWrite'), p: { path, flags: options?.flags } }) as { id: string };
+    return _makeWriteStream((op, p2) => _sendFsAsync({ t: t(op), p: p2 }), r.id, enc);
   }
 
   return {
-    readFile, readFileSync, readFileBase64, readFileBase64Sync,
-    writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
+    readFile, readFileSync,
+    writeFile, writeFileSync,
     appendFile, appendFileSync,
     exists, existsSync, stat, statSync,
     isDirectory, isDirectorySync,
@@ -157,12 +292,8 @@ export const fs = {
 // 顶层函数 = plugin 级别（与 fs.* 一致）
 export const readFile = fs.readFile;
 export const readFileSync = fs.readFileSync;
-export const readFileBase64 = fs.readFileBase64;
-export const readFileBase64Sync = fs.readFileBase64Sync;
 export const writeFile = fs.writeFile;
 export const writeFileSync = fs.writeFileSync;
-export const writeFileBase64 = fs.writeFileBase64;
-export const writeFileBase64Sync = fs.writeFileBase64Sync;
 export const appendFile = fs.appendFile;
 export const appendFileSync = fs.appendFileSync;
 export const exists = fs.exists;
@@ -182,15 +313,17 @@ export const createWriteStream = fs.createWriteStream;
 
 // ── 流式读写（有状态句柄；背压 = 显式响应——每个操作 await 结果后才发起下一块）──
 
-/** 读流选项：字节偏移区间（start 含、end 含；缺省 = 全文件）。 */
+/** 读流选项：字节偏移区间（start 含、end 含）；encoding 创建时固定（默认 Uint8Array）。 */
 export interface ReadStreamOptions {
   start?: number;
   end?: number;
+  encoding?: FsEncoding;
 }
 
-/** 写流选项：打开模式——w 覆盖（默认）/ a 追加 / wx 排他创建（已存在报错）。 */
+/** 写流选项：打开模式 + 编码（encoding 创建时固定，运行时不可修改）。 */
 export interface WriteStreamOptions {
   flags?: 'w' | 'a' | 'wx';
+  encoding?: FsEncoding;
 }
 
 /** 文件状态（stat）。mtimeMs / ctimeMs 为 epoch 毫秒。 */
@@ -203,32 +336,39 @@ export interface FileStat {
 }
 
 /** 文件读流：read() 一次返回一块（默认 1 MiB），null = EOF；可 for await。 */
-export interface ReadStream {
-  read(maxBytes?: number): Promise<Uint8Array | null>;
+export interface ReadStream<Chunk = Uint8Array> {
+  read(maxBytes?: number): Promise<Chunk | null>;
   close(): Promise<void>;
-  [Symbol.asyncIterator](): AsyncIterator<Uint8Array>;
+  [Symbol.asyncIterator](): AsyncIterator<Chunk>;
 }
 
 /** 文件写流：write(chunk) 等到写入完成（显式响应背压），end() 冲刷并关闭。 */
 export interface WriteStream {
+  /** 创建时固定的编码；未指定时字符串 chunk 按 UTF-8 编码。运行时不可修改。 */
+  readonly encoding?: FsEncoding;
   write(chunk: Uint8Array | string): Promise<void>;
   /** 冲刷缓冲并关闭（调用后不可再 write）。 */
   end(): Promise<void>;
   close(): Promise<void>;
 }
 
-function _makeReadStream(
+function _makeReadStream<Chunk>(
   op: (name: string, p: Record<string, unknown>) => Promise<unknown>,
   id: string,
-): ReadStream {
+  decoder: { push(b64: string): Chunk | null; flush(): Chunk | null },
+): ReadStream<Chunk> {
   let closed = false;
   const check = () => { if (closed) throw new Error('read stream closed'); };
   return {
-    async read(maxBytes?: number) {
+    async read(maxBytes?: number): Promise<Chunk | null> {
       check();
-      const r = await op('read', { id, maxBytes }) as { data?: string; eof?: boolean };
-      if (r.eof) return null;
-      return Uint8Array.fromBase64(r.data as string);
+      while (true) {
+        const r = await op('read', { id, maxBytes }) as { data?: string; eof?: boolean };
+        if (r.eof) return decoder.flush();
+        const chunk = decoder.push(r.data as string);
+        // UTF-8 解码器可能因跨块多字节序列暂未产出——继续读下一块
+        if (chunk !== null) return chunk;
+      }
     },
     async close() {
       if (closed) return;
@@ -248,14 +388,19 @@ function _makeReadStream(
 function _makeWriteStream(
   op: (name: string, p: Record<string, unknown>) => Promise<unknown>,
   id: string,
+  encoding?: FsEncoding,
 ): WriteStream {
   let closed = false;
   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,
     async write(chunk: Uint8Array | string) {
       check();
-      const data = typeof chunk === 'string' ? stringToBytes(chunk) : chunk;
-      await op('write', { id, data: data.toBase64() });
+      await op('write', { id, data: toBytes(chunk).toBase64() });
     },
     async end() {
       check();

package/src/http.ts

@@ -11,10 +11,13 @@ interface HttpResult {
 export interface RespondOptions {
   /** HTTP 状态码（默认 200）。 */
   status?: number;
-  /** 文本响应体（UTF-8）。 */
-  body?: string;
-  /** base64 编码的**二进制**响应体（与 body 互斥，优先）——如从 assets 读取的资源包等。 */
-  bodyBase64?: string;
+  /**
+   * 响应体：`Uint8Array` 直接作为二进制写出；字符串按 `encoding` 解释
+   * （默认 UTF-8 文本；`'base64'` 时视为 base64 编码的二进制数据）。
+   */
+  body?: string | Uint8Array;
+  /** body 为字符串时的编码：`'utf8'`（默认）或 `'base64'`（base64 编码的二进制）；Uint8Array 时忽略。 */
+  encoding?: 'utf8' | 'base64';
   /** 响应头。 */
   headers?: Record<string, string>;
 }
@@ -44,7 +47,17 @@ export function listen(callback: (req: Record<string, unknown>) => void, port?:
 }
 
 export function respond(serverId: string, connId: string, opts: RespondOptions = {}): void {
-  _sendHttp({ t: 'respond', p: { serverId, connId, ...opts } });
+  const p: Record<string, unknown> = { serverId, connId };
+  if (opts.body instanceof Uint8Array) {
+    p.body = opts.body.toBase64();   // Uint8Array → 二进制（base64 承载）
+    p.encoding = 'base64';
+  } else {
+    p.body = opts.body;
+    if (opts.encoding === 'base64') p.encoding = 'base64';
+  }
+  if (opts.status !== undefined) p.status = opts.status;
+  if (opts.headers !== undefined) p.headers = opts.headers;
+  _sendHttp({ t: 'respond', p });
 }
 
 export function close(serverId: string): void {

package/src/instance-id.ts

@@ -2,11 +2,16 @@ let _seq = 0;
 // 每个插件 QuickJS 上下文独立（模块级变量彼此隔离）；随机种子保证
 // 跨插件/跨 Worker 生成的 id 全局唯一——id 是不透明句柄，不携带任何业务信息。
 const _seed = Math.random().toString(36).slice(2, 12);
-const _gcQueue: string[] = [];
+// GC 队列必须复用运行时（init.js）创建的全局数组（读已有 / 否则创建）：
+// 1) init.js 的 _flushGC 在每次消息分发后冲刷该数组并上报 gc-collect；
+//    若此处新建数组覆盖全局，FinalizationRegistry 回调推入的 id 永远不会被冲刷。
+// 2) 多 yeow-api 副本共存时（peer 范围不重叠、npm 安装独立副本），共享同一
+//    数组可保证所有副本的句柄回收都进入同一条上报通道。
+const _g = globalThis as any;
+const _gcQueue: string[] = _g.__yeowGcQueue || (_g.__yeowGcQueue = []);
 const _gcReg = typeof FinalizationRegistry !== 'undefined'
   ? new FinalizationRegistry<string>((raw: string) => { _gcQueue.push(raw); })
   : null;
-(globalThis as any).__yeowGcQueue = _gcQueue;
 
 export class InstanceId {
   readonly _raw: string;

package/src/lifecycle.ts

@@ -1,11 +1,30 @@
-const _initCbs: (() => void)[] = [];
-const _loadCbs: (() => void)[] = [];
-const _unloadCbs: (() => void)[] = [];
+// 生命周期钩子注册表（共享全局数组）。
+//
+// 多 yeow-api 副本共存（npm 语义化版本规则：peer 范围不重叠时依赖包自带
+// 独立副本）时，每个副本的模块级数组必须指向**同一个**全局数组——
+// 若各副本直接 `globalThis.__yeowInitCbs = <自身数组>`，后加载的副本会
+// 覆盖先加载副本注册的回调（表现为 onLoad 不执行）。读已有 / 否则创建：
+// 首个加载的副本创建数组，后续副本复用，运行时（init.js）读取同一数组。
+const _global = globalThis as any;
+const _initCbs: (() => void)[] = _global.__yeowInitCbs || (_global.__yeowInitCbs = []);
+const _loadCbs: (() => void)[] = _global.__yeowLoadCbs || (_global.__yeowLoadCbs = []);
+const _unloadCbs: (() => void)[] = _global.__yeowUnloadCbs || (_global.__yeowUnloadCbs = []);
 
-export function onInit(cb: () => void): void { _initCbs.push(cb); }
-export function onLoad(cb: () => void): void { _loadCbs.push(cb); }
-export function onUnload(cb: () => void): void { _unloadCbs.push(cb); }
+// dev 模式栈追踪：在注册点捕获调用栈挂到回调函数上（__yeowNode）。
+// 运行时（init.js）分发钩子时优先使用它作为该钩子的栈上下文——比 init.js
+// 分发点的内部帧更能还原用户调用链（外层回调经 _getCurrentCbStack 连接）。
+// 仅 $dev 时捕获（QuickJS 的 Error.stack 为懒构建 getter，无访问即无成本）。
+function _attachNode(cb: () => void): void {
+    try {
+        if (!_global.$dev) return;
+        const getCb = _global._getCurrentCbStack;
+        (cb as any).__yeowNode = {
+            stack: new Error().stack,
+            outer: typeof getCb === 'function' ? getCb() : null,
+        };
+    } catch { /* 注册点捕获失败不影响钩子注册 */ }
+}
 
-(globalThis as any).__yeowInitCbs = _initCbs;
-(globalThis as any).__yeowLoadCbs = _loadCbs;
-(globalThis as any).__yeowUnloadCbs = _unloadCbs;
+export function onInit(cb: () => void): void { _attachNode(cb); _initCbs.push(cb); }
+export function onLoad(cb: () => void): void { _attachNode(cb); _loadCbs.push(cb); }
+export function onUnload(cb: () => void): void { _attachNode(cb); _unloadCbs.push(cb); }

package/src/material.ts

@@ -37,7 +37,7 @@ export async function getItems(options?: TaskOptions): Promise<string[]> {
 
 /**
  * Material —— 材料级静态判断对象（不依赖坐标/状态）。
- * 基于方块类型（material）判断其固有属性：固体/液体/空气。
+ * 基于方块类型（material）判断其固有属性：固体/空气。
  */
 export const Material = {
   /** 是否为固体方块（基于类型，状态不影响）。 */
@@ -48,14 +48,6 @@ export const Material = {
     return call<boolean>('material.isSolid', { type }, options);
   },
 
-  /** 是否为液体（水 / 熔岩）。 */
-  isLiquid(type: string, options?: TaskOptions): Promise<boolean> {
-    return post<boolean>('material.isLiquid', { type }, options);
-  },
-  isLiquidSync(type: string, options?: TaskOptions): boolean {
-    return call<boolean>('material.isLiquid', { type }, options);
-  },
-
   /** 是否为空气（空方块）。 */
   isAir(type: string, options?: TaskOptions): Promise<boolean> {
     return post<boolean>('material.isAir', { type }, options);

package/src/player.ts

@@ -79,7 +79,7 @@ export class Player {
   isOpAsync(options?: TaskOptions): Promise<boolean> { return post<boolean>('player.isOp', { uuid: this.uuid }, options); }
 
   get online(): boolean { return call<boolean>('player.isOnline', { uuid: this.uuid }); }
-  getOnline(options?: TaskOptions): Promise<boolean> { return post<boolean>('player.isOnline', { uuid: this.uuid }, options); }
+  isOnlineAsync(options?: TaskOptions): Promise<boolean> { return post<boolean>('player.isOnline', { uuid: this.uuid }, options); }
 
   get isFlying(): boolean { return call<boolean>('player.isFlying', { uuid: this.uuid }); }
   set isFlying(v: boolean) { call('player.setFlying', { uuid: this.uuid, value: v }); }

package/src/task.ts

@@ -73,12 +73,23 @@ export interface BatchTask {
   priority?: 'high' | 'normal' | 'low';
 }
 
-/** 同步批量：阻塞直到全部任务完成，返回结果数组（顺序对应 tasks；单个任务失败时对应项为 `{err}` 对象）。 */
+/** 同步批量：阻塞直到全部任务完成，返回结果数组（顺序对应 tasks；单个任务失败时对应项为 `{err}` 对象——与单任务 call/post 抛 Error 不同，批量保留部分结果）。 */
 export function callBatch(tasks: BatchTask[]): unknown[] {
   if (tasks.length === 0) return [];
   const r = $send('task', { tasks });
   if (r == null) return [];
-  if ((r as any)?.err) throw new Error((r as any).err);
+  if ((r as any)?.err) {
+    // 与 call/post 对齐的错误上下文（type/task/Java 堆栈）
+    const errObj = r as any;
+    const msg = errObj.type ? `[${errObj.type}] ${errObj.err}` : errObj.err;
+    const e = new Error(msg);
+    if (errObj.stack) {
+      e.stack += '\n    --- runtime executer error(for reference) ---\n' + errObj.stack;
+    }
+    (e as any).javaType = errObj.type || null;
+    (e as any).taskType = errObj.task || null;
+    throw e;
+  }
   return r as unknown[];
 }
 

package/src/world.ts

@@ -3,6 +3,7 @@ import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
 import { Block } from './block.js';
 import type { BlockState } from './block.js';
+import type { ItemStack } from './item.js';
 import { Chunk, ChunkData } from './chunk.js';
 
 interface WorldData {
@@ -103,14 +104,23 @@ export class World {
   setBorderDamage(amount?: number, buffer?: number, options?: TaskOptions): Promise<boolean> {
     return post<boolean>('world.setBorderDamage', { world: this.name, amount, buffer }, options);
   }
+  setBorderDamageSync(amount?: number, buffer?: number, options?: TaskOptions): boolean {
+    return call<boolean>('world.setBorderDamage', { world: this.name, amount, buffer }, options);
+  }
   /** 边界警告（distance 方块距离；time 秒）。 */
   setBorderWarning(distance?: number, time?: number, options?: TaskOptions): Promise<boolean> {
     return post<boolean>('world.setBorderWarning', { world: this.name, distance, time }, options);
   }
+  setBorderWarningSync(distance?: number, time?: number, options?: TaskOptions): boolean {
+    return call<boolean>('world.setBorderWarning', { world: this.name, distance, time }, options);
+  }
   /** 边界平滑移动（from → to，seconds 秒）。 */
   setBorderMoving(from: number, to: number, seconds: number, options?: TaskOptions): Promise<boolean> {
     return post<boolean>('world.setBorderMoving', { world: this.name, from, to, seconds }, options);
   }
+  setBorderMovingSync(from: number, to: number, seconds: number, options?: TaskOptions): boolean {
+    return call<boolean>('world.setBorderMoving', { world: this.name, from, to, seconds }, options);
+  }
   getChunkAt(x: number, z: number, options?: TaskOptions): Promise<Chunk> {
     return post<ChunkData>('world.getChunkAt', { world: this.name, x, z }, options).then((d) => Chunk.from(d));
   }
@@ -211,11 +221,16 @@ export class World {
   getNearbyEntitiesSync(x: number, y: number, z: number, radius: number, options?: TaskOptions): string[] {
     return call<string[]>('world.getNearbyEntities', { world: this.name, x, y, z, radius }, options);
   }
-  dropItem(x: number, y: number, z: number, itemType: string, amount?: number, options?: TaskOptions): Promise<void> {
-    return post('world.dropItem', { world: this.name, x, y, z, itemType, amount }, options);
+  /** 在指定位置掉落物品（`item` 为 ItemStack 数据快照或材质名字符串；字符串时可用 `amount` 指定数量——旧式参数兼容）。 */
+  dropItem(x: number, y: number, z: number, item: ItemStack | string, amount?: number, options?: TaskOptions): Promise<void> {
+    const it: Record<string, unknown> = typeof item === 'string' ? { type: item } : { ...item };
+    if (typeof item === 'string' && amount !== undefined) it.amount = amount;
+    return post('world.dropItem', { world: this.name, x, y, z, item: it }, options);
   }
-  dropItemSync(x: number, y: number, z: number, itemType: string, amount?: number, options?: TaskOptions): void {
-    call('world.dropItem', { world: this.name, x, y, z, itemType, amount }, options);
+  dropItemSync(x: number, y: number, z: number, item: ItemStack | string, amount?: number, options?: TaskOptions): void {
+    const it: Record<string, unknown> = typeof item === 'string' ? { type: item } : { ...item };
+    if (typeof item === 'string' && amount !== undefined) it.amount = amount;
+    call('world.dropItem', { world: this.name, x, y, z, item: it }, options);
   }
   strikeLightning(x: number, y: number, z: number, options?: TaskOptions): Promise<void> {
     return post('world.strikeLightning', { world: this.name, x, y, z }, options);