yeow-api 0.2.107 → 0.2.109

package/package.json

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

package/src/block.ts

@@ -2,32 +2,82 @@ import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import { Location } from './location.js';
 import type { ItemStack } from './item.js';
+import { Material } from './material.js';
 
+/** 方块状态（Minecraft 原版键值对枚举，值统一为字符串）。 */
+export interface BlockState {
+  [key: string]: string;
+}
+
+/**
+ * Block —— 方块数据描述符 + 可选的世界位置（location）。
+ * 对应 Minecraft 原版的方块概念：类型 + 方块状态（键值对枚举，如
+ * `facing`、`waterlogged`、`level` 等，值统一为字符串）。
+ *
+ * **静态数据语义**：`type` / `state` / `location` 均为**获取时刻的快照**，
+ * 之后世界变化不会自动更新；需要最新状态请重新调用 `world.getBlock`。
+ *
+ * 两种来源：
+ * - `Block.of(type, state?)` —— 纯数据描述符，无 location（用于放置/比较）
+ * - `world.getBlock(x, y, z)` —— 世界中的方块，带 location（yaw/pitch 忽略，为 0）
+ */
 export class Block {
   constructor(
-    public readonly world: string,
-    public readonly x: number,
-    public readonly y: number,
-    public readonly z: number,
     public readonly type: string,
+    public readonly state?: BlockState,
+    /** 世界位置（由 world.getBlock 返回时存在；yaw/pitch 恒为 0）。 */
+    public readonly location?: Location,
   ) {}
 
-  get location(): Location {
-    return new Location(this.x, this.y, this.z, undefined, undefined, this.world);
+  static of(type: string, state?: BlockState): Block {
+    return new Block(type, state);
+  }
+
+  /** 派生一个带状态的新描述符（原对象不变）。 */
+  withState(state: BlockState): Block {
+    return new Block(this.type, { ...(this.state ?? {}), ...state }, this.location);
+  }
+
+  /** 是否与给定类型/状态相同（忽略空状态差异）。 */
+  matches(type: string, state?: BlockState): boolean {
+    if (this.type !== type) return false;
+    if (!state || Object.keys(state).length === 0) return true;
+    const s = this.state ?? {};
+    for (const [k, v] of Object.entries(state)) {
+      if (s[k] !== v) return false;
+    }
+    return true;
   }
-  isSolid(options?: TaskOptions): Promise<boolean> { return post<boolean>('block.isSolid', { world: this.world, x: this.x, y: this.y, z: this.z }, options); }
-  isSolidSync(options?: TaskOptions): boolean { return call<boolean>('block.isSolid', { world: this.world, x: this.x, y: this.y, z: this.z }, options); }
-  isLiquid(options?: TaskOptions): Promise<boolean> { return post<boolean>('block.isLiquid', { world: this.world, x: this.x, y: this.y, z: this.z }, options); }
-  isLiquidSync(options?: TaskOptions): boolean { return call<boolean>('block.isLiquid', { world: this.world, x: this.x, y: this.y, z: this.z }, options); }
-  isEmpty(options?: TaskOptions): Promise<boolean> { return post<boolean>('block.isEmpty', { world: this.world, x: this.x, y: this.y, z: this.z }, options); }
-  isEmptySync(options?: TaskOptions): boolean { return call<boolean>('block.isEmpty', { world: this.world, x: this.x, y: this.y, z: this.z }, options); }
+
+  // ── 材料级静态判断（基于类型，委托 Material；不依赖位置/状态）──
+
+  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); }
+
+  // ── 世界操作（需要 location）──
+
+  private get pos(): { world: string; x: number; y: number; z: number } | null {
+    const l = this.location;
+    if (!l || l.world === undefined) return null;
+    return { world: l.world, x: l.x, y: l.y, z: l.z };
+  }
+
+  /** 按该方块的位置自然破坏并掉落物品（需要 location）。 */
   breakNaturally(tool?: ItemStack, options?: TaskOptions): Promise<boolean> {
-    const p: Record<string, unknown> = { world: this.world, x: this.x, y: this.y, z: this.z };
+    const pos = this.pos;
+    if (!pos) return Promise.reject(new Error('block has no location (create with world.getBlock)'));
+    const p: Record<string, unknown> = { ...pos };
     if (tool) p.item = tool;
     return post<boolean>('block.breakNaturally', p, options);
   }
   breakNaturallySync(tool?: ItemStack, options?: TaskOptions): boolean {
-    const p: Record<string, unknown> = { world: this.world, x: this.x, y: this.y, z: this.z };
+    const pos = this.pos;
+    if (!pos) throw new Error('block has no location (create with world.getBlock)');
+    const p: Record<string, unknown> = { ...pos };
     if (tool) p.item = tool;
     return call<boolean>('block.breakNaturally', p, options);
   }

package/src/core.ts

@@ -9,6 +9,7 @@ export type { ChunkData } from './chunk.js';
 export { Entity, LivingEntity } from './entity.js';
 export type { BoundingBox } from './entity.js';
 export { Block } from './block.js';
+export type { BlockState } from './block.js';
 export { Inventory } from './inventory.js';
 export { registerCommand } from './command.js';
 export type { CommandOptions, CommandPayload, CommandSender, ManualCompleter } from './command.js';
@@ -31,7 +32,7 @@ export type {
 export { onInit, onLoad, onUnload } from './lifecycle.js';
 export {
     broadcast, broadcastSync, dispatchCommand, dispatchCommandSync,
-    setMotd, setMotdSync, setIcon, setIconSync,
+    setMotd, setMotdSync,
     getMotd, getMotdSync, getVersion, getVersionSync,
     getTps, getTpsSync, getMaxPlayers, getMaxPlayersSync,
 } from './server.js';
@@ -84,7 +85,7 @@ export { createBoard as createScoreboard, deleteBoard as deleteScoreboard,
     setTeamFriendlyFire, setTeamSeeInvisible, setTeamOption,
     teamAddEntry, teamRemoveEntry, teamGetEntries,
     setPlayerBoard } from './scoreboard.js';
-export { getMaterials, getBlocks, getItems } from './material.js';
+export { Material, getMaterials, getBlocks, getItems } from './material.js';
 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';

package/src/event.ts

@@ -151,10 +151,18 @@ export interface InventoryCloseEvent {
 }
 export interface ServerPingEvent {
   address: string;
+  /** 当前在线人数。handler 可返回 `{ numPlayers: <number> }` 覆盖该次 ping 响应显示的在线人数——**不建议修改**（伪装在线人数可能违反服务器列表政策）。 */
   numPlayers: number;
+  /** 最大玩家数。handler 可返回 `{ maxPlayers: <number> }` 覆盖该次 ping 响应显示的最大玩家数——**不建议修改**（仅影响显示，不改变实际进入限制）。 */
   maxPlayers: number;
+  /** MOTD 文本。handler 可返回 `{ motd: "<text>" }` 覆盖该次 ping 响应的 MOTD。 */
   motd: string;
   cancelled?: boolean;
+  /**
+   * handler 可返回 `{ icon: "<PNG base64>" }` 修改服务器列表图标
+   * （自动缩放至 64×64；无效图片忽略，保持原图标）。
+   */
+  icon?: string;
 }
 export interface PlayerTeleportEvent {
   player: Player;
@@ -344,7 +352,7 @@ function adaptEvent<K extends keyof EventMap>(type: K, data: RawEvent): EventMap
 
 // ── Event Subscription ─────────────────────────────────────────────
 
-type EventHandler<K extends keyof EventMap> = (e: EventMap[K]) => void;
+type EventHandler<K extends keyof EventMap> = (e: EventMap[K]) => unknown;
 type ManualHandler<K extends keyof EventMap> = (
   e: EventMap[K],
   complete: (result?: Record<string, unknown>) => void,
@@ -394,7 +402,10 @@ export function eventOn<K extends keyof EventMap>(
     }
 
     const result = (handler as EventHandler<typeof eventType>)(wrapped);
-    const mods = { cancelled: localMods.cancelled || false };
+    const mods: Record<string, unknown> = {
+      ...(result && typeof result === 'object' ? result : {}),
+    };
+    if (localMods.cancelled) mods.cancelled = true;
     $send('task', { type: 'event.complete', params: { callbackId: cbId, mods }, cb: '' });
   }, { persistent: true });
 

package/src/material.ts

@@ -1,4 +1,4 @@
-import { post } from './task.js';
+import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 
 export interface MaterialInfo {
@@ -34,3 +34,33 @@ export async function getItems(options?: TaskOptions): Promise<string[]> {
   Object.freeze(_items);
   return _items;
 }
+
+/**
+ * Material —— 材料级静态判断对象（不依赖坐标/状态）。
+ * 基于方块类型（material）判断其固有属性：固体/液体/空气。
+ */
+export const Material = {
+  /** 是否为固体方块（基于类型，状态不影响）。 */
+  isSolid(type: string, options?: TaskOptions): Promise<boolean> {
+    return post<boolean>('material.isSolid', { type }, options);
+  },
+  isSolidSync(type: string, options?: TaskOptions): boolean {
+    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);
+  },
+  isAirSync(type: string, options?: TaskOptions): boolean {
+    return call<boolean>('material.isAir', { type }, options);
+  },
+};

package/src/server.ts

@@ -7,8 +7,6 @@ export function dispatchCommand(cmd: string, options?: TaskOptions): Promise<boo
 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); }
 export function setMotdSync(motd: string, options?: TaskOptions): void { call('server.setMotd', { motd }, options); }
-export function setIcon(base64: string, options?: TaskOptions): Promise<void> { return post('server.setIcon', { icon: base64 }, options); }
-export function setIconSync(base64: string, options?: TaskOptions): void { call('server.setIcon', { icon: base64 }, options); }
 export function getMotd(options?: TaskOptions): Promise<string> { return post<string>('server.getMotd', {}, options); }
 export function getMotdSync(options?: TaskOptions): string { return call<string>('server.getMotd', {}, options); }
 export function getVersion(options?: TaskOptions): Promise<string> { return post<string>('server.getVersion', {}, options); }

package/src/world.ts

@@ -2,6 +2,7 @@ import { call, post } from './task.js';
 import type { TaskOptions } from './task.js';
 import { Location, LocationData } from './location.js';
 import { Block } from './block.js';
+import type { BlockState } from './block.js';
 import { Chunk, ChunkData } from './chunk.js';
 
 interface WorldData {
@@ -100,18 +101,32 @@ export class World {
     return call<string>('world.getBiome', { world: this.name, x, y, z }, options);
   }
   getBlock(x: number, y: number, z: number, options?: TaskOptions): Promise<Block | null> {
-    return post<{ x: number; y: number; z: number; type: string }>('world.getBlock', { world: this.name, x, y, z }, options)
-      .then((r) => (r ? new Block(this.name, r.x, r.y, r.z, r.type) : null));
+    return post<{ world: string; x: number; y: number; z: number; type: string; state: BlockState }>('world.getBlock', { world: this.name, x, y, z }, options)
+      .then((r) => (r ? new Block(r.type, r.state, new Location(r.x, r.y, r.z, 0, 0, r.world)) : null));
   }
   getBlockSync(x: number, y: number, z: number, options?: TaskOptions): Block | null {
-    const r = call<{ x: number; y: number; z: number; type: string }>('world.getBlock', { world: this.name, x, y, z }, options);
-    return r ? new Block(this.name, r.x, r.y, r.z, r.type) : null;
-  }
-  setBlock(x: number, y: number, z: number, blockType: string, options?: TaskOptions): Promise<void> {
-    return post('world.setBlock', { world: this.name, x, y, z, blockType }, options);
-  }
-  setBlockSync(x: number, y: number, z: number, blockType: string, options?: TaskOptions): void {
-    call('world.setBlock', { world: this.name, x, y, z, blockType }, options);
+    const r = call<{ world: string; x: number; y: number; z: number; type: string; state: BlockState }>('world.getBlock', { world: this.name, x, y, z }, options);
+    return r ? new Block(r.type, r.state, new Location(r.x, r.y, r.z, 0, 0, r.world)) : null;
+  }
+  setBlock(x: number, y: number, z: number, block: Block | string, options?: TaskOptions): Promise<void> {
+    const p: Record<string, unknown> = { world: this.name, x, y, z };
+    if (typeof block === 'string') {
+      p.blockType = block;
+    } else {
+      p.blockType = block.type;
+      if (block.state && Object.keys(block.state).length > 0) p.state = block.state;
+    }
+    return post('world.setBlock', p, options);
+  }
+  setBlockSync(x: number, y: number, z: number, block: Block | string, options?: TaskOptions): void {
+    const p: Record<string, unknown> = { world: this.name, x, y, z };
+    if (typeof block === 'string') {
+      p.blockType = block;
+    } else {
+      p.blockType = block.type;
+      if (block.state && Object.keys(block.state).length > 0) p.state = block.state;
+    }
+    call('world.setBlock', p, options);
   }
   getEntities(options?: TaskOptions): Promise<string[]> {
     return post<string[]>('world.getEntities', { world: this.name }, options);