Gateway Builder

Gateway Builder / 网关构建器

Creating builders / 创建 Builder

Gateway.customBuilder(id) creates and registers a normal dynamic gateway. Gateway.builder(id) points to an already registered gateway and is mainly used to spawn it at a selected position.

Gateway.customBuilder(id) 用于创建并注册普通动态网关。Gateway.builder(id) 指向一个已经注册的网关，主要用于在指定位置生成它。

Method	Purpose / 用途
Gateway.customBuilder(id)	Create a custom normal gateway / 创建普通自定义网关
Gateway.builder(id)	Spawn or inspect an existing gateway / 生成或检查已有网关
Gateway.endlessBuilder(id)	Create an Endless gateway, 1.21.1 only / 创建无尽网关，仅 1.21.1
Gateway.apotheosisTieredBuilder(id, tier)	Create an Apotheosis tiered gateway, 1.21.1 only / 创建神化分层网关，仅 1.21.1

Display and layout / 显示与布局

• name(text): direct display name / 直接显示名称
• tooltipKey(key): translation key for the pearl tooltip / 珍珠提示汉化键
• tooltipText(text): direct pearl tooltip / 珍珠直接提示文本
• size('small' | 'medium' | 'large'): gateway size / 网关尺寸
• color(rgb): gateway color, for example 0x55AAFF / 网关颜色
• hidePearlInCreativeTab(): hide this pearl from creative enumeration / 在创造栏隐藏珍珠
• showPearlInCreativeTab(boolean): control creative visibility / 控制创造栏可见性

Waves and entities / 波次与实体

Use addWave for each wave. Wave indexes exposed by events start at zero.

每个波次使用一次 addWave。事件暴露的波次索引从 0 开始。

// 添加一波实体，并单独修改僵尸属性
builder.addWave(wave => {
  wave.addEntity('minecraft:zombie', 3).modify(entity => {
    entity.addAttribute('minecraft:generic.max_health', 10)
    entity.addEffect('minecraft:strength', 0)
    entity.finalizeSpawn(false)
  })
  wave.maxTime(1200)
  wave.setupTime(60)
  wave.buildWave()
})

modifyAllWaves applies wave-level modifiers and rewards to every wave, including waves added before and after the call.

modifyAllWaves 会把波次级修饰和奖励应用到全部波次，包括调用前后添加的波次。

// 给全部波次增加发光效果和奖励
builder.modifyAllWaves(wave => {
  wave.addEffect('minecraft:glowing', 0)
  wave.addReward('minecraft:gold_nugget', 2)
})

Entity modifiers / 实体修饰

The same modifier methods are available globally, per wave, and on an individual standard entity where applicable:

以下修饰方法可按实际作用域用于全局、波次或单个标准实体：

• addAttribute(attribute, value[, operation])
• addEffect(effect, amplifier[, chance, ambient, visible])
• addGearSet(gearSetId)
• addModifierJson(json)
• setDescription(text)
• setNbt(snbt) and addNbt(snbt)
• finalizeSpawn(boolean)

Attribute operations are addition, multiply_base, and multiply_total.

属性操作类型为 addition、multiply_base 和 multiply_total。

Rules / 网关规则

Common rule methods include spawnRange, leashRange, allowDiscarding, allowDimChange, playerDamageOnly, removeMobsOnFailure, failOnOutOfBounds, spacing, followRangeBoost, and defaultDropChance.

常用规则包括生成范围、牵引范围、是否允许丢弃/跨维度、是否仅玩家伤害、失败移除实体、越界失败、网关间距、追踪范围增益和默认装备掉落概率。

The 1.21.1 branch additionally exposes requiresNearbyPlayer and lives in the generated typings.

1.21.1 分支还在补全中暴露了 requiresNearbyPlayer 和 lives。

Boss display and textures / Boss 显示与纹理

• bossEventAsBar() and bossEventAsNamePlate() select the display mode.
• bossEventFog(boolean) controls fog.
• entityTexture(path) changes the gateway entity texture.
• bossBarTexture(path) or bossBar(...) configures boss-bar textures and UV regions.

bossEventAsBar() 与 bossEventAsNamePlate() 用于选择 Boss 条或名牌模式；bossEventFog 控制迷雾；entityTexture 和 bossBar 系列方法用于自定义渲染资源。

Endless gateway, 1.21.1 / 无尽网关，仅 1.21.1

The first added wave becomes the Endless base wave. Additional progression rules are added with addEndlessModifier and use the native Gateways application-mode JSON.

第一个波次会成为无尽网关的基础波次。后续成长规则使用 addEndlessModifier，其中应用模式采用 Gateways 原生 JSON。

// 1.21.1 无尽网关示例
Gateway.endlessBuilder('kubejs:endless_test')
  .name('Endless Test')
  .size('medium')
  .addWave(wave => {
    wave.addEntity('minecraft:zombie', 3)
    wave.maxTime(800)
    wave.setupTime(100)
    wave.buildWave()
  })
  .addEndlessModifier(modifier => {
    modifier.applicationModeJson('{"type":"gateways:after_every_n_waves","waves":3,"max":10}')
    modifier.addEntityJson('{"type":"gateways:standard","entity":"minecraft:zombie","count":1}')
    modifier.maxTimeDelta(-20)
    modifier.buildModifier()
  })
  .register()