yeow-api 0.2.59 → 0.2.101

package/package.json

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

package/src/chunk.ts

@@ -0,0 +1,122 @@
+import { call, post } from './task.js';
+
+export interface ChunkData {
+  x: number;
+  z: number;
+  world: string;
+}
+
+/** 模块级缓存：方块 key 列表（= Java 侧索引基准，运行时内稳定）。 */
+let _blocksCache: string[] | null = null;
+
+async function ensureBlocks(): Promise<string[]> {
+  if (_blocksCache) return _blocksCache;
+  const blocks = await post<string[]>('server.getBlocks', {});
+  _blocksCache = blocks;
+  return blocks;
+}
+
+function ensureBlocksSync(): string[] {
+  if (_blocksCache) return _blocksCache;
+  const blocks = call<string[]>('server.getBlocks', {});
+  _blocksCache = blocks;
+  return blocks;
+}
+
+/** base64(little-endian short[]) → Uint16Array：直接视图，零拷贝零遍历。 */
+function decodeShortArray(b64: string): Uint16Array {
+  const bytes = Uint8Array.fromBase64(b64);
+  return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.length >>> 1);
+}
+
+/**
+ * 完整区块快照（3D）：方块类型索引数组，与 `getBlocks()` 的数组下标对应。
+ * 索引仅当前运行时有效（重启后可能变化），不可持久化。
+ */
+export class ChunkSnapshot {
+  constructor(
+    readonly data: Uint16Array,
+    readonly minY: number,
+    readonly height: number,
+    readonly blocks: string[],
+  ) {}
+
+  /** 绝对高度 y 处的方块 key（越界/未知索引回退 minecraft:air）。 */
+  getBlock(x: number, y: number, z: number): string {
+    const ry = y - this.minY;
+    if (x < 0 || x > 15 || z < 0 || z > 15 || ry < 0 || ry >= this.height) return 'minecraft:air';
+    return this.blocks[this.data[(ry * 16 + z) * 16 + x]] ?? 'minecraft:air';
+  }
+
+  /** 绝对高度 y 处的原始方块索引。 */
+  getBlockIndex(x: number, y: number, z: number): number {
+    const ry = y - this.minY;
+    if (x < 0 || x > 15 || z < 0 || z > 15 || ry < 0 || ry >= this.height) return 0;
+    return this.data[(ry * 16 + z) * 16 + x];
+  }
+
+  static async fromRaw(raw: { data: string; minY: number; height: number }): Promise<ChunkSnapshot> {
+    return new ChunkSnapshot(decodeShortArray(raw.data), raw.minY, raw.height, await ensureBlocks());
+  }
+
+  static fromRawSync(raw: { data: string; minY: number; height: number }): ChunkSnapshot {
+    return new ChunkSnapshot(decodeShortArray(raw.data), raw.minY, raw.height, ensureBlocksSync());
+  }
+}
+
+/**
+ * 顶部方块快照（2D，256 元素）：每列最高非空气方块的类型索引，顺序 z 外层 → x 内层。
+ * 索引仅当前运行时有效，不可持久化。
+ */
+export class ChunkTopSnapshot {
+  constructor(
+    readonly data: Uint16Array,
+    readonly blocks: string[],
+  ) {}
+
+  getTop(x: number, z: number): string {
+    if (x < 0 || x > 15 || z < 0 || z > 15) return 'minecraft:air';
+    return this.blocks[this.data[z * 16 + x]] ?? 'minecraft:air';
+  }
+
+  getTopIndex(x: number, z: number): number {
+    if (x < 0 || x > 15 || z < 0 || z > 15) return 0;
+    return this.data[z * 16 + x];
+  }
+
+  static async fromRaw(raw: { data: string }): Promise<ChunkTopSnapshot> {
+    return new ChunkTopSnapshot(decodeShortArray(raw.data), await ensureBlocks());
+  }
+
+  static fromRawSync(raw: { data: string }): ChunkTopSnapshot {
+    return new ChunkTopSnapshot(decodeShortArray(raw.data), ensureBlocksSync());
+  }
+}
+
+export class Chunk {
+  constructor(
+    public readonly x: number,
+    public readonly z: number,
+    public readonly world: string,
+  ) {}
+
+  static from(d: ChunkData): Chunk {
+    return new Chunk(d.x, d.z, d.world);
+  }
+
+  /** 完整方块快照（16×16×世界高度，y 外层 → z → x）。重量级操作，适合低频/批量场景。 */
+  getSnapshot(): Promise<ChunkSnapshot> {
+    return post<{ data: string; minY: number; height: number }>('chunk.getSnapshot', { world: this.world, x: this.x, z: this.z }).then(ChunkSnapshot.fromRaw);
+  }
+  getSnapshotSync(): ChunkSnapshot {
+    return ChunkSnapshot.fromRawSync(call<{ data: string; minY: number; height: number }>('chunk.getSnapshot', { world: this.world, x: this.x, z: this.z }));
+  }
+
+  /** 顶部方块快照（256 元素，每列最高非空气方块，z 外层 → x 内层）。 */
+  getTopSnapshot(): Promise<ChunkTopSnapshot> {
+    return post<{ data: string }>('chunk.getTopSnapshot', { world: this.world, x: this.x, z: this.z }).then(ChunkTopSnapshot.fromRaw);
+  }
+  getTopSnapshotSync(): ChunkTopSnapshot {
+    return ChunkTopSnapshot.fromRawSync(call<{ data: string }>('chunk.getTopSnapshot', { world: this.world, x: this.x, z: this.z }));
+  }
+}

package/src/entity.ts

@@ -1,6 +1,15 @@
 import { call, post } from './task.js';
 import { Location, LocationData } from './location.js';
 
+export interface BoundingBox {
+  minX: number;
+  minY: number;
+  minZ: number;
+  maxX: number;
+  maxY: number;
+  maxZ: number;
+}
+
 export class Entity {
   static get(uuid: string): Promise<Entity | null> {
     return post<{ uuid: string }>('entity.get', { uuid }).then((d) => (d ? new Entity(d.uuid) : null));
@@ -67,6 +76,11 @@ export class Entity {
   get vehicle(): string | null { return call<string | null>('entity.getVehicle', { uuid: this.uuid }); }
   getVehicle(): Promise<string | null> { return post<string | null>('entity.getVehicle', { uuid: this.uuid }); }
 
+  get boundingBox(): BoundingBox {
+    return call<BoundingBox>('entity.getBoundingBox', { uuid: this.uuid });
+  }
+  getBoundingBox(): Promise<BoundingBox> { return post<BoundingBox>('entity.getBoundingBox', { uuid: this.uuid }); }
+
   remove(): Promise<void> { return post('entity.remove', { uuid: this.uuid }); }
   removeSync(): void { call('entity.remove', { uuid: this.uuid }); }
   teleport(loc: Location): Promise<void> { return post('entity.teleport', { uuid: this.uuid, ...loc.toObject() }); }

package/src/event.ts

@@ -168,6 +168,18 @@ export interface PlayerItemConsumeEvent {
   itemType: string;
   cancelled?: boolean;
 }
+export interface PlayerAdvancementDoneEvent {
+  player: Player;
+  advancement: string;
+}
+export interface PlayerToggleSneakEvent {
+  player: Player;
+  sneaking: boolean;
+}
+export interface PlayerToggleFlightEvent {
+  player: Player;
+  flying: boolean;
+}
 export interface EntityExplodeEvent {
   entity: string;
   entityType: string;
@@ -268,6 +280,9 @@ type EventMap = {
   playerExpChange: PlayerExpChangeEvent;
   playerLevelChange: PlayerLevelChangeEvent;
   playerGameModeChange: PlayerGameModeChangeEvent;
+  playerAdvancementDone: PlayerAdvancementDoneEvent;
+  playerToggleSneak: PlayerToggleSneakEvent;
+  playerToggleFlight: PlayerToggleFlightEvent;
   foodLevelChange: FoodLevelChangeEvent;
   entityDamage: EntityDamageEvent;
   entityDeath: EntityDeathEvent;

package/src/fs.ts

@@ -1,3 +1,5 @@
+type FsLevel = 'plugin' | 'server' | 'outer';
+
 function _sendFs(payload: Record<string, unknown>): unknown {
   const r = $send('fs', payload);
   if (r == null) return undefined;
@@ -15,88 +17,132 @@ function _sendFsAsync(payload: Record<string, unknown>): Promise<unknown> {
   });
 }
 
-export async function readFile(path: string): Promise<string> {
-  const r = await _sendFsAsync({ t: 'readFile', p: { path } }) as { data: string };
-  return r.data;
-}
-export function readFileSync(path: string): string {
-  return (_sendFs({ t: 'readFile', p: { path } }) as { data: string }).data;
-}
+/** 按 fs 级别（plugin/server/outer）生成全套文件操作。 */
+function _makeFs(level: FsLevel) {
+  const t = (op: string) => `${level}.${op}`;
 
-export async function readFileBase64(path: string): Promise<string> {
-  const r = await _sendFsAsync({ t: 'readBase64', p: { path } }) as { data: string };
-  return r.data;
-}
-export function readFileBase64Sync(path: string): string {
-  return (_sendFs({ t: 'readBase64', p: { path } }) as { data: string }).data;
-}
+  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;
+  }
 
-export async function writeFile(path: string, data: string): Promise<void> {
-  await _sendFsAsync({ t: 'writeFile', p: { path, data } });
-}
-export function writeFileSync(path: string, data: string): void {
-  _sendFs({ t: 'writeFile', p: { path, 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;
+  }
 
-export async function writeFileBase64(path: string, data: string): Promise<void> {
-  await _sendFsAsync({ t: 'writeBase64', p: { path, data } });
-}
-export function writeFileBase64Sync(path: string, data: string): void {
-  _sendFs({ t: 'writeBase64', p: { path, data } });
-}
+  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 } });
+  }
 
-export async function appendFile(path: string, data: string): Promise<void> {
-  await _sendFsAsync({ t: 'appendFile', p: { path, data } });
-}
-export function appendFileSync(path: string, data: string): void {
-  _sendFs({ t: 'appendFile', p: { path, data } });
-}
+  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 } });
+  }
 
-export async function exists(path: string): Promise<boolean> {
-  const r = await _sendFsAsync({ t: 'exists', p: { path } });
-  return r === true || String(r) === 'true';
-}
-export function existsSync(path: string): boolean {
-  const r = _sendFs({ t: 'exists', p: { path } });
-  return r === true || String(r) === 'true';
-}
+  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 } });
+  }
 
-export async function isDirectory(path: string): Promise<boolean> {
-  const r = await _sendFsAsync({ t: 'isDirectory', p: { path } });
-  return r === true || String(r) === 'true';
-}
-export function isDirectorySync(path: string): boolean {
-  const r = _sendFs({ t: 'isDirectory', p: { path } });
-  return r === true || String(r) === 'true';
-}
+  async function exists(path: string): Promise<boolean> {
+    const r = await _sendFsAsync({ t: t('exists'), p: { path } });
+    return r === true || String(r) === 'true';
+  }
+  function existsSync(path: string): boolean {
+    const r = _sendFs({ t: t('exists'), p: { path } });
+    return r === true || String(r) === 'true';
+  }
 
-export async function deleteFile(path: string): Promise<boolean> {
-  const r = await _sendFsAsync({ t: 'delete', p: { path } });
-  return r === true || String(r) === 'true';
-}
-export function deleteFileSync(path: string): boolean {
-  const r = _sendFs({ t: 'delete', p: { path } });
-  return r === true || String(r) === 'true';
-}
+  async function isDirectory(path: string): Promise<boolean> {
+    const r = await _sendFsAsync({ t: t('isDirectory'), p: { path } });
+    return r === true || String(r) === 'true';
+  }
+  function isDirectorySync(path: string): boolean {
+    const r = _sendFs({ t: t('isDirectory'), p: { path } });
+    return r === true || String(r) === 'true';
+  }
 
-export async function mkdir(path: string): Promise<void> {
-  await _sendFsAsync({ t: 'mkdir', p: { path } });
-}
-export function mkdirSync(path: string): void {
-  _sendFs({ t: 'mkdir', p: { path } });
-}
+  async function deleteFile(path: string): Promise<boolean> {
+    const r = await _sendFsAsync({ t: t('delete'), p: { path } });
+    return r === true || String(r) === 'true';
+  }
+  function deleteFileSync(path: string): boolean {
+    const r = _sendFs({ t: t('delete'), p: { path } });
+    return r === true || String(r) === 'true';
+  }
 
-export async function list(path: string): Promise<string[]> {
-  return await _sendFsAsync({ t: 'list', p: { path } }) as string[];
-}
-export function listSync(path: string): string[] {
-  return _sendFs({ t: 'list', p: { path } }) as string[];
+  async function mkdir(path: string): Promise<void> {
+    await _sendFsAsync({ t: t('mkdir'), p: { path } });
+  }
+  function mkdirSync(path: string): void {
+    _sendFs({ t: t('mkdir'), p: { path } });
+  }
+
+  async function list(path: string): Promise<string[]> {
+    return await _sendFsAsync({ t: t('list'), p: { path } }) as string[];
+  }
+  function listSync(path: string): string[] {
+    return _sendFs({ t: t('list'), p: { path } }) as string[];
+  }
+
+  async function systemPaths(): Promise<{ home: string; desktop: string; temp: string }> {
+    return await _sendFsAsync({ t: t('systemPaths') }) as { home: string; desktop: string; temp: string };
+  }
+  function systemPathsSync(): { home: string; desktop: string; temp: string } {
+    return _sendFs({ t: t('systemPaths') }) as { home: string; desktop: string; temp: string };
+  }
+
+  return {
+    readFile, readFileSync, readFileBase64, readFileBase64Sync,
+    writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
+    appendFile, appendFileSync,
+    exists, existsSync, isDirectory, isDirectorySync,
+    deleteFile, deleteFileSync, mkdir, mkdirSync, list, listSync,
+    // systemPaths 仅 outer 级提供（fs.outer.systemPaths）
+    ...(level === 'outer' ? { systemPaths, systemPathsSync } : {}),
+  };
 }
 
+// fs.* 为 plugin 级别（插件数据目录 plugins/<name>/，无需声明权限）；
+// fs.server.* / fs.outer.* 需在 yeow.config.json 声明 fs:server.* / fs:outer.*。
 export const fs = {
-  readFile, readFileSync, readFileBase64, readFileBase64Sync,
-  writeFile, writeFileSync, writeFileBase64, writeFileBase64Sync,
-  appendFile, appendFileSync,
-  exists, existsSync, isDirectory, isDirectorySync,
-  deleteFile, deleteFileSync, mkdir, mkdirSync, list, listSync,
+  ..._makeFs('plugin'),
+  server: _makeFs('server'),
+  outer: _makeFs('outer'),
 };
+
+// 顶层函数 = 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;
+export const existsSync = fs.existsSync;
+export const isDirectory = fs.isDirectory;
+export const isDirectorySync = fs.isDirectorySync;
+export const deleteFile = fs.deleteFile;
+export const deleteFileSync = fs.deleteFileSync;
+export const mkdir = fs.mkdir;
+export const mkdirSync = fs.mkdirSync;
+export const list = fs.list;
+export const listSync = fs.listSync;

package/src/global.d.ts

@@ -28,8 +28,12 @@ declare global {
         { cbId: string; handler: Function; manualRelease: boolean }[]
       >
     | undefined;
+}
 
-  function uint8ArrayToBase64(buffer: ArrayBuffer): string;
-  function base64ToUint8Array(base64: string): ArrayBuffer;
+// yeow-dev：构建期虚拟模块（由 Yeow 构建器按 importer 所属依赖项注入命名空间）。
+// 插件未安装 yeow-dev 时此声明生效；类型与实际构建行为一致。
+declare module 'yeow-dev' {
+  export function getAssetsPath(path: string): string;
 }
+
 export {};

package/src/index.ts

@@ -4,7 +4,10 @@ export { call } from './task.js';
 export { Location } from './location.js';
 export { Player } from './player.js';
 export { World } from './world.js';
+export { Chunk, ChunkSnapshot, ChunkTopSnapshot } from './chunk.js';
+export type { ChunkData } from './chunk.js';
 export { Entity, LivingEntity } from './entity.js';
+export type { BoundingBox } from './entity.js';
 export { Block } from './block.js';
 export { Inventory } from './inventory.js';
 export { registerCommand } from './command.js';
@@ -14,6 +17,7 @@ export type {
     PlayerJoinEvent, PlayerQuitEvent, PlayerChatEvent, PlayerMoveEvent,
     PlayerInteractEvent, PlayerCommandEvent, PlayerDeathEvent, PlayerRespawnEvent,
     PlayerTeleportEvent, PlayerItemConsumeEvent,
+    PlayerAdvancementDoneEvent, PlayerToggleSneakEvent, PlayerToggleFlightEvent,
     PlayerDropItemEvent, PlayerPickupItemEvent, PlayerBucketFillEvent, PlayerBucketEmptyEvent,
     PlayerExpChangeEvent, PlayerLevelChangeEvent, PlayerGameModeChangeEvent, FoodLevelChangeEvent,
     EntityDamageEvent, EntityDeathEvent, EntitySpawnEvent, EntityExplodeEvent,
@@ -41,7 +45,6 @@ export {
 export { assets, read as assetsRead, readSync as assetsReadSync,
     readBase64 as assetsReadBase64, readBase64Sync as assetsReadBase64Sync,
     extract as assetsExtract, extractSync as assetsExtractSync } from './assets.js';
-export { getAssetsPath } from './assets-path.js';
 export { path } from './path.js';
 export { listen, respond, close, request } from './http.js';
 export { logError } from './log-error.js';

package/src/player.ts

@@ -65,6 +65,19 @@ export class Player {
   isFlyingAsync(): Promise<boolean> { return post<boolean>('player.isFlying', { uuid: this.uuid }); }
   setFlying(v: boolean): Promise<void> { return post('player.setFlying', { uuid: this.uuid, value: v }); }
 
+  get isSneaking(): boolean { return call<boolean>('player.isSneaking', { uuid: this.uuid }); }
+  isSneakingAsync(): Promise<boolean> { return post<boolean>('player.isSneaking', { uuid: this.uuid }); }
+  get isSprinting(): boolean { return call<boolean>('player.isSprinting', { uuid: this.uuid }); }
+  isSprintingAsync(): Promise<boolean> { return post<boolean>('player.isSprinting', { uuid: this.uuid }); }
+
+  get bedLocation(): Location | null {
+    const r = call<LocationData>('player.getBedLocation', { uuid: this.uuid });
+    return r ? Location.from(r) : null;
+  }
+  getBedLocation(): Promise<Location | null> {
+    return post<LocationData>('player.getBedLocation', { uuid: this.uuid }).then((r) => (r ? Location.from(r) : null));
+  }
+
   get allowFlight(): boolean { return call<boolean>('player.getAllowFlight', { uuid: this.uuid }); }
   set allowFlight(v: boolean) { call('player.setAllowFlight', { uuid: this.uuid, value: v }); }
   getAllowFlight(): Promise<boolean> { return post<boolean>('player.getAllowFlight', { uuid: this.uuid }); }

package/src/world.ts

@@ -1,6 +1,7 @@
 import { call, post } from './task.js';
 import { Location, LocationData } from './location.js';
 import { Block } from './block.js';
+import { Chunk, ChunkData } from './chunk.js';
 
 interface WorldData {
   name: string;
@@ -43,6 +44,42 @@ export class World {
   getHighestBlockYSync(x: number, z: number): number {
     return call<number>('world.getHighestBlockY', { world: this.name, x, z });
   }
+  getChunkAt(x: number, z: number): Promise<Chunk> {
+    return post<ChunkData>('world.getChunkAt', { world: this.name, x, z }).then((d) => Chunk.from(d));
+  }
+  getChunkAtSync(x: number, z: number): Chunk {
+    return Chunk.from(call<ChunkData>('world.getChunkAt', { world: this.name, x, z }));
+  }
+  isChunkLoaded(x: number, z: number): Promise<boolean> {
+    return post<boolean>('world.isChunkLoaded', { world: this.name, x, z });
+  }
+  isChunkLoadedSync(x: number, z: number): boolean {
+    return call<boolean>('world.isChunkLoaded', { world: this.name, x, z });
+  }
+  loadChunk(x: number, z: number): Promise<boolean> {
+    return post<boolean>('world.loadChunk', { world: this.name, x, z });
+  }
+  loadChunkSync(x: number, z: number): boolean {
+    return call<boolean>('world.loadChunk', { world: this.name, x, z });
+  }
+  unloadChunk(x: number, z: number): Promise<boolean> {
+    return post<boolean>('world.unloadChunk', { world: this.name, x, z });
+  }
+  unloadChunkSync(x: number, z: number): boolean {
+    return call<boolean>('world.unloadChunk', { world: this.name, x, z });
+  }
+  getBlockLightLevel(x: number, y: number, z: number): Promise<number> {
+    return post<number>('world.getBlockLightLevel', { world: this.name, x, y, z });
+  }
+  getBlockLightLevelSync(x: number, y: number, z: number): number {
+    return call<number>('world.getBlockLightLevel', { world: this.name, x, y, z });
+  }
+  getSkyLightLevel(x: number, y: number, z: number): Promise<number> {
+    return post<number>('world.getSkyLightLevel', { world: this.name, x, y, z });
+  }
+  getSkyLightLevelSync(x: number, y: number, z: number): number {
+    return call<number>('world.getSkyLightLevel', { world: this.name, x, y, z });
+  }
   getGameRule(rule: string): Promise<string | null> {
     return post<string | null>('world.getGameRule', { world: this.name, rule });
   }

package/src/assets-path.d.ts

@@ -1,3 +0,0 @@
-declare module '__yeow-assets' {
-    export function getPath(path: string): string;
-}

package/src/assets-path.ts

@@ -1,7 +0,0 @@
-/// <reference path="assets-path.d.ts" />
-
-import { getPath as _getPath } from '__yeow-assets';
-
-export function getAssetsPath(path: string): string {
-    return _getPath(path);
-}