Kzeroko KTM2

保护区域

地标、受保护建筑及其中住所共用的保护层:玩家规则、破坏防护与客户端预测。

更新于 2026/11/4 12 分钟阅读

所有受保护的地方共用internal.protection里的同一层:Atelier地标,以及protectedStructures选项列出的每一种建筑,比如冒险者公会。玩家的每次改动,服务器和客户端都用同一张判定表来回答。区域内的方块不会被生物、爆炸、火、流体、活塞或发射器改动,doMobGriefing游戏规则开着也一样。

它做什么

这一层负责三件事。区域来源说明保护在哪里生效;玩家权限根据区域和家园判定每一次玩家操作;破坏作用域标出方块写入的起因,让写入守卫拒绝环境破坏。

它有意止步于以下边界:

  • 家园仍归结构空间管。 成员、租期、授权和访客都属于结构空间,这一层只读取授权位。
  • 生成有独立边界。 地标保留自己的生成策略,可配置和平建筑由internal.spawning.PeacefulStructures处理,修改方块保护不会改动这份列表。
  • 普通实体不会被冻结。 生物在区域里照常走动、战斗、受伤,陈设实体与受保护的公会接待员会受到保护。
  • 地牢世界用自己的规则。 DungeonWorldPolicy保留它的放置限制,区域不覆盖地牢世界。

运行时模型

区域来源

ProtectionZones用数组保存已注册的来源,并取它们的并集。客户端世界里永远没有区域。

来源注册位置范围生命周期
LandmarkZoneSourceAtelierSystem.init地标占地加留空区,覆盖整个高度世界绑定地标后就不再变化
StructureZoneSourceProtectionSystem.init列出建筑每个起点的边界,水平方向和下方各扩展protectedStructureMargin格,向上直到建筑高度上限从第一个引用它的区块被扫描起,到世界卸载为止

建筑来源会把每个已加载区块扫描一次,找出对列出建筑的引用。区块加载先排队,在世界刻末尾统一处理,这时可以按原版方式加载区块来读取被引用的起点。在这之间的查询只扫描自己所在的区块,从不加载区块。修改任一选项都会重建所有区域,并重新扫描已加载区块。列表里没有注册为建筑的ID会记一条警告,然后跳过。

选项类型默认值作用
protectedStructureslist of identifiersisekaiexpansion:respawn_temple、isekaiexpansion:adventurers_guild、isekaiexpansion:world_portal_ruins这些建筑的每个起点都会成为区域。
protectedStructureMargininteger4每个起点在水平四周和下方额外保护的格数,0–16,超出范围会被截断。

和平建筑生成判定

仅服务端使用的peacefulStructures列表默认取上述三个ID,并分别追加,16。严格的namespace:structure,range格式、0–128范围与生成例外见和平建筑。它与protectedStructureMargin独立,和平范围水平扩展并覆盖所有高度。

已加载的列表变化时,PeacefulStructureRule解析条目。PeacefulStructures在各世界解析ID,无效或未注册的条目记录警告后跳过,重复ID取有效条目中的最大范围。空列表或null只关闭这些可配置限制。

PeacefulStructureIndex缓存不可变的扩展矩形。缓存未命中时,按配置范围检查相邻的建筑引用区块,再读取实际建筑起点。读取只请求STRUCTURE_REFERENCES和STRUCTURE_STARTS,两者都早于地形与实体生成,因此首次查询可能加载或生成建筑元数据。它不请求完整地形区块,也不扫描实体。每个世界最多缓存8192个引用区块条目和4096个查询区块条目,空结果也会缓存。缓存加载过程不跨区块请求持锁,因此生成线程等待服务端处理区块时,不会锁住服务端对同一区域的查询。

AtelierSpawnHelperMixin在创建实体前拒绝普通候选;AtelierServerSpawnMixin和AtelierChunkRegionMixin使用LandmarkSpawnPolicy.Source检查最终接纳。被抑制的来源为NATURAL、CHUNK_GENERATION、STRUCTURE、PATROL、REINFORCEMENT和JOCKEY。已有实体与明确的遭遇来源继续遵循各自规则。

各世界使用独立缓存。区块卸载会使该引用区块及受影响的相邻查询条目失效。已加载列表变化后,下一次查询替换状态;数据包成功重载或世界卸载时丢弃状态。此功能不写入持久数据,也不增加其他配置语法。

判定表

权限等级2以上的创造模式玩家绕过所有规则。其他人一律交给ProtectionRules.allows,按这个顺序检查:先看不可破坏标签,再看占有该位置的家园授权,最后看区域。

操作家园权限区域内、家园外限制标签
BREAKBREAK拒绝isekaiexpansion:protection/unbreakable在任何地方都拒绝,自己的家园也不例外
BUILDBUILD拒绝无
USEUSE允许,受限方块除外isekaiexpansion:protection/restricted_use
SLEEPSLEEP允许无
ENTITYENTITIES允许,受限实体除外isekaiexpansion:protection/fixtures

区域内的家园用自己的授权代替区域的玩家规则,包括使用受限方块。在所有区域之外,家园照样按授权判定,空地则什么都允许。

实体使用走独立判定:自己的有效 NPC 随从、驯养伙伴及绑定召唤物无需房产管理权限即可交互。其他 NPC 与村民按住所 USE 权限判定,租客已具备该权限。攻击、陈设及其他实体交互仍需 ENTITIES。客户端预测与服务端回调都遵循这一区别。

玩家钩子

玩家输入钩子检查的操作
挖掘ServerPlayerInteractionManager在收到动作时和移除方块前各查一次;客户端在攻击、挖掘进度和移除时也查BREAK
放置方块两端的BlockItem.canPlace;床还检查床头格,两格高的方块检查另一半BUILD
isekaiexpansion:protection/restricted_items中的工具两端的ItemStack.useOnBlock,检查点击的方块和点击面前方的一格BUILD
用桶放置、用桶舀起BucketItem.placeFluid,以及舀起前的BucketItem.useBUILD、BREAK
使用方块UseBlockCallback,在默认监听器之前的isekaiexpansion:protection阶段USE,床则是SLEEP
攻击或使用实体AttackEntityCallback、UseEntityCallback,同一阶段攻击为 ENTITY,NPC 使用遵循上述规则
编辑、染色、发光或涂蜡告示牌AbstractSignBlockBUILD
落在耕地上FarmlandBlock.onLandedUponBUILD

任一只手拿着物品潜行时,原版本来就跳过方块自己的使用,所以这里也跳过使用检查。命令告示牌照常可以点击。服务器上玩家使用的每件物品都在玩家作用域里运行,模组物品自己改动的方块同样会被判定。

破坏作用域

ProtectionScope按线程记录一个起因。起因生效期间,World.setBlockState和WorldChunk.setBlockState会拒绝该起因在区域里不能做的写入。作用域可以嵌套,结束时恢复外层,被包住的调用抛出异常也一样。

起因开启位置在区域内拒绝
MOB每个生物、弹射物和闪电的刻除了不改age的同方块变化(比如门)之外的一切改动;作物的变化一律算破坏
EXPLOSIONExplosion.affectWorld一切改动;受保护的格子会先从受影响列表里移除
FIREFireBlock.scheduledTick除了改动已有火方块之外的一切改动,所以火会照常老化、熄灭
MECHANISMDispenserBlock.dispense一切改动
PLAYER物品使用、铁砧取出产物同方块切换放行;其他改动在结果为空气时需要BREAK,否则需要BUILD

作用域另有几条在写入前生效的规则:

  • 生物破坏规则读作关闭:正在计算刻的生物,碰撞箱向外扩2格后碰到区域时就是这样。破门、末影人搬方块、踩坏作物都不会开始。游戏规则本身不变。
  • 不是玩家的执行者在区域内会被World.breakBlock和canModifyAt拒绝。玩家射出的弹射物按射手的BREAK权限判定。
  • 陈设实体在区域内不受任何伤害,有权限的玩家和移出世界类伤害除外。
  • 火势蔓延到区域格子时,在格子燃烧前就被拒绝,所以区域里的TNT不会被点燃。
  • 活塞的推动只要会移动、破坏或填入区域格子,就会失败。
  • 流体不会从区域外或另一个家园流进区域,也不会冲掉区域里的方块。已有的流体和含水方块照常可用。

客户端预测

客户端用快照来预测,被拒绝的方块不会先在本地放下或挖掉。进入服务器时,如果服务器公开了isekaiexpansion:protection_request,客户端就发出这个空包并等待快照;这个请求不授予任何权限。服务器在isekaiexpansion:protection上回复。

字段类型默认值作用
protocolVarInt必填必须是1,其他值会被拒绝。
dimensionidentifier必填这份快照替换的维度。
editorboolean必填服务器计算的创造模式管理员绕过标记。
zoneCountVarInt必填0–256个区域。
zoneszoneCount × 6 signed integers必填闭区间的minX、minY、minZ、maxX、maxY、maxZ。
claimCountVarInt必填发送的区域内0–1024个家园范围。
claimsclaimCount × 7 signed integers必填一个范围的六个边界,再加上它授予这名玩家的家园权限位,0–31。

服务器发送快照中心256格内的区域,符合条件的太多时优先保留最近的。维度、管理员状态、区域版本或家园版本变化时,玩家离中心超过64格时,以及每100刻(按玩家错开)都会重建快照。重建后内容没变就不发送。

当前维度的快照到达之前,客户端拒绝BREAK和BUILD,允许USE、SLEEP和ENTITY。绕过需要服务器的标记和本地的创造模式管理员状态同时成立。被拒绝时,动作栏显示message.isekaiexpansion.protection.denied,等待快照期间显示message.isekaiexpansion.protection.syncing,每秒最多一次。

约定

  • 建筑区域只在服务器线程上回答。 StructureZoneSource只在服务器线程上应答,其他线程看不到建筑区域。地标区域不可变,任何线程都安全。
  • 来源必须便宜。 这一层在方块更新路径里查询区域来源,来源必须从内存直接回答,不能等待区块加载。
  • 没有作用域的写入照旧。 命令、Atelier任务、网络包和普通方块刻都没有破坏作用域。
  • 家园只代替玩家规则。 环境防护覆盖整个区域,家园也在其中。区域外的家园只有玩家规则。
  • 拒绝后会修正客户端。 挖掘被拒绝时,先重发目标、它的6个相邻格及方块实体,再确认动作。放置、工具或桶被拒绝时,会重新同步当前界面的物品栏。
  • 读包是严格的。 反向边界、超范围的授权位、超出索引预算和多余的字节都会被拒绝。

扩展方式

在模组初始化时注册区域来源。接口在api.protection里:

ProtectionAPI.registerZoneSource(new ProtectionZoneSource() {
    @Override public boolean contains(ServerWorld world, BlockPos pos) { return ARENA.contains(pos); }
    @Override public boolean intersects(ServerWorld world, BlockBox box) { return ARENA.intersects(box); }
    @Override public void collect(ServerWorld world, BlockBox area, Consumer<BlockBox> sink) {
        if (ARENA.intersects(area)) sink.accept(ARENA);
    }
    @Override public long revision(ServerWorld world) { return 0; }
});

用自己的代码路径改方块的工具,动手前先问一声。ProtectionAPI.allows、canBreak、canBuild和canUse、canAttack在客户端做预测,在服务器做判定。canEntityModify用于实体自己发起的改动。客户端的挖掘或放置输入改查api.client.protection.ProtectionClientAPI。

GuildReceptionistEntity 在服务器上按当前位置查询 ProtectionAPI.isProtected,并将结果同步给客户端的攻击判定。受保护时拒绝攻击、所有伤害、有害状态、推挤、击退及爆炸。基础服务大脑不安装平民威胁传感器与逃跑任务。实体仍可被准星选中以便右键交谈,移除标记仍会撤下接待员。这套服务规则独立于也会限制交互的陈设标签。

验证

先跑离线检查,再对重映射后的jar跑生产环境钩子检查:

./gradlew.bat -I tools/atelier/verify.gradle checkAtelier --offline --console=plain
./gradlew.bat -I tools/atelier/verify.gradle checkProtectionRemap -PatelierMinecraftIntermediary=<minecraft-merged-intermediary.jar> --offline

ProtectionCheck会在地标、建筑和家园格子上比对客户端预测与判定表,并覆盖读包拒绝、权限切换、作用域起因与嵌套,以及两格方块的放置。重映射检查证明每个钩子都恰好对准一个原版方法或调用。

然后在有公会和地标的世界里实测。用生存玩家试着挖掘,放床、树苗和门,用骨粉、锄头和桶,编辑告示牌,打物品展示框,踩耕地。打开doMobGriefing,让僵尸走到门前、苦力怕在边界爆炸、末影人穿过区域。再在自己拥有的家园里、重新连接后、切换维度后、离开创造模式后各试一遍。

相关页面

地标范围见Atelier结构,家园授权见结构空间。玩家看的家园说明在我的家园。