# 2.9
2023.10.24：版本号（V2.9 BE1.18.30）
包括Mod PC包，手机测试版启动器，和服务器引擎。

示例Demo：<a href="../../../mcguide/20-玩法开发/13-模组SDK编程/60-Demo示例.html" rel="noopenner">前往此处下载</a>

## 一、更新时间表
1. 在10月24日上线2.9第一个Beta版。
2. 在11月07日上线2.9第二个Beta版。
3. 在11月16日上线2.9稳定版。
4. 在11月24日，全渠道将更新2.9版本玩家包体，玩家将陆续更新到2.9版本，请开发者合理安排更新节奏。




## 二、重要功能更新
### 材质与着色器
1. 支持原版BB模型自定义shader的Uniform参数，实现动态材质表现，详见
[SetEntityExtraUniforms](../接口/实体/渲染.md#setentityextrauniforms)和[SetBlockEntityExtraUniforms](../接口/方块/渲染.md#setblockentityextrauniforms)系列接口。

![图片](../picture/V29_entityshaeruniform.gif)

2. 新增支持动态替换骨骼模型的材质接口，详见[SetModelMaterial](../接口/模型.md#setmodelmaterial)和[SetModelMultiPassMaterial](../接口/模型.md#setmodelmultipassmaterial)系列接口。

3. 新增获取骨骼模型shader的Uniform参数的接口，详见[GetExtraUniformValue](../接口/模型.md#getextrauniformvalue)。

4. 新增自定义后处理效果系列接口，包括获取开启状态，参数和管理多pass材质相关功能，详见[InsertPassToPostprocess](../接口/后处理/自定义.md#insertpasstopostprocess)和[CheckEnabledByName](../接口/后处理/自定义.md#checkenabledbyname)等接口。

5. 根据反馈再次更新了材质使用相关的教学文档，补充了更详细的配置和接口说明，详情参考<a href="../../../mcguide/16-美术/7-材质与着色器/1-材质介绍与着色器入门.html">材质介绍与着色器入门教程</a>。

6. 示例Demo新增针对性更强的自定义玩家材质、自定义实体模型材质、自定义骨骼模型材质、自定义网易粒子特效材质，自定义后处理的简单Demo，详见<a href="../../../mcguide/20-玩法开发/13-模组SDK编程/60-Demo示例.html" rel="noopenner">示例DEMO</a>，或直接前往内容库下载和使用。

### NBT系列接口
新增了部分获取和设置实体、玩家的NBT属性的接口，详见[实体属性](../接口/实体/属性.md)、[实体行为](../接口/实体/行为.md)、[玩家属性](../接口/玩家/属性.md#getenchantmentseed)和[玩家权限](../接口/玩家/权限.md)等模块的新增接口。



### 大型结构特征
1. 支持下界和末地生成大型结构特征，详见<a href="../../../mcguide/20-玩法开发/15-自定义游戏内容/4-自定义维度/6-自定义大型特征.html" rel="noopenner">这篇文档</a>。
2. 修复了概率丢失部分结构的问题。
3. 修复了结构包含命令方块时，概率出现断言的问题。
4. 新增大型结构生成事件，且支持取消生成，详见[PlaceNeteaseLargeFeatureServerEvent](../事件/世界.md#placeneteaselargefeatureserverevent)。

### 成就系统
1. 成就系统的按钮被拖动时抛出事件，详见[AchievementButtonMovedClientEvent](../事件/UI.md#achievementbuttonmovedclientevent)。
2. 新增获取和设置成就系统按钮的接口，详见[SetAchievementGatePosition](../接口/自定义UI/自定义成就系统.md#setachievementgateposition)和[GetAchievementGatePosition](../接口/自定义UI/自定义成就系统.md#getachievementgateposition)。
3. 替换了关闭按钮的UI资源。
4. 修复成就系统概率重置的问题。


### UI
1. 小地图控件支持增加文本标记，详见[AddEntityTextMarker](../接口/自定义UI/UI界面.md#addentitytextmarker)接口。
2. 网易纸娃娃支持渲染某一类生物，无需关联某个实例，详见[RenderEntity](../接口/自定义UI/UI控件.md#renderentity)。

3. 网易纸娃娃支持定义灯光方向，详见[RenderSkeletonModel](../接口/自定义UI/UI控件.md#renderskeletonmodel)接口。

![图片](../picture/V29PaperDollLight.png)

4. 修复了网易纸娃娃arm_model切换到第一人称时出现偏移的问题。
5. [GridComponentSizeChangedClientEvent](../事件/UI.md#gridcomponentsizechangedclientevent)新增抛出grid路径参数。
6. [GetPath](../接口/自定义UI/UI控件.md#getpath)(客户端)， 返回当前控件的相对路径。
7. [SetBindWorldPosition](../接口/自定义UI/UI界面.md#setbindworldposition)，设置绑定到世界坐标的UI控件的位置。

### 物品分页
1. 物品分页新增sort_by_identifier字段，支持该分页按照物品标识符分组，详见<a href="../../../mcguide/20-玩法开发/15-自定义游戏内容/13-自定义物品分页.html" rel="noopenner">这篇文档</a>。

### 游戏设置
1. [SetToggleOption](../接口/游戏设置.md#settoggleoption)新增多个可控制的游戏设置，包括十字键，平滑光照等等。

### 摄像机
1. [SetCameraAnchor](../接口/玩家/摄像机.md#setcameraanchor)(客户端)支持XZ轴。
2. 新增[GetCameraRotation](../接口/玩家/摄像机.md#getcamerarotation)替代原有GetCameraRot，支持获取三个方向角度。

### 骨骼模型
1. ModelComp组件下部分接口支持传入ModelId参数，用于指定模型，如[SetTexture](../接口/模型.md#settexture)(客户端)。

### 其他
1. 修复了射线检测接口无法用于方块检测的问题，详见[getEntitiesOrBlockFromRay](../接口/世界/实体管理.md#getentitiesorblockfromray)。
2. 方块配置的netease:block_chest组件新增了can_be_blocked字段，用于控制箱子的开启是否受到实心方块的阻挡，详见<a href="../../../mcguide/20-玩法开发/15-自定义游戏内容/2-自定义方块/1-JSON组件.html" rel="noopenner">这篇文档</a>。

## 三、API更新
- 新增

1. 新增[GetEntityDefinitions](../接口/实体/实体类型.md#getentitydefinitions)(服务端)， 获取实体的命名空间ID及其当前和之前的定义组件群<!--by cxz-->

1. 新增[GetEntityFallDistance](../接口/实体/属性.md#getentityfalldistance)(服务端)， 获取实体的坠落高度，越大的值会给予实体更大的坠落伤害<!--by cxz-->

1. 新增[GetEntityLinksTag](../接口/实体/属性.md#getentitylinkstag)(服务端)， 获取实体相连接的实体，如获取entityId为马，会返回骑乘者的信息<!--by cxz-->

1. 新增[IsLootDropped](../接口/实体/行为.md#islootdropped)(服务端)， 获取生物是否生成掉落物<!--by cxz-->

1. 新增[SetLootDropped](../接口/实体/行为.md#setlootdropped)(服务端)， 设置生物是否生成掉落物<!--by cxz-->

1. 新增[GetMobColor](../接口/实体/属性.md#getmobcolor)(服务端)， 获取生物的颜色，截止至网易2.9版本，只对羊和热带鱼有效<!--by cxz-->

1. 新增[SetMobColor](../接口/实体/属性.md#setmobcolor)(服务端)， 设置生物的颜色，截止至网易2.9版本，只对羊和热带鱼有效<!--by cxz-->

1. 新增[GetMobStrength](../接口/实体/属性.md#getmobstrength)(服务端)， 获取生物的强度，截止至网易2.9版本，只对羊驼有效，强度越大羊驼驮运的箱子时格子数量越多<!--by cxz-->

1. 新增[SetMobStrength](../接口/实体/属性.md#setmobstrength)(服务端)， 设置生物的强度，截止至网易2.9版本，只对羊驼有效，强度越大羊驼驮运的箱子时格子数量越多<!--by cxz-->

1. 新增[GetMobStrengthMax](../接口/实体/属性.md#getmobstrengthmax)(服务端)， 获取生物强度的最大值，截止至网易2.9版本，只对羊驼有效，强度越大羊驼驮运的箱子时格子数量越多，[SetMobStrength](#setstrength)无法超过SetMobStrengthMax的值<!--by cxz-->

1. 新增[SetMobStrengthMax](../接口/实体/属性.md#setmobstrengthmax)(服务端)， 设置生物强度的最大值，截止至网易2.9版本，只对羊驼有效，强度越大羊驼驮运的箱子时格子数量越多，[SetMobStrength](#setmobstrength)无法超过SetMobStrengthMax的值<!--by cxz-->

1. 新增[IsSheared](../接口/实体/属性.md#issheared)(服务端)， 判断实体是否被剃毛，截止至网易2.9版本，只对羊有效<!--by cxz-->

1. 新增[SetSheared](../接口/实体/属性.md#setsheared)(服务端)， 设置实体是否被剃毛，截止至网易2.9版本，只对羊有效<!--by cxz-->

1. 新增[IsIllagerCaptain](../接口/实体/属性.md#isillagercaptain)(服务端)， 判断实体是否为袭击队长，截止至网易2.9版本，只对掠夺者和卫道士有效<!--by cxz-->

1. 新增[PromoteToIllagerCaptain](../接口/实体/属性.md#promotetoillagercaptain)(服务端)， 晋升实体为袭击队长，截止至网易2.9版本，只对掠夺者和卫道士有效<!--by cxz-->

1. 新增[IsSitting](../接口/实体/属性.md#issitting)(服务端)， 判断实体是否处于坐下状态<!--by cxz-->

1. 新增[SetSitting](../接口/实体/属性.md#setsitting)(服务端)， 设置生物是否坐下<!--by cxz-->

1. 新增[IsBaby](../接口/实体/属性.md#isbaby)(服务端)， 判断实体是否为幼年<!--by cxz-->

1. 新增[SetAsAdult](../接口/实体/属性.md#setasadult)(服务端)， 设置实体为成年体<!--by cxz-->

1. 新增[IsTamed](../接口/实体/属性.md#istamed)(服务端)， 判断实体是否被驯服<!--by cxz-->

1. 新增[IsAngry](../接口/实体/属性.md#isangry)(服务端)， 判断实体是否处于激怒状态<!--by cxz-->

1. 新增[SetAngry](../接口/实体/属性.md#setangry)(服务端)， 设置实体是否处于激怒状态<!--by cxz-->

1. 新增[IsOutOfControl](../接口/实体/属性.md#isoutofcontrol)(服务端)， 判断实体是否处于失控状态，截止至网易2.9版本，只对船有效<!--by cxz-->

1. 新增[SetOutOfControl](../接口/实体/属性.md#setoutofcontrol)(服务端)， 设置实体是否处于失控状态，截止至网易2.9版本，只对船有效<!--by cxz-->

1. 新增[GetVariant](../接口/实体/属性.md#getvariant)(服务端)， 获取实体的变种属性值<!--by cxz-->

1. 新增[SetVariant](../接口/实体/属性.md#setvariant)(服务端)， 设置实体的变种属性值<!--by cxz-->

1. 新增[GetMarkVariant](../接口/实体/属性.md#getmarkvariant)(服务端)， 获取实体的标记变种属性值<!--by cxz-->

1. 新增[SetMarkVariant](../接口/实体/属性.md#setmarkvariant)(服务端)， 设置实体的标记变种属性值<!--by cxz-->

1. 新增[HasSaddle](../接口/实体/属性.md#hassaddle)(服务端)， 判断实体是否装备了鞍<!--by cxz-->

1. 新增[HasChest](../接口/实体/属性.md#haschest)(服务端)， 判断生物是否背负了箱子，截止至网易2.9版本，只对羊驼、驴、骡生效<!--by cxz-->

1. 新增[SetChest](../接口/实体/属性.md#setchest)(服务端)， 设置生物是否背负了箱子，截止至网易2.9版本，只对羊驼、驴、骡生效<!--by cxz-->

1. 新增[IsEating](../接口/实体/行为.md#iseating)(服务端)， 判断非玩家实体是否在进食<!--by cxz-->

1. 新增[IsStunned](../接口/实体/行为.md#isstunned)(服务端)， 判断是否处于眩晕状态，截止至网易2.9版本，仅对劫掠兽有效<!--by cxz-->

1. 新增[IsRoaring](../接口/实体/行为.md#isroaring)(服务端)， 判断是否处于咆哮状态，截止至网易2.9版本，仅对劫掠兽有效<!--by cxz-->

1. 新增[IsPersistent](../接口/实体/行为.md#ispersistent)(服务端)， 判断是否为持久性生物<!--by cxz-->

1. 新增[GetLeashHolder](../接口/实体/行为.md#getleashholder)(服务端)， 获取实体被使用拴绳牵引时牵引者的ID<!--by cxz-->

1. 新增[SetLeashHolder](../接口/实体/行为.md#setleashholder)(服务端)， 为实体添加牵引者，与原版拴绳的作用相同<!--by cxz-->

1. 新增[GetTradeLevel](../接口/实体/属性.md#gettradelevel)(服务端)， 获取村民的交易等级<!--by cxz-->

1. 新增[SetTradeLevel](../接口/实体/属性.md#settradelevel)(服务端)， 设置村民的交易等级<!--by cxz-->

1. 新增[GetDeathTime](../接口/实体/属性.md#getdeathtime)(服务端)， 获取生物死亡后持续的时间（刻，1秒20刻），用于控制死亡动画。0表示生物未死亡。<!--by cxz-->

1. 新增[IsNaturallySpawned](../接口/实体/属性.md#isnaturallyspawned)(服务端)， 获取生物是否为自然生成的<!--by cxz-->

1. 新增[IsPregnant](../接口/实体/属性.md#ispregnant)(服务端)， 获取生物是否怀孕，截止至网易2.9版本，只对海龟有效<!--by cxz-->

1. 新增[GetEnchantmentSeed](../接口/玩家/属性.md#getenchantmentseed)(服务端)， 获取玩家的附魔种子，该种子会决定附魔台上准备附魔的装备的附魔项<!--by cxz-->

1. 新增[SetEnchantmentSeed](../接口/玩家/属性.md#setenchantmentseed)(服务端)， 设置玩家的附魔种子，该种子会决定附魔台上准备附魔的装备的附魔项<!--by cxz-->

1. 新增[SetBuildAbility](../接口/玩家/权限.md#setbuildability)(服务端)， 设置玩家能否放置方块，该接口的设置会存档，且只影响生存模式<!--by cxz-->

1. 新增[SetMineAbility](../接口/玩家/权限.md#setmineability)(服务端)， 设置玩家能否摧毁方块，该接口的设置会存档，且只影响生存模式<!--by cxz-->

1. 新增[SetOperateDoorsAndSwitchesAbility](../接口/玩家/权限.md#setoperatedoorsandswitchesability)(服务端)， 设置玩家能否与门和开关交互，该接口的设置会存档，影响生存、创造、冒险模式<!--by cxz-->

1. 新增[SetOpenContainersAbility](../接口/玩家/权限.md#setopencontainersability)(服务端)， 设置玩家能否打开容器，该接口的设置会存档，影响生存、创造、冒险模式<!--by cxz-->

1. 新增[SetAttackPlayersAbility](../接口/玩家/权限.md#setattackplayersability)(服务端)， 设置玩家能否攻击其他玩家，该接口的设置会存档，影响生存、创造、冒险模式<!--by cxz-->

1. 新增[SetAttackMobsAbility](../接口/玩家/权限.md#setattackmobsability)(服务端)， 设置玩家能否攻击生物，该接口的设置会存档，影响生存、创造、冒险模式<!--by cxz-->

1. 新增[SetAchievementGatePosition](../接口/自定义UI/自定义成就系统.md#setachievementgateposition)(客户端)， 设置自定义成就系统的入口按钮位置<!--by cxz-->

1. 新增[GetAchievementGatePosition](../接口/自定义UI/自定义成就系统.md#getachievementgateposition)(客户端)， 获取自定义成就系统的入口按钮位置<!--by cxz-->

1. 新增[SetEntityExtraUniforms](../接口/实体/渲染.md#setentityextrauniforms)(客户端)， 新增设置用于实体shader的自定义变量接口<!--by xujiarong02-->

1. 新增[SetEntityUIExtraUniforms](../接口/实体/渲染.md#setentityuiextrauniforms)(客户端)， 新增设置用于实体shader的UI自定义变量接口<!--by xujiarong02-->

1. 新增[GetEntityExtraUniforms](../接口/实体/渲染.md#getentityextrauniforms)(客户端)， 新增获取在实体shader使用的自定义变量的值的接口<!--by xujiarong02-->

1. 新增[GetEntityUIExtraUniforms](../接口/实体/渲染.md#getentityuiextrauniforms)(客户端)， 新增获取在实体shader使用的UI自定义变量的值的接口<!--by xujiarong02-->

1. 新增[SetBlockEntityExtraUniforms](../接口/方块/渲染.md#setblockentityextrauniforms)(客户端)， 设置可在自定义方块实体的shader当中使用的自定义变量的值。<!--by xujiarong-->

1. 新增[GetBlockEntityExtraUniforms](../接口/方块/渲染.md#getblockentityextrauniforms)(客户端)， 获取在自定义方块实体的shader当中使用的自定义变量的值。<!--by xujiarong-->

1. 新增[GetCameraRotation](../接口/玩家/摄像机.md#getcamerarotation)(客户端)， 获取摄像机的朝向，支持获取翻滚角<!--by czh-->

1. 新增[GetExtraUniformValue](../接口/模型.md#getextrauniformvalue)(客户端)， 获取在骨骼模型shader中使用的自定义变量Uniform的值<!--by xujiarong-->

1. 新增[SetModelMaterial](../接口/模型.md#setmodelmaterial)(客户端)， 新增设置骨骼模型的所使用的自定义材质接口<!--by xujiarong-->

1. 新增[SetModelMultiPassMaterial](../接口/模型.md#setmodelmultipassmaterial)(客户端)， 新增设置骨骼模型的所使用的多Pass材质接口<!--by xujiarong-->

1. 新增[GetModelMaterial](../接口/模型.md#getmodelmaterial)(客户端)， 新增获取骨骼模型的正在使用的材质名称的接口<!--by xujiarong-->

1. 新增[SetRotUseZXY](../接口/特效/微软粒子.md#setrotusezxy)(客户端)， 设置粒子发射器旋转，旋转顺序按照绕z,x,y轴旋转<!--by xujiarong-->

1. 新增[CheckEnabledByName](../接口/后处理/自定义.md#checkenabledbyname)(客户端)， 查询是否开启了自定义后处理效果<!--by xujiarong-->

1. 新增[GetParameter](../接口/后处理/自定义.md#getparameter)(客户端)，  获取指定自定义后处理参数的值<!--by xujiarong-->

1. 新增[InsertPassToPostprocess](../接口/后处理/自定义.md#insertpasstopostprocess)(客户端)，  往自定义后处理的多pass中的指定位置插入自定义pass<!--by xujiarong-->

1. 新增[PushBackPassToPostprocess](../接口/后处理/自定义.md#pushbackpasstopostprocess)(客户端)，  往自定义后处理的多pass的最末尾插入自定义pass<!--by xujiarong-->

1. 新增[RemovePassInPostprocess](../接口/后处理/自定义.md#removepassinpostprocess)(客户端)，  删除自定义后处理的多pass中指定位置的pass<!--by xujiarong-->

1. 新增[PopBackPassInPostprocess](../接口/后处理/自定义.md#popbackpassinpostprocess)(客户端)，  删除自定义后处理的多pass的最末尾的pass<!--by xujiarong-->

1. 新增[SetBindWorldPosition](../接口/自定义UI/UI界面.md#setbindworldposition)(客户端)， 设置UI绑定的worldPosition<!--by cxz-->

1. 新增[AddEntityTextMarker](../接口/自定义UI/UI界面.md#addentitytextmarker)(客户端)， 增加实体文本标记<!--by dongbingyang-->

1. 新增[RemoveEntityTextMarker](../接口/自定义UI/UI界面.md#removeentitytextmarker)(客户端)， 删除实体文本标记<!--by dongbingyang-->

1. 新增[AddStaticTextMarker](../接口/自定义UI/UI界面.md#addstatictextmarker)(客户端)， 增加地图上静态文本的标记<!--by dongbingyang-->

1. 新增[RemoveStaticTextMarker](../接口/自定义UI/UI界面.md#removestatictextmarker)(客户端)， 删除静态文本标记<!--by dongbingyang-->

1. 新增[GetPath](../接口/自定义UI/UI控件.md#getpath)(客户端)， 返回当前控件的相对路径，路径从画布节点开始算起<!--by hdy-->

1. 新增[PlayerFeedEntityServerEvent](../事件/玩家.md#playerfeedentityserverevent)(服务端)， 玩家喂养生物时触发，例如玩家手持小麦喂养牛、玩家手持胡萝卜喂养幼年猪。<!--by hdy-->

1. 新增[PlayerNamedEntityServerEvent](../事件/玩家.md#playernamedentityserverevent)(服务端)， 玩家用命名牌重命名实体时触发，例如玩家手持命名牌对羊修改名字、玩家手持命名牌对盔甲架修改名字。<!--by hdy-->

1. 新增[PlaceNeteaseLargeFeatureServerEvent](../事件/世界.md#placeneteaselargefeatureserverevent)(服务端)， 触发时机：网易版大型结构即将生成时服务端抛出该事件<!--by hdy-->

1. 新增[AchievementButtonMovedClientEvent](../事件/UI.md#achievementbuttonmovedclientevent)(客户端)， 使用自定义成就系统的时，拖动成就入口结束时触发<!--by cxz-->

- 调整

1. 调整[getEntitiesOrBlockFromRay](../接口/世界/实体管理.md#getentitiesorblockfromray)(服务端)， 支持检测方块<!--by hdy-->

1. 调整[GetRecipeResult](../接口/世界/配方.md#getreciperesult)(服务端)， 返回值新增fullItemName字段，包含了物品的命名空间。原来的itemName字段弃用<!--by czh-->

1. 调整[GetOwnerId](../接口/实体/行为.md#getownerid)(服务端)， 现在主人实体未在世界内加载也可以返回id<!--by czh-->

1. 调整[SetCameraAnchor](../接口/玩家/摄像机.md#setcameraanchor)(客户端)， 支持x、z轴<!--by xsf-->

1. 调整[PlayAnim](../接口/模型.md#playanim)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[GetAnimLength](../接口/模型.md#getanimlength)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[SetAnimSpeed](../接口/模型.md#setanimspeed)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[SetTexture](../接口/模型.md#settexture)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[GetTexture](../接口/模型.md#gettexture)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[SetLegacyBindRot](../接口/模型.md#setlegacybindrot)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[GetBoneWorldPos](../接口/模型.md#getboneworldpos)(客户端)， 增加modelId参数，用于选择指定模型<!--by xsf-->

1. 调整[GetOwnerId](../接口/实体/行为.md#getownerid)(客户端)， 现在主人实体未在世界内加载也可以返回id<!--by czh-->

1. 调整[RenderEntity](../接口/自定义UI/UI控件.md#renderentity)(客户端)， 支持使用实体identifier进行渲染<!--by xujiarong-->

1. 调整[RenderSkeletonModel](../接口/自定义UI/UI控件.md#renderskeletonmodel)(客户端)， 新增light_direction参数，可以控制骨骼模型在纸娃娃中的打光方向<!--by xujiarong-->

1. 调整[DamageEvent](../事件/实体.md#damageevent)(服务端)， 增加ignite参数注意事项<!--by xusifan-->

1. 调整[OnFireHurtEvent](../事件/实体.md#onfirehurtevent)(服务端)， 新增cancelIgnite参数，支持取消点燃效果<!--by xusifan-->

1. 调整[GridComponentSizeChangedClientEvent](../事件/UI.md#gridcomponentsizechangedclientevent)(客户端)， 增加path参数，grid网格所在的路径（从UI根节点算起）<!--by hdy-->

1. 调整[OptionId](../枚举值/OptionId.md)， 新增十字键操作、隐藏HUD、摄像机摇晃等8个OptionId<!--by xsf-->

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

1. 废弃GetCameraRot，请使用GetCameraRotation接口