Ponder JS API

Ponder 脚本环境的完整 JavaScript API 参考。Ponder 脚本仅在客户端执行，用于创建交互式教程场景。

Quick Start

// 注册标签
Ponder.tags(tags => {
  tags.createTag("rpg:forge", "minecraft:anvil", "锻造", "演示锻造流程")
})

// 注册场景
Ponder.registry(reg => {
  reg.create("minecraft:anvil")
    .scene("rpg:forge", "锻造流程", (scene, util) => {
      scene.configureBasePlate(0, 0, 5)
      scene.showBasePlate()

      const base = util.select().fromToXYZ(0, 0, 0, 2, 0, 2)
      scene.world().showSection(base, Direction.UP)
      scene.idle(20)

      const top = util.vector().topOfXYZ(1, 1, 1)
      scene.overlay().showText(40).text("放入矿石").pointAt(top)
      scene.idle(40)

      scene.effects().indicateSuccess(top)
      scene.particles().simple(20, "smoke", top).density(3).scale(0.8)
      scene.idle(20)
    })
})

TIP

所有接受 pos / position 参数的方法同时支持 BlockPos、Vec3、PonderVec3Wrapper、[x,y,z] 数组等类型。所有接受 direction / face 参数的方法同时支持 Direction 常量字符串（如 "up"、"north"）。

1. 全局对象与常量

1.1 Ponder

场景与标签注册入口。

方法	说明
`Ponder.registry(callback)`	注册场景，`callback` 接收 `PonderRegistryEventWrapper`
`Ponder.tags(callback)`	注册标签，`callback` 接收 `PonderTagEventWrapper`

1.2 PonderPalette

颜色调色板常量与工具方法。

常量（String 类型）：

常量	值
`WHITE`	`"white"`
`BLACK`	`"black"`
`RED`	`"red"`
`GREEN`	`"green"`
`BLUE`	`"blue"`
`SLOW`	`"slow"`
`MEDIUM`	`"medium"`
`FAST`	`"fast"`
`INPUT`	`"input"`
`OUTPUT`	`"output"`

方法：

方法	返回类型	说明
`fromString(name)`	`String?`	根据名称获取调色板颜色
`parseHex(hex)`	`Int`	解析十六进制颜色字符串

1.3 PonderGuiTextures

GUI 图标/纹理常量。

常量	说明
`LOGO`	Ponder Logo
`SPEECH_TOOLTIP_BACKGROUND`	语音气泡背景
`SPEECH_TOOLTIP_COLOR`	语音气泡颜色
`ICON_PONDER_LEFT` / `ICON_PONDER_CLOSE` / `ICON_PONDER_RIGHT`	导航图标
`ICON_PONDER_IDENTIFY` / `ICON_PONDER_REPLAY`	功能图标
`ICON_PONDER_USER_MODE` / `ICON_PONDER_SLOW_MODE`	模式图标
`ICON_CONFIG_UNLOCKED` / `ICON_CONFIG_LOCKED`	配置锁定图标
`ICON_CONFIG_DISCARD` / `ICON_CONFIG_SAVE` / `ICON_CONFIG_RESET`	配置操作图标
`ICON_CONFIG_BACK` / `ICON_CONFIG_PREV` / `ICON_CONFIG_NEXT`	配置导航图标
`ICON_DISABLE` / `ICON_CONFIG_OPEN` / `ICON_CONFIRM`	其他操作图标
`ICON_LMB` / `ICON_SCROLL` / `ICON_RMB`	鼠标按键图标

1.4 Direction / Facing

方向常量（Direction 和 Facing 指向同一对象 PonderDirectionJS）。

常量	值
`DOWN`	`"down"`
`UP`	`"up"`
`NORTH`	`"north"`
`SOUTH`	`"south"`
`WEST`	`"west"`
`EAST`	`"east"`

1.5 PonderPointing

指向常量。

常量	值
`DOWN`	`"down"`
`LEFT`	`"left"`
`RIGHT`	`"right"`
`UP`	`"up"`

1.6 Block

方块工具对象。

方法	返回类型	说明
`Block.id(value)`	`PonderBlockStateWrapper`	解析方块 ID 并返回默认状态

const stone = Block.id("minecraft:stone")
const lit = Block.id("minecraft:furnace").with("lit", "true")

1.7 Vec3

向量构造器（通过 new 创建）。

const v = new Vec3(1.0, 2.5, 3.0)

1.8 ParrotElement / PonderInput

TIP

ParrotElement 和 PonderInput（别名 PonderInputWindowElement）作为类型暴露到全局作用域，但通常不需要直接构造，而是通过 scene.special().createBirb() 和 scene.showControls() 获取。

2. Wrapper API 参考

WARNING

以下方法签名中，标注为 Any 类型的参数均支持多种类型输入（BlockPos / Vec3 / PonderVec3Wrapper / ResourceLocation / String / 数组等），引擎会自动转换。标注为"可链式调用"的方法返回 this，支持 .method1().method2() 写法。

PonderBlockStateWrapper

调整方块状态属性。

方法	参数	返回类型	说明
`with(property, value)`	`property: String`, `value: String`	`PonderBlockStateWrapper`	设置方块状态属性，可链式调用
`unwrap()`	-	`BlockState`	获取底层 Minecraft BlockState

const state = Block.id("minecraft:furnace").with("lit", "true").with("facing", "north")

PonderRegistryEventWrapper

场景注册事件入口（Ponder.registry(reg => { ... }) 的 reg 参数）。

方法	参数	返回类型	说明
`create(...components)`	`vararg components: Any`	`PonderSceneRegistrationBuilderWrapper`	为指定组件创建场景注册器
`forComponents(...components)`	`vararg components: Any`	`PonderMultiSceneBuilderWrapper`	为多个组件批量注册场景
`withKeyFunction()`	-	`PonderSceneRegistrationHelper`	获取底层注册器（高级用法）
`printParticleNames()`	-	`void`	在日志中输出所有可用的简单粒子类型名称

PonderSceneRegistrationBuilderWrapper

基于组件注册场景。

方法	参数	返回类型	说明
`tag(...tags)`	`vararg tags: Any`	`this`	为后续场景添加默认标签，可链式调用
`scene(sceneId, title, callback, ...tags)`	`sceneId: String`, `title: String`, `callback: Function`, `vararg tags: Any`	`PonderStoryBoardEntryWrapper`	注册场景，callback 接收 `(scene, util)`
`scene(sceneId, title, schematic, callback, ...tags)`	`sceneId: String`, `title: String`, `schematic: Any`, `callback: Function`, `vararg tags: Any`	`PonderStoryBoardEntryWrapper`	指定结构文件注册场景
`sceneWithSchematic(sceneId, title, schematic, callback, ...tags)`	同上	`PonderStoryBoardEntryWrapper`	同上（显式命名版本）

reg.create("minecraft:anvil")
  .tag("rpg:guide")
  .scene("rpg:forge", "锻造流程", (scene, util) => {
    // scene: PonderSceneBuilderWrapper
    // util: PonderSceneBuildingUtilWrapper
  })

PonderMultiSceneBuilderWrapper

批量注册多个场景。

方法	参数	返回类型	说明
`addStoryBoard(schematic, callback)`	`schematic: Any`, `callback: Function`	`this`	添加场景
`addStoryBoardWithTags(schematic, callback, ...tags)`	`schematic: Any`, `callback: Function`, `vararg tags: Any`	`this`	添加场景并关联标签
`addStoryBoardWithExtras(schematic, callback, extras)`	`schematic: Any`, `callback: Function`, `extras: Function`	`this`	添加场景并自定义 StoryBoardEntry
`addStoryBoardByPath(schematicPath, callback)`	`schematicPath: String`, `callback: Function`	`this`	按路径添加场景
`addStoryBoardByPathWithTags(schematicPath, callback, ...tags)`	`schematicPath: String`, `callback: Function`, `vararg tags: Any`	`this`	按路径添加场景并关联标签
`addStoryBoardByPathWithExtras(schematicPath, callback, extras)`	`schematicPath: String`, `callback: Function`, `extras: Function`	`this`	按路径添加场景并自定义 StoryBoardEntry
`unwrap()`	-	`MultiSceneBuilder`	获取底层构建器

PonderStoryBoardEntryWrapper

场景条目排序与标签管理。

方法	参数	返回类型	说明
`orderBefore(otherSceneId)`	`otherSceneId: String`	`this`	排序：排在另一场景之前
`orderBeforeWithNamespace(namespace, otherSceneId)`	`namespace: String`, `otherSceneId: String`	`this`	排序：指定命名空间
`orderAfter(otherSceneId)`	`otherSceneId: String`	`this`	排序：排在另一场景之后
`orderAfterWithNamespace(namespace, otherSceneId)`	`namespace: String`, `otherSceneId: String`	`this`	排序：指定命名空间
`highlightTag(tag)`	`tag: Any`	`this`	高亮一个标签
`highlightTags(...tags)`	`vararg tags: Any`	`this`	高亮多个标签
`highlightAllTags()`	-	`this`	高亮所有标签
`getComponent()`	-	`ResourceLocation`	获取关联的组件 ID
`unwrap()`	-	`StoryBoardEntry`	获取底层条目

PonderSceneBuilderWrapper

场景构建主入口（scene 参数）。

TIP

scene 对象的子模块同时支持方法调用和属性访问两种方式：

方法：scene.world() / scene.overlay() / scene.effects() / scene.special() / scene.debug() / scene.getParticles()
属性：scene.world / scene.overlay / scene.effects / scene.special / scene.debug / scene.particles

子模块访问：

方法/属性	返回类型	说明
`util()` / `util`	`PonderSceneBuildingUtilWrapper`	构建工具
`overlay()` / `overlay`	`PonderOverlayInstructionsWrapper`	覆盖层指令（文本/线条/轮廓）
`world()` / `world`	`PonderWorldInstructionsWrapper`	世界操作指令（方块/实体）
`effects()` / `effects`	`PonderEffectInstructionsWrapper`	特效指令（粒子/光效）
`special()` / `special`	`PonderSpecialInstructionsWrapper`	特殊元素指令（鹦鹉/矿车）
`debug()` / `debug`	`PonderDebugInstructionsWrapper`	调试指令
`getParticles()` / `particles`	`PonderParticleInstructionsWrapper`	粒子指令（高级粒子系统）

场景配置：

方法	参数	返回类型	说明
`title(sceneId, title)`	`sceneId: String`, `title: String`	`void`	设置场景标题
`configureBasePlate(xOffset, zOffset, basePlateSize)`	`xOffset: Int`, `zOffset: Int`, `basePlateSize: Int`	`void`	配置底板
`scaleSceneView(factor)`	`factor: Float`	`void`	缩放场景视图
`removeShadow()`	-	`void`	移除阴影
`setSceneOffsetY(yOffset)`	`yOffset: Float`	`void`	设置场景 Y 偏移
`showBasePlate()`	-	`void`	显示底板

流程控制：

方法	参数	返回类型	说明
`idle(ticks)`	`ticks: Int`	`void`	等待指定 tick
`idleSeconds(seconds)`	`seconds: Int`	`void`	等待指定秒数
`markAsFinished()`	-	`void`	标记场景结束
`setNextUpEnabled(isEnabled)`	`isEnabled: Boolean`	`void`	启用/禁用"下一步"按钮
`addKeyframe()`	-	`void`	添加关键帧
`addLazyKeyframe()`	-	`void`	添加懒加载关键帧

相机与结构：

方法	参数	返回类型	说明
`rotateCameraY(degrees)`	`degrees: Float`	`void`	旋转相机 Y 轴
`showStructure()`	-	`void`	显示整个结构
`showStructureHeight(height)`	`height: Int`	`void`	显示结构到指定高度
`encapsulateBounds(size)`	`size: Any`	`void`	扩展场景边界

快捷方法：

方法	参数	返回类型	说明
`text(duration, text, position?)`	`duration: Int`, `text: String`, `position?: Any`	`PonderTextElementBuilderWrapper`	快捷显示文本
`textSimple(duration, text)`	`duration: Int`, `text: String`	`PonderTextElementBuilderWrapper`	快捷显示文本（无定位）
`showControls(duration, position, direction)`	`duration: Int`, `position: Any`, `direction: Any`	`PonderInputElementBuilderWrapper`	快捷显示输入控件
`playSound(sound)`	`sound: Any`	`void`	播放音效（默认音量 1.0、音调 1.0）
`playSound(sound, volume)`	`sound: Any`, `volume: Number`	`void`	播放音效（默认音调 1.0）
`playSound(sound, volume, pitch)`	`sound: Any`, `volume: Number`, `pitch: Number`	`void`	播放音效

底层访问：

方法	参数	返回类型	说明
`getScene()`	-	`PonderScene`	获取底层 PonderScene
`addInstruction(instruction)`	`instruction: PonderInstruction`	`void`	添加原始指令
`addInstructionCallback(callback)`	`callback: Function`	`void`	添加回调指令，callback 接收 `PonderScene`
`unwrap()`	-	`SceneBuilder`	获取底层 SceneBuilder

PonderSceneBuildingUtilWrapper

构建工具（util 参数）。

TIP

util 对象的子模块同时支持方法调用和属性访问两种方式：

方法：util.select() / util.vector() / util.grid()
属性：util.select / util.vector / util.grid

方法/属性	返回类型	说明
`select()` / `select`	`PonderSelectionUtilWrapper`	选择器工具
`vector()` / `vector`	`PonderVectorUtilWrapper`	向量工具
`grid()` / `grid`	`PonderPositionUtilWrapper`	位置工具
`unwrap()`	`SceneBuildingUtil`	获取底层工具

PonderSelectionUtilWrapper

选择器工具（创建 Selection 对象）。

方法	参数	返回类型	说明
`everywhere()`	-	`Selection`	选中整个场景
`position(pos)`	`pos: Any`	`Selection`	选中单个方块位置
`positionXYZ(x, y, z)`	`x: Int`, `y: Int`, `z: Int`	`Selection`	选中单个方块位置
`fromTo(pos1, pos2)`	`pos1: Any`, `pos2: Any`	`Selection`	选中两点间的区域
`fromToXYZ(x, y, z, x2, y2, z2)`	`x~z: Int`, `x2~z2: Int`	`Selection`	选中两点间的区域
`column(x, z)`	`x: Int`, `z: Int`	`Selection`	选中指定列
`layer(y)`	`y: Int`	`Selection`	选中指定层
`layersFrom(y)`	`y: Int`	`Selection`	选中从 y 层开始往上的所有层
`layers(y, height)`	`y: Int`, `height: Int`	`Selection`	选中从 y 层开始的 height 层
`cuboid(origin, size)`	`origin: Any`, `size: Any`	`Selection`	选中长方体区域
`unwrap()`	-	`SelectionUtil`	获取底层工具

const base = util.select().fromToXYZ(0, 0, 0, 4, 0, 4)
const single = util.select().positionXYZ(1, 1, 1)
const all = util.select().everywhere()

PonderVectorUtilWrapper

向量工具（创建 PonderVec3Wrapper 对象）。

方法	参数	返回类型	说明
`centerOf(pos)`	`pos: Any`	`PonderVec3Wrapper`	方块中心
`centerOfXYZ(x, y, z)`	`x: Int`, `y: Int`, `z: Int`	`PonderVec3Wrapper`	方块中心
`topOf(pos)`	`pos: Any`	`PonderVec3Wrapper`	方块顶部中心
`topOfXYZ(x, y, z)`	`x: Int`, `y: Int`, `z: Int`	`PonderVec3Wrapper`	方块顶部中心
`blockSurface(pos, face)`	`pos: Any`, `face: Any`	`PonderVec3Wrapper`	方块指定面的中心
`blockSurfaceWithMargin(pos, face, margin)`	`pos: Any`, `face: Any`, `margin: Float`	`PonderVec3Wrapper`	方块指定面的中心（带边距）
`of(x, y, z)`	`x: Double`, `y: Double`, `z: Double`	`PonderVec3Wrapper`	创建任意向量
`unwrap()`	-	`VectorUtil`	获取底层工具

PonderPositionUtilWrapper

位置工具（创建 BlockPos 对象）。

方法	参数	返回类型	说明
`at(x, y, z)`	`x: Int`, `y: Int`, `z: Int`	`BlockPos`	创建方块位置
`zero()`	-	`BlockPos`	返回原点 (0,0,0)
`unwrap()`	-	`PositionUtil`	获取底层工具

PonderVec3Wrapper

向量对象封装。

方法	参数	返回类型	说明
`x()`	-	`Double`	获取 X 分量
`y()`	-	`Double`	获取 Y 分量
`z()`	-	`Double`	获取 Z 分量
`add(other)`	`other: Any`	`PonderVec3Wrapper`	向量加法
`add(x, y, z)`	`x: Double`, `y: Double`, `z: Double`	`PonderVec3Wrapper`	向量加法
`addXYZ(x, y, z)`	`x: Double`, `y: Double`, `z: Double`	`PonderVec3Wrapper`	向量加法（别名）
`subtract(other)`	`other: Any`	`PonderVec3Wrapper`	向量减法
`subtract(x, y, z)`	`x: Double`, `y: Double`, `z: Double`	`PonderVec3Wrapper`	向量减法
`scale(factor)`	`factor: Double`	`PonderVec3Wrapper`	向量缩放
`unwrap()`	-	`Vec3`	获取底层 Minecraft Vec3

const v = new Vec3(1, 2, 3)
const moved = v.add(0, 1, 0).scale(2.0)

PonderOverlayInstructionsWrapper

覆盖层指令（文本/线条/轮廓）。通过 scene.overlay() 或 scene.overlay 获取。

方法	参数	返回类型	说明
`showText(duration)`	`duration: Int`	`PonderTextElementBuilderWrapper`	显示文本，返回可链式配置的构建器
`showOutlineWithText(selection, duration)`	`selection: Any`, `duration: Int`	`PonderTextElementBuilderWrapper`	显示带轮廓的文本
`showControls(sceneSpace, direction, duration)`	`sceneSpace: Any`, `direction: Any`, `duration: Int`	`PonderInputElementBuilderWrapper`	显示输入控件
`chaseBoundingBoxOutline(color, slot, boundingBox, duration)`	`color: Any`, `slot: Any?`, `boundingBox: Any`, `duration: Int`	`void`	追踪显示包围盒轮廓
`showCenteredScrollInput(pos, side, duration)`	`pos: Any`, `side: Any`, `duration: Int`	`void`	显示居中滚动输入
`showScrollInput(location, side, duration)`	`location: Any`, `side: Any`, `duration: Int`	`void`	显示滚动输入
`showRepeaterScrollInput(pos, duration)`	`pos: Any`, `duration: Int`	`void`	显示中继器滚动输入
`showFilterSlotInput(location, duration)`	`location: Any`, `duration: Int`	`void`	显示过滤槽输入
`showFilterSlotInputWithSide(location, side, duration)`	`location: Any`, `side: Any`, `duration: Int`	`void`	显示带方向的过滤槽输入
`showLine(color, start, end, duration)`	`color: Any`, `start: Any`, `end: Any`, `duration: Int`	`void`	显示线条
`showBigLine(color, start, end, duration)`	`color: Any`, `start: Any`, `end: Any`, `duration: Int`	`void`	显示粗线条
`showOutline(color, slot, selection, duration)`	`color: Any`, `slot: Any?`, `selection: Any`, `duration: Int`	`void`	显示选区轮廓
`unwrap()`	-	`OverlayInstructions`	获取底层

TIP

duration 参数的单位均为 tick（1 秒 = 20 tick）。color 参数接受 PonderPalette 常量字符串。

PonderTextElementBuilderWrapper

文本元素构建器（可链式调用）。

方法	参数	返回类型	说明
`colored(color)`	`color: Any`	`this`	设置文本颜色（PonderPalette 名称或颜色值）
`pointAt(pos)`	`pos: Any`	`this`	指向某个位置
`independent(y?)`	`y: Int = 0`	`this`	独立定位（不跟随场景元素）
`text(text)`	`text: String`	`this`	设置文本内容
`textWithParams(text, ...params)`	`text: String`, `vararg params: Any`	`this`	设置带参数的文本内容
`placeNearTarget()`	-	`this`	将文本放置在目标附近
`attachKeyFrame()`	-	`this`	附加关键帧
`unwrap()`	-	`TextElementBuilder`	获取底层

scene.overlay().showText(60)
  .text("这是一条提示")
  .pointAt(util.vector().topOfXYZ(1, 1, 1))
  .colored(PonderPalette.GREEN)
  .placeNearTarget()
  .attachKeyFrame()

PonderInputElementBuilderWrapper

输入提示构建器（可链式调用）。

方法	参数	返回类型	说明
`withItem(item)`	`item: Any`	`this`	显示物品图标
`leftClick()`	-	`this`	显示左键图标
`rightClick()`	-	`this`	显示右键图标
`scroll()`	-	`this`	显示滚轮图标
`showing(icon)`	`icon: Any`	`this`	显示指定图标（PonderGuiTextures 名称或对象）
`whileSneaking()`	-	`this`	标记为"潜行时"
`whileCTRL()`	-	`this`	标记为"按住 CTRL 时"
`unwrap()`	-	`InputElementBuilder`	获取底层

scene.showControls(40, util.vector().topOfXYZ(1, 1, 1), Direction.UP)
  .rightClick()
  .withItem("minecraft:diamond")

PonderWorldInstructionsWrapper

世界/方块/实体操作指令。通过 scene.world() 或 scene.world 获取。

区段显示/隐藏：

方法	参数	返回类型	说明
`showSection(selection, fadeInDirection)`	`selection: Any`, `fadeInDirection: Any`	`void`	显示选区
`showSectionAndMerge(selection, fadeInDirection, link)`	`selection: Any`, `fadeInDirection: Any`, `link: Any`	`void`	显示选区并合并到已有链接
`glueBlockOnto(position, fadeInDirection, link)`	`position: Any`, `fadeInDirection: Any`, `link: Any`	`void`	将方块粘贴到已有链接
`showIndependentSection(selection, fadeInDirection)`	`selection: Any`, `fadeInDirection: Any`	`PonderElementLinkWrapper`	显示独立区段（可移动/旋转）
`showIndependentSectionImmediately(selection)`	`selection: Any`	`PonderElementLinkWrapper`	立即显示独立区段
`hideSection(selection, fadeOutDirection)`	`selection: Any`, `fadeOutDirection: Any`	`void`	隐藏选区
`hideIndependentSection(link, fadeOutDirection)`	`link: Any`, `fadeOutDirection: Any`	`void`	隐藏独立区段
`restoreBlocks(selection)`	`selection: Any`	`void`	恢复选区内的方块
`makeSectionIndependent(selection)`	`selection: Any`	`PonderElementLinkWrapper`	将选区转为独立区段

区段变换：

方法	参数	返回类型	说明
`rotateSection(link, xRotation, yRotation, zRotation, duration)`	`link: Any`, `x/y/zRotation: Double`, `duration: Int`	`void`	旋转区段
`configureCenterOfRotation(link, anchor)`	`link: Any`, `anchor: Any`	`void`	配置旋转中心
`configureStabilization(link, anchor)`	`link: Any`, `anchor: Any`	`void`	配置稳定化锚点
`moveSection(link, offset, duration)`	`link: Any`, `offset: Any`, `duration: Int`	`void`	移动区段

方块操作：

方法	参数	返回类型	说明
`setBlock(pos, state)`	`pos: Any`, `state: Any`	`void`	设置单个方块（带粒子）
`setBlock(pos, state, spawnParticles)`	`pos: Any`, `state: Any`, `spawnParticles: Boolean`	`void`	设置单个方块
`setBlocks(selection, state)`	`selection: Any`, `state: Any`	`void`	批量设置方块（带粒子）
`setBlocks(selection, state, spawnParticles)`	`selection: Any`, `state: Any`, `spawnParticles: Boolean`	`void`	批量设置方块
`replaceBlocks(selection, state)`	`selection: Any`, `state: Any`	`void`	替换方块（带粒子）
`replaceBlocks(selection, state, spawnParticles)`	`selection: Any`, `state: Any`, `spawnParticles: Boolean`	`void`	替换方块
`destroyBlock(pos)`	`pos: Any`	`void`	销毁方块
`modifyBlock(pos, callback)`	`pos: Any`, `callback: Function`	`void`	修改方块状态，callback 接收 `PonderBlockStateWrapper`
`modifyBlock(pos, callback, spawnParticles)`	`pos: Any`, `callback: Function`, `spawnParticles: Boolean`	`void`	修改方块状态
`modifyBlocks(selection, callback)`	`selection: Any`, `callback: Function`	`void`	批量修改方块状态
`modifyBlocks(selection, callback, spawnParticles)`	`selection: Any`, `callback: Function`, `spawnParticles: Boolean`	`void`	批量修改方块状态
`cycleBlockProperty(pos, property)`	`pos: Any`, `property: Any`	`void`	循环切换方块属性值
`toggleRedstonePower(selection)`	`selection: Any`	`void`	切换红石信号
`incrementBlockBreakingProgress(pos)`	`pos: Any`	`void`	增加方块破坏进度

实体操作：

方法	参数	返回类型	说明
`createEntity(factory)`	`factory: Function`	`PonderElementLinkWrapper`	通过工厂函数创建实体，factory 接收 `Level`
`createEntity(entityType, position)`	`entityType: Any`, `position: Any`	`PonderElementLinkWrapper`	按类型创建实体
`createEntity(entityType, position, callback?)`	`entityType: Any`, `position: Any`, `callback?: Function`	`PonderElementLinkWrapper`	按类型创建实体并配置
`createEntityWithType(entityType, position, callback?)`	`entityType: Any`, `position: Any`, `callback?: Function`	`PonderElementLinkWrapper`	同上（显式命名版本）
`createItemEntity(location, motion, stack)`	`location: Any`, `motion: Any`, `stack: Any`	`PonderElementLinkWrapper`	创建掉落物实体
`modifyEntity(link, callback)`	`link: Any`, `callback: Function`	`void`	修改实体
`modifyEntities(entityType, callback)`	`entityType: Any`, `callback: Function`	`void`	修改所有指定类型的实体
`modifyEntitiesInside(entityType, area, callback)`	`entityType: Any`, `area: Any`, `callback: Function`	`void`	修改区域内指定类型的实体
`removeEntity(link)`	`link: Any`	`void`	移除实体

方块实体操作：

方法	参数	返回类型	说明
`modifyBlockEntityNBT(selection, callback)`	`selection: Any`, `callback: Function`	`void`	修改方块实体 NBT（callback 接收 Map 形式的 CompoundTag）
`modifyBlockEntityNBT(selection, reDrawBlocks, callback)`	`selection: Any`, `reDrawBlocks: Boolean`, `callback: Function`	`void`	修改方块实体 NBT（控制是否重绘）
`modifyBlockEntityNBT(selection, beType, callback)`	`selection: Any`, `beType: Any`, `callback: Function`	`void`	修改指定类型的方块实体 NBT
`modifyBlockEntityNBTWithRedraw(selection, beType, callback, reDrawBlocks)`	`selection: Any`, `beType: Any`, `callback: Function`, `reDrawBlocks: Boolean`	`void`	修改方块实体 NBT（完整参数版本）
`modifyBlockEntity(position, beType, callback)`	`position: Any`, `beType: Any`, `callback: Function`	`void`	直接修改方块实体对象
`unwrap()`	-	`WorldInstructions`	获取底层

TIP

modifyBlockEntityNBT 的 callback 接收的是 CompoundTag 的 Map 代理对象，可以像普通 Map 一样读写 NBT 数据：

scene.world().modifyBlockEntityNBT(sel, (nbt) => {
  nbt["Items"] = [{ id: "minecraft:diamond", Count: 1, Slot: 0 }]
})

PonderEffectInstructionsWrapper

特效指令。通过 scene.effects() 或 scene.effects 获取。

方法	参数	返回类型	说明
`indicateRedstone(pos)`	`pos: Any`	`void`	显示红石激活效果
`indicateSuccess(pos)`	`pos: Any`	`void`	显示成功效果
`createRedstoneParticles(pos, color, amount)`	`pos: Any`, `color: Any`, `amount: Int`	`void`	创建红石粒子
`emitParticles(location, emitter, amountPerCycle, cycles)`	`location: Any`, `emitter: ParticleEmitter`, `amountPerCycle: Float`, `cycles: Int`	`void`	发射粒子
`simpleParticleEmitter(data, motion)`	`data: Any`, `motion: Any`	`PonderParticleEmitterWrapper?`	创建简单粒子发射器
`particleEmitterWithinBlockSpace(data, motion)`	`data: Any`, `motion: Any`	`PonderParticleEmitterWrapper?`	创建方块空间内粒子发射器
`playPhotonFx(path, location)`	`path: String`, `location: Any`	`void`	播放 Photon 粒子特效
`playSnowstormFx(path, location)`	`path: String`, `location: Any`	`void`	播放 Snowstorm 粒子特效
`unwrap()`	-	`EffectInstructions`	获取底层

PonderParticleInstructionsWrapper

高级粒子系统。通过 scene.getParticles() 或 scene.particles 获取。

TIP

所有粒子创建方法返回 PonderParticleDataBuilderWrapper，支持链式调用来配置粒子属性。

方法	参数	返回类型	说明
`simple(ticks, type, pos)`	`ticks: Int`, `type: Any`, `pos: Any`	`PonderParticleDataBuilderWrapper`	创建简单粒子（type 为粒子 ID 字符串如 `"smoke"`）
`dust(ticks, color, pos)`	`ticks: Int`, `color: Any`, `pos: Any`	`PonderParticleDataBuilderWrapper`	创建灰尘粒子（单色）
`dust(ticks, fromColor, toColor, pos)`	`ticks: Int`, `fromColor: Any`, `toColor: Any`, `pos: Any`	`PonderParticleDataBuilderWrapper`	创建灰尘粒子（颜色过渡）
`item(ticks, item, pos)`	`ticks: Int`, `item: Any`, `pos: Any`	`PonderParticleDataBuilderWrapper`	创建物品粒子
`block(ticks, state, pos)`	`ticks: Int`, `state: Any`, `pos: Any`	`PonderParticleDataBuilderWrapper`	创建方块粒子

scene.particles().simple(40, "minecraft:flame", pos)
  .density(5)
  .scale(1.5)
  .gravity(-0.01)
  .area(new Vec3(1, 0.5, 1))

PonderParticleDataBuilderWrapper

粒子数据构建器（可链式调用）。

方法	参数	返回类型	说明
`density(value)`	`value: Number`	`this`	每 tick 生成的粒子数量
`gravity(value)`	`value: Number`	`this`	粒子重力
`physics(value)`	`value: Boolean`	`this`	是否启用物理
`collision(value)`	`value: Boolean`	`this`	是否启用碰撞
`color(value)`	`value: Any`	`this`	粒子颜色
`roll(value)`	`value: Number`	`this`	粒子旋转
`friction(value)`	`value: Number`	`this`	粒子摩擦力
`scale(value)`	`value: Number`	`this`	粒子大小
`lifetime(value)`	`value: Number`	`this`	粒子生命周期（tick）
`motion(vec)`	`vec: Any`	`this`	设置固定运动方向
`speed(vec)`	`vec: Any`	`this`	设置随机速度（高斯分布）
`area(vec)`	`vec: Any`	`this`	设置生成区域（均匀分布）
`delta(vec)`	`vec: Any`	`this`	设置位置偏移（高斯分布）
`withinBlockSpace()`	-	`this`	限制粒子在方块空间内随机位置
`transform(callback)`	`callback: Function`	`this`	自定义变换，callback 接收 `(partialTick, position, motion)` 返回 `[position, motion]`
`transformPosition(callback)`	`callback: Function`	`this`	自定义位置变换，callback 接收 `(partialTick, position)` 返回新 position
`transformMotion(callback)`	`callback: Function`	`this`	自定义运动变换，callback 接收 `(partialTick, motion)` 返回新 motion

PonderSpecialInstructionsWrapper

特殊元素指令（鹦鹉/矿车/兴趣点）。通过 scene.special() 或 scene.special 获取。

方法	参数	返回类型	说明
`createBirb(location, pose?)`	`location: Any`, `pose?: Any`	`PonderElementLinkWrapper<ParrotElement>`	创建鹦鹉
`changeBirbPose(birb, pose?)`	`birb: Any`, `pose?: Any`	`void`	改变鹦鹉姿势
`movePointOfInterest(location)`	`location: Any`	`void`	移动兴趣点（鹦鹉会朝向此点）
`rotateParrot(link, xRotation, yRotation, zRotation, duration)`	`link: Any`, `x/y/zRotation: Double`, `duration: Int`	`void`	旋转鹦鹉
`moveParrot(link, offset, duration)`	`link: Any`, `offset: Any`, `duration: Int`	`void`	移动鹦鹉
`createCart(location, angle, type)`	`location: Any`, `angle: Float`, `type: Any`	`PonderElementLinkWrapper<MinecartElement>`	创建矿车
`rotateCart(link, yRotation, duration)`	`link: Any`, `yRotation: Float`, `duration: Int`	`void`	旋转矿车
`moveCart(link, offset, duration)`	`link: Any`, `offset: Any`, `duration: Int`	`void`	移动矿车
`hideElement(link, direction)`	`link: Any`, `direction: Any`	`void`	隐藏动画元素
`unwrap()`	-	`SpecialInstructions`	获取底层

PonderDebugInstructionsWrapper

调试指令。通过 scene.debug() 或 scene.debug 获取。

方法	参数	返回类型	说明
`debugSchematic()`	-	`void`	调试输出结构信息
`addInstructionInstance(instruction)`	`instruction: Any`	`void`	添加原始指令
`enqueueCallback(callback)`	`callback: Function`	`void`	添加调试回调
`unwrap()`	-	`DebugInstructions`	获取底层

PonderElementLinkWrapper

元素引用句柄（用于后续操作独立区段/实体等）。

方法	参数	返回类型	说明
`getId()`	-	`UUID`	获取元素链接 ID
`unwrap()`	-	`ElementLink<T>`	获取底层链接

const link = scene.world().showIndependentSection(sel, Direction.UP)
scene.world().moveSection(link, new Vec3(2, 0, 0), 20)
scene.idle(20)
scene.world().hideIndependentSection(link, Direction.DOWN)

PonderParticleEmitterWrapper / PonderParrotElementWrapper / PonderInputWindowElementWrapper

这些是简单的包装类型，主要用于在 Wrapper API 之间传递引用。

Wrapper	方法	说明
`PonderParticleEmitterWrapper`	`unwrap()`	获取底层 `ParticleEmitter`
`PonderParrotElementWrapper`	-	鹦鹉元素引用（通常不直接使用）
`PonderInputWindowElementWrapper`	-	输入窗口元素引用（通常不直接使用）

3. 标签 API

PonderTagEventWrapper

标签注册事件入口（Ponder.tags(tags => { ... }) 的 tags 参数）。

方法	参数	返回类型	说明
`registerTag(id)`	`id: Any`	`PonderTagBuilderWrapper`	注册标签并返回构建器
`createTag(id, callback)`	`id: Any`, `callback: Function`	`void`	使用回调创建标签（callback 接收 PonderTagBuilderWrapper）
`createTag(id, icon, title, description)`	`id: Any`, `icon: Any`, `title: String`, `description: String`	`void`	快捷创建标签
`createTag(id, icon, title, description, items?)`	`id: Any`, `icon: Any`, `title: String`, `description: String`, `items?: Any`	`void`	快捷创建标签并关联物品
`createTagSimple(id, icon, title, description, items?)`	同上	`void`	同上（显式命名版本）
`add(tag, components)`	`tag: Any`, `components: Any`	`void`	将组件添加到标签
`remove(tag, components)`	`tag: Any`, `components: Any`	`void`	从标签移除组件
`addToTag(...tags)`	`vararg tags: Any`	`PonderMultiTagBuilderWrapper.TagWrapper`	批量操作入口（先指定标签，再 `.add(component)`）
`addToComponent(...components)`	`vararg components: Any`	`PonderMultiTagBuilderWrapper.ComponentWrapper`	批量操作入口（先指定组件，再 `.add(tag)`）
`unwrap()`	-	`DefaultPonderTagRegistrationHelper`	获取底层

Ponder.tags(tags => {
  // 方式一：快捷创建
  tags.createTag("rpg:guide", "minecraft:book", "指南", "RPG 指南")

  // 方式二：使用构建器
  tags.createTag("rpg:advanced", builder => {
    builder.title("高级指南").description("进阶内容").icon("minecraft:diamond").addToIndex()
  })

  // 方式三：批量关联
  tags.addToTag("rpg:guide").add("minecraft:stone").add("minecraft:dirt")
  tags.addToComponent("minecraft:anvil").add("rpg:guide").add("rpg:advanced")
})

PonderTagBuilderWrapper

标签构建器（可链式调用）。

方法	参数	返回类型	说明
`title(title)`	`title: String`	`this`	设置标题
`description(description)`	`description: String`	`this`	设置描述
`addToIndex()`	-	`this`	添加到索引页
`noIndex()`	-	`this`	不添加到索引页
`addIconToItems()`	-	`this`	将图标物品也添加为组件
`icon(icon)`	`icon: Any`	`this`	设置图标（ResourceLocation / 物品 / 字符串）
`idAsIcon()`	-	`this`	使用标签 ID 作为图标
`item(item)`	`item: Any`	`this`	关联物品
`itemWithOptions(item, useAsIcon, useAsMainItem)`	`item: Any`, `useAsIcon: Boolean`, `useAsMainItem: Boolean`	`this`	关联物品（带选项）
`register()`	-	`void`	注册标签（使用 `createTag(id, callback)` 时自动调用）
`unwrap()`	-	`TagBuilder`	获取底层

PonderMultiTagBuilderWrapper

批量标签/组件关联。

TagWrapper（通过 tags.addToTag(...) 获取）：

方法	参数	返回类型	说明
`add(component)`	`component: Any`	`this`	将组件添加到已指定的标签

ComponentWrapper（通过 tags.addToComponent(...) 获取）：

方法	参数	返回类型	说明
`add(tag)`	`tag: Any`	`this`	将标签关联到已指定的组件

Ponder JS API ​

Quick Start ​

1. 全局对象与常量 ​

1.1 Ponder ​

1.2 PonderPalette ​

1.3 PonderGuiTextures ​

1.4 Direction / Facing ​

1.5 PonderPointing ​

1.6 Block ​

1.7 Vec3 ​

1.8 ParrotElement / PonderInput ​

2. Wrapper API 参考 ​

PonderBlockStateWrapper ​

PonderRegistryEventWrapper ​

PonderSceneRegistrationBuilderWrapper ​

PonderMultiSceneBuilderWrapper ​

PonderStoryBoardEntryWrapper ​

PonderSceneBuilderWrapper ​

PonderSceneBuildingUtilWrapper ​

PonderSelectionUtilWrapper ​

PonderVectorUtilWrapper ​

PonderPositionUtilWrapper ​

PonderVec3Wrapper ​

PonderOverlayInstructionsWrapper ​

PonderTextElementBuilderWrapper ​

PonderInputElementBuilderWrapper ​

PonderWorldInstructionsWrapper ​

PonderEffectInstructionsWrapper ​

PonderParticleInstructionsWrapper ​

PonderParticleDataBuilderWrapper ​

PonderSpecialInstructionsWrapper ​

PonderDebugInstructionsWrapper ​

PonderElementLinkWrapper ​

PonderParticleEmitterWrapper / PonderParrotElementWrapper / PonderInputWindowElementWrapper ​

3. 标签 API ​

PonderTagEventWrapper ​

PonderTagBuilderWrapper ​

PonderMultiTagBuilderWrapper ​