3.2

2024.12.11：版本号（V3.2 BE1.20.50） 包括Mod PC包，手机测试版启动器，和服务器引擎。

示例Demo：前往此处下载

一、更新时间表

1. 在2024年12月11日上线3.2第一个Beta版。
2. 在2024年12月26日上线3.2第二个Beta版。
3. 在2025年1月7日上线3.2稳定版。
4. 在2025年1月10日，全渠道将更新3.2版本玩家包体，玩家将陆续更新到3.2版本，请开发者合理安排更新节奏。

二、重要功能更新

由于本次更新和调整了大量接口，部分接口将于3.2第二个Beta版发布，届时本篇文档将同步更新，敬请关注。

1. 新增自定义指令接口，方便开发者和玩家使用指令调整模组功能。同时支持监听全局指令，支持实体发起指令。
2. 支持动态获取、创建、删除某个实体的行为包组件，可用于更精细地获取实体属性、控制实体行为，详见GetComponents系列接口。
3. 横屏商业化接口更新，支持手机端玩家在局内跳转到组件详情页或开发者主页，可用于组件宣传、组件联动、前置组件等场景。（第二个Beta版发布）
4. 新增实体单例渲染接口，可单独操纵某个实体的渲染，详见AddTextureToOneActor系列接口。
5. 后处理支持自定义外置纹理，可用于实现光怪陆离的后处理效果，详情参考文档自定义后处理。
6. 新增全局实体和特效功能，此类实体和特效不会因为距离过远超出视野而消失，可用于制作boss和大型装饰品（例如主城的传送门）。
7. 新增实用性接口和事件，如：类似望远镜的拉近视野接口，可用于枪械瞄准镜效果；玩家动作事件和跳跃事件，可用于动作优化类模组；客户端渲染帧事件，按照屏幕帧率高频调用。
8. 优化部分接口和事件，使其更具备实用性，如：支持molang缩写，双端BlockUseEvent支持获取点击比例位置等。详见下方更新日志。
9. 原版UI接口适配微软新触控，接口特性存在一定调整，请开发者注意适配。
10. 为了同步微软注册方式，我们隐藏了register_to_create_menu字段，并将其默认值改为true。请使用新版的category字段，详见自定义物品和自定义方块。
11. 由于微软在1.20.50版本将方块状态的facing_direction变更为cardinal_direction，所以原版实际使用facing_direction的四面向方块（如箱子类，熔炉类）的aux和实际朝向的对应关系被修改，如您此前利用方块调色板或者GetBlockNew记录了方块数据，在3.2直接按照原数据放出方块将出现部分方块朝向错乱，需要自行适配。现在GetBlockStates接口会返回新的cardinal_direction，而SetBlockStates会继续兼容旧版facing_direction一段时间。

• facing_direction和cardinal_direction的aux对应关系如下：

  朝向	facing_direction	cardinal_direction
  北面	2	2
  南面	3	0
  西面	4	1
  东面	5	3

• 受到影响的方块如下：

  名称	方块id
  箱子	chest
  末影箱	ender_chest
  陷阱箱	trapped_chest
  切石机	stonecutter_block
  熔炉	furnace
  高炉	blast_furnace
  烟熏炉	smoker
  燃烧的熔炉	lit_furnace
  燃烧的高炉	lit_blast_furnace
  燃烧的烟熏炉	lit_smoker

三、API更新

• 新增

1. 新增getEntitiesOrBlockFromRay(客户端)， 客户端新增获取与射线相交的实体和方块接口

2. 新增GetBlockTags(服务端)， 获取方块tags

3. 新增SetBlockEntityData(服务端)， 设置方块（包括自定义方块）的数据

4. 新增GetEntitiesBySelector(服务端)， 根据目标选择器获取实体id列表

5. 新增AddActorComponent(服务端)， 给指定实体自定义添加实体Component

6. 新增RemoveActorComponent(服务端)， 删除指定实体的指定Component

7. 新增GetComponents(服务端)， 获取指定实体的生效Components

8. 新增SetPistonMaxInteractionCount(服务端)， 设置活塞/粘性活塞最多推动的方块数量

9. 新增GetPistonMaxInteractionCount(服务端)， 获取活塞/粘性活塞最多推动的方块数量

10. 新增GetItemTags(服务端)， 获取物品tags

11. 新增GetItemInfoByBlockName(服务端)， 通过方块名称及aux值获取物品信息

12. 新增GetPlayerDestroyTotalTime(服务端)， 获取玩家破坏方块需要的时间，受玩家状态（急迫、潮涌、挖掘疲劳）和手持物及手持物附魔（效率）影响

13. 新增AddAnimationControllerToOneActor(客户端)， 增加单个生物渲染动画控制器

14. 新增RemoveAnimationControllerForOneActor(客户端)， 移除单个生物渲染动画控制器

15. 新增AddRenderMaterialToOneActor(客户端)， 增加单个生物的渲染材质

16. 新增AddRenderControllerToOneActor(客户端)， 增加单个生物的渲染控制器

17. 新增RemoveRenderControllerForOneActor(客户端)， 删除单个生物的渲染控制器

18. 新增AddGeometryToOneActor(客户端)， 增加单个生物渲染几何体

19. 新增RemoveGeometryForOneActor(客户端)， 删除单个生物的渲染几何体

20. 新增AddTextureToOneActor(客户端)， 增加单个生物的渲染贴图

21. 新增RemoveTextureForOneActor(客户端)， 删除单个生物的渲染贴图

22. 新增AddParticleEffectToOneActor(客户端)， 增加单个生物特效资源

23. 新增AddSoundEffectToOneActor(客户端)， 增加单个生物的音效资源

24. 新增AddScriptAnimateToOneActor(客户端)， 在单个生物的客户端实体定义（minecraft:client_entity）json中的scripts/animate节点添加动画/动画控制器

25. 新增AddAnimationToOneActor(客户端)， 增加单个生物渲染动画

26. 新增SetActorBlockGeometryScale(客户端)， 设置实体的方块几何体模型的缩放倍率。

27. 新增GetActorBlockGeometryScale(客户端)， 获取实体的方块几何体模型的缩放倍率。

28. 新增SetGlobal(客户端)， 设置序列帧是否是全局的

29. 新增CanSee(客户端)， 添加对象是否可看见目标的客户端接口

30. 新增GetPistonMaxInteractionCount(客户端)， 获取活塞/粘性活塞最多推动的方块数量

31. 新增GetItemTags(客户端)， 获取物品tags

32. 新增SetCompassTarget(客户端)， 设置指南针的朝向位置

33. 新增SetCompassEntity(客户端)， 设置指南针朝向的实体

34. 新增OpenResourceCenterDetailWindow(客户端)， 打开网易资源中心组件详情界面

35. 新增OpenDeveloperHomeWindow(客户端)， 打开网易资源中心开发者主页

36. 新增SetGlobal(客户端)， 设置粒子发射器是否为全局粒子发射器

37. 新增GetPlayerDestroyTotalTime(客户端)， 获取玩家破坏方块需要的时间，受玩家状态（急迫、潮涌、挖掘疲劳）和手持物及手持物附魔（效率）影响

38. 新增SetPlayerFovScale(客户端)， 新增设置fov倍率功能

39. 新增AddEntityMarker(客户端)， 增加实体位置标记

40. 新增AddEntityTextMarker(客户端)， 增加实体文本标记

41. 新增AddStaticMarker(客户端)， 增加地图上静态位置的标记

42. 新增AddStaticTextMarker(客户端)， 增加地图上静态文本的标记

43. 新增RemoveEntityMarker(客户端)， 删除实体位置标记

44. 新增RemoveEntityTextMarker(客户端)， 删除实体文本标记

45. 新增RemoveStaticMarker(客户端)， 删除静态位置标记

46. 新增RemoveStaticTextMarker(客户端)， 删除静态文本标记

47. 新增RepaintMiniMap(客户端)， 重新绘制小地图

48. 新增GlobalCommandServerEvent(服务端)， 服务端全局命令事件

49. 新增CustomCommandTriggerServerEvent(服务端)， 新增自定义命令触发事件

50. 新增OnPlayerActionServerEvent(服务端)， 玩家动作事件

51. 新增GameRenderTickEvent(客户端)， 客户端渲染帧开始时触发

52. 新增OnLocalPlayerStartJumpClientEvent(客户端)， 玩家开始跳跃事件

53. 新增OnLocalPlayerActionClientEvent(客户端)， 玩家动作事件

54. 新增PlayerActionType， 玩家动作枚举

• 调整

1. 调整getEntitiesOrBlockFromRay(服务端)， isThrouth拼写错误，调整为isThrough，通过关键词isThrouth = True调用的方法还会再兼容一段时间

2. 调整HideWalkGui(客户端)， 新触控接入后原移动按钮已移除，现在该接口控制新触控跑/走按钮

3. 调整HideSwimGui(客户端)， 调整描述，仅影响十字键操作下的浮潜按钮，摇杆模式上浮=跳跃，下潜=潜行，需要通过HideJumpGui和HideSneakGui来隐藏

4. 调整SetCrossHair(客户端)， 适配新触控

5. 调整CreateEngineEntityByNBT(服务端)， 新增isGlobal参数，可创建全局实体，不受视野范围限制

6. 调整CreateEngineEntityByTypeStr(服务端)， 新增isGlobal参数，可创建全局实体，不受视野范围限制

7. 调整SetAttrMaxValue(服务端)， 支持设置伤害吸收

8. 调整SetEntityOnFire(服务端)， 当传入参数seconds小于等于0时，将让着火的实体灭火

9. 调整RegisterBlockPatterns(服务端)， 支持具体方块匹配/通配，namespace:name:aux_value，当aux_value不填或者填*时为通配，如果有具体aux_value时只匹配特定方块

10. 调整GetBlockBasicInfo(服务端)， 支持返回minecraft:tags

11. 调整GetDestroyTotalTime(服务端)， 增加可选挖掘参数

12. 调整SetCommand(服务端)， 支持任意实体entityId

13. 调整GetItemBasicInfo(服务端)， 支持返回minecraft:tags

14. 调整SetItemTierSpeed(服务端)， 补充文档,提示开发者可以从物品的userData中获取挖掘速度

15. 调整GetDestroyTotalTime(客户端)， 增加可选挖掘参数

16. 调整GetItemBasicInfo(客户端)， 支持返回minecraft:tags

17. 调整CreateBindEntityNew(客户端)， 支持传入空字符串时，绑定到实体根骨骼上

18. 调整BindEntity(客户端)， 支持传入空字符串时，绑定到实体根骨骼上

19. 调整Register(客户端)， 支持molang变量缩写

20. 调整UnRegister(客户端)， 支持molang变量缩写

21. 调整Set(客户端)， 支持molang变量缩写

22. 调整Get(客户端)， 支持molang变量缩写

23. 调整GetMolangValue(客户端)， 支持molang变量缩写

24. 调整RenderEntity(客户端)， 支持设置x轴、z轴初始旋转

25. 调整RenderSkeletonModel(客户端)， 支持设置x轴、z轴初始旋转

26. 调整RenderBlockGeometryModel(客户端)， 支持设置x轴、z轴初始旋转

27. 调整ServerBlockUseEvent(服务端)， 新增clickX,clickY,clickZ参数，可获取点击点的比例位置

28. 调整PlayerPickupArrowServerEvent(服务端)， 调整文档，补充说明抛射物也受此接口监听

29. 调整PlaceNeteaseStructureFeatureEvent(服务端)， structureName参数可修改

30. 调整ClientBlockUseEvent(客户端)， 新增clickX,clickY,clickZ参数，可获取点击点的比例位置

31. 调整GyroSensorChangedClientEvent(客户端)， 新增orientation表示当前屏幕朝向

32. 调整OptionId， 移除旧版十字键操作

33. 调整OriginGUIName， 移除移动状态按钮，新触控有对应的加速按钮和潜行按钮，增加新触控跳跃/潜行枚举

• 废弃（将在未来不可用）

1. 废弃ChangeWalkState，对应按钮已移除，后续不再维护，相关需求可用setSprinting/setSneaking/ChangeSneakState实现

2. 废弃GetWalkState，对应按钮已移除，后续不再维护，相关需求可用isSprinting/isSneaking实现

3. 废弃SetPlayerRideEntity，请使用SetRiderRideEntity

4. 废弃AddEntityMarker，推荐使用UI面向对象miniMapUIControl.AddEntityMarker接口

5. 废弃RemoveEntityMarker，推荐使用UI面向对象miniMapUIControl.RemoveEntityMarker接口

6. 废弃AddStaticMarker，推荐使用UI面向对象miniMapUIControl.AddStaticMarker接口

7. 废弃RemoveStaticMarker，推荐使用UI面向对象miniMapUIControl.RemoveStaticMarker接口

8. 废弃ZoomIn，推荐使用UI面向对象miniMapUIControl.ZoomIn接口

9. 废弃ZoomOut，推荐使用UI面向对象miniMapUIControl.ZoomOut接口

10. 废弃ZoomReset，推荐使用UI面向对象miniMapUIControl.ZoomReset接口

11. 废弃SetHighestY，推荐使用UI面向对象minimapUIControl.SetHighestY接口

12. 废弃AddEntityTextMarker，推荐使用UI面向对象miniMapUIControl.AddEntityTextMarker接口

13. 废弃RemoveEntityTextMarker，推荐使用UI面向对象miniMapUIControl.RemoveEntityTextMarker接口

14. 废弃AddStaticTextMarker，推荐使用UI面向对象miniMapUIControl.AddStaticTextMarker接口

15. 废弃RemoveStaticTextMarker，推荐使用UI面向对象miniMapUIControl.RemoveStaticTextMarker接口