查看“JSON模组教程-行星、区块、生成器、环境方块”的源代码

<span id="行星区块生成器环境方块"></span>
= 行星、区块、生成器、环境方块 =

这一节负责“战役与世界”的部分：行星、区块、天气与环境方块。JSON 能做的事情不少，但行星生成器和复杂规则仍建议以原版为参考，尤其是跨行星玩法与地图生成逻辑。

<span id="行星planet"></span>
== 行星（Planet） ==

行星文件位于 <code>content/planets</code>。行星负责定义“战役大地图”的形态与规则入口。基础字段包括 <code>parent</code>（父天体）、<code>radius</code>（行星半径）、<code>orbitTime</code>/<code>rotateTime</code>（公转/自转周期）、<code>atmosphereColor</code>/<code>lightColor</code>（大气与光照颜色）以及 <code>defaultEnv</code>（默认环境标志）。其中 <code>defaultEnv</code> 影响区块默认环境，例如是否允许氧气、是否启用孢子环境等。

除了视觉参数，行星还有一些影响战役体验的规则字段。<code>startSector</code> 可以指定玩家初始的区块编号；<code>launchCapacityMultiplier</code> 会影响发射时核心携带物资上限；<code>allowLaunchSchematics</code> 和 <code>allowLaunchLoadout</code> 决定玩家是否可以选择发射蓝图与携带物品。它们不会改变地图生成，但会显著影响“进入战役时的节奏”。

行星还决定“默认环境”。<code>defaultEnv</code> 是一组环境标记，会影响氧气、孢子、地面油水等规则是否启用；<code>defaultAttributes</code> 则提供地形属性的基线值。视觉层面上，<code>hasAtmosphere</code> 与 <code>updateLighting</code> 控制是否有大气与昼夜变化，<code>atmosphereRadIn/Out</code> 决定大气层厚度。玩法层面上，<code>clearSectorOnLose</code>、<code>allowSectorInvasion</code>、<code>enemyInfiniteItems</code> 等字段会改变战役难度与节奏，这些都属于“行星级规则”，比单独区块的参数更“宏观”。

需要注意的是，JSON 里目前只会把 <code>generator</code> 反序列化成 <code>AsteroidGenerator</code>。写 <code>SerpuloPlanetGenerator</code> 或 <code>ErekirPlanetGenerator</code> 并不会生效。如果你想复用“塞普罗”或“埃里克尔”的生成器，需要用 Java 或 JavaScript 接管生成器字段。

“饱和火力 3.3.0”就是用脚本来解决生成器限制的。它在 <code>scripts/planets/泰伯利亚.js</code> 中手动创建行星并指定生成器，例如：

<pre>const TBLY = new Planet("泰伯利亚", Planets.sun, 1, 3.3);
TBLY.generator = extend(SerpuloPlanetGenerator, {
    getDefaultLoadout() {
        return Schematics.readBase64("bXNjaAF4nA3JMQ6AIBAAwQXFRr9i4XuMBR5XkCAYkP9LphwcbmLO/lHMwRq0SY3vF0sGluRvTQ17XoZNStU9d0na20gDduAHAc0Org==");
    }
});</pre>
这个片段说明了“行星生成器只能靠脚本”这一点：JSON 负责静态字段，生成器与规则则由 JS 或 Java 接管。

'''文件：content/planets/tutorial-planet.json'''

<pre>{
    "name": "示例行星",
    "parent": "sun",
    "radius": 1,
    "orbitTime": 60,
    "rotateTime": 30,
    "atmosphereColor": "7db6ff",
    "lightColor": "ffd37f"
}
</pre>
这个例子只设置了最基本的轨道与颜色参数，适合快速验证行星是否能被正确加载。

== 行星与科技树关系 ==

行星不仅是“背景”，还决定战役科技树的展示与解锁方式。<code>techTree</code> 与 <code>autoAssignPlanet</code> 让原版内容在不同星球下有不同的解锁顺序。你在 JSON 里新增的方块或单位，如果没有明确指定研究位置，可能会跟随默认行星显示，导致玩家在不合适的阶段就能解锁。解决办法要么是在内容上设置合适的 <code>research</code>，要么在行星层面控制哪些内容在该星球可用。

还有一些与发射相关的字段，例如 <code>allowLaunchSchematics</code> 和 <code>allowLaunchLoadout</code>，它们决定玩家是否可以带蓝图与物资进入区块。对战役节奏影响很大：允许蓝图会让玩家更快建立基地，禁止蓝图则会强化“开局规划”的重要性。你可以把它当作一种“难度调节器”。

行星的“可见性与入口”也值得关注。<code>visible</code> 与 <code>accessible</code> 决定它是否出现在行星列表中，<code>iconColor</code> 与 <code>launchMusic</code> 影响 UI 体验；<code>defaultCore</code> 会影响发射时默认核心类型，<code>allowCampaignRules</code> 决定玩家能否在行星界面调整规则。这些字段偏 UI 与流程，但对战役体验影响很直接。

<span id="区块sectorpreset"></span>
== 区块（SectorPreset） ==

区块文件位于 <code>content/sectors</code>。每个区块必须指定 <code>sector</code> 编号，<code>planet</code> 可选。区块对应的地图文件必须放在 <code>maps/&lt;name&gt;.msav</code>，文件名要和 JSON 文件名一致，否则区块不会生成地图。原版的“零号地区”“冰冻森林”“盐碱荒滩”等都是 <code>SectorPreset</code> 的实例。

<code>SectorPreset</code> 的常见字段包括 <code>difficulty</code>（难度 0-10）、<code>captureWave</code>（达到多少波算占领）、<code>startWaveTimeMultiplier</code>（开局波次时间倍率）、<code>addStartingItems</code>（是否提供初始物资）、<code>noLighting</code>（禁用光照）、<code>requireUnlock</code>（是否需要解锁才能登陆）、<code>isLastSector</code>（是否为最终区块）、<code>attackAfterWaves</code>（波次结束后进入攻击模式）。这些字段大多是“规则开关”，不会影响地图本身，但会影响玩家进入后的玩法节奏。

如果你希望某个区块“独立于行星规则”，可以用 <code>overrideLaunchDefaults</code> 并在区块里单独设定 <code>allowLaunchSchematics</code> 与 <code>allowLaunchLoadout</code>。<code>showHidden</code> 控制隐藏区块是否显示名字与图标，适合做彩蛋或剧情节点。<code>requireUnlock</code> 与 <code>shieldSectors</code>（在 JS/Java 中常用）用于限制登陆顺序，避免玩家过早进入高难区块。区块本身无法写复杂 <code>rules</code>，但你可以在 JS/Java 里通过 <code>rules</code> 回调做深度定制。

'''文件：content/sectors/tutorial-sector.json'''

<pre>{
    "name": "示例区块",
    "planet": "serpulo",
    "sector": 15
}
</pre>
如果你希望写复杂的波次、敌人行为或特殊胜负条件，通常需要地图脚本或 Java/JS 来实现，JSON 只负责基础的入口与一些通用开关。

== 区块与地图文件的配合 ==

区块本身只是“入口”，真正的地图形态由 <code>.msav</code> 文件决定。你可以把区块理解为“战役菜单里的按钮”，而地图文件则是“战场本体”。这也意味着区块的 <code>name</code> 与地图文件名必须严格一致，否则区块会显示但无法进入。若你想做自定义战役，建议先把地图在编辑器里跑通，再回到 JSON 里配置区块参数。

地图文件里还包含波次、规则与脚本等信息，它们对战斗节奏影响比 <code>SectorPreset</code> 更直接。<code>SectorPreset</code> 主要管“能不能进入、入口怎么显示”，而 <code>.msav</code> 才是真正的“关卡设计”。因此当你发现区块规则写了但不生效，优先检查地图本身是否覆盖了规则。

在原版中，很多区块还会设置 <code>requireUnlock</code> 或 <code>showHidden</code>，用于控制玩家在战役地图上看到哪些区域。即使你不写这些字段，默认规则也会生效，但写清楚可以避免“解锁顺序混乱”。

<span id="天气weather"></span>
== 天气（Weather） ==

天气文件位于 <code>content/weathers</code>。<code>Weather</code> 的核心字段包括 <code>duration</code>（持续时间，单位为刻）、<code>opacityMultiplier</code>（覆盖层不透明度）、<code>sound</code>/<code>soundVol</code>（音效与音量）、<code>status</code>/<code>statusDuration</code>（施加的状态与持续时间）以及 <code>statusAir</code>/<code>statusGround</code>（作用对象）。这些字段决定天气的“强度与范围”。

不同天气子类会有自己的表现参数，例如 <code>RainWeather</code> 关注雨线速度、密度与颜色，<code>ParticleWeather</code> 会关心粒子大小与飘动。大多数情况下，你可以先复刻原版天气，再逐步替换颜色与状态，以保证效果不会过强或过于杂乱。

<span id="模组示例饱和火力-3.3.0-的天气"></span>
== 模组示例：饱和火力 3.3.0 的天气 ==

“电离层异常”是一个 <code>ParticleWeather</code>，它把 <code>statusGround</code> 设为 <code>false</code>，表示只影响空中单位，同时通过 <code>sound</code> 与 <code>soundVol</code> 强化氛围感：

<pre>{
    "name": "电离层异常",
    "type": "ParticleWeather",
    "particleRegion": "circle-small",
    "color": "c0ecff",
    "density": 5000,
    "statusGround": false,
    "sound": "shootArc",
    "soundVol": 4,
    "statusDuration": 3,
    "status": "unmoving"
}</pre>
“腐蚀性尘降风”则展示了 <code>attrs</code> 对地形属性的影响，它通过削弱孢子属性来改变生产环境，同时施加状态：

<pre>{
    "name": "腐蚀性尘降风",
    "type": "ParticleWeather",
    "attrs": {"spores": -0.5},
    "color": "a0b46e",
    "density": 3000,
    "opacityMultiplier": 0.4,
    "statusDuration": 10,
    "status": "corroded"
}</pre>
这两个例子分别强调了“作用对象”和“属性联动”，也说明天气不仅是视觉特效，更是战役节奏的控制器。

== 天气与状态的联动 ==

天气的 <code>status</code> 与 <code>statusDuration</code> 会周期性施加在单位上，且可以区分空中与地面（<code>statusAir</code>/<code>statusGround</code>）。这会导致某些单位“天然吃亏”，例如纯地面单位在持续减速天气里会明显受限，而飞行单位可能几乎不受影响。你在设计天气时需要考虑这一点，否则战役的难度会出现“对某类单位极不友好”的偏差。

天气的 <code>attrs</code> 还可以影响地形属性，例如降低或增加某些属性值，从而间接影响生产方块的效率。虽然这类设计较少见，但在特殊关卡中很有表现力。

另外，<code>opacityMultiplier</code> 会影响覆盖层的可见度，数值太高会让地图过暗、视线压抑；<code>duration</code> 则控制天气维持时间，过短会显得“像闪一下”，过长又会让玩家觉得被强制压制。天气是“节奏控制器”，不是单纯装饰，建议配合波次设计一起调。

<span id="环境方块environment"></span>
== 环境方块（Environment） ==

环境方块通常位于 <code>content/blocks/environment</code>，常见类型包括 <code>Floor</code>（地板）、<code>OreBlock</code>（矿物）、<code>StaticWall</code>（环境墙）和 <code>Prop</code>（装饰物）。它们的贴图必须放在 <code>sprites/blocks/environment/</code>，否则会触发 <code>Wrong Texture Folder</code>。

<code>Floor</code> 的字段很丰富。<code>speedMultiplier</code> 与 <code>dragMultiplier</code> 会改变单位移动手感，<code>damageTaken</code> 会造成持续伤害，<code>status</code> 与 <code>statusDuration</code> 能让地板“踩上去就中状态”，<code>liquidDrop</code> 与 <code>liquidMultiplier</code> 决定泵类方块的抽取效率。若地板是液体，还会用到 <code>isLiquid</code> 与 <code>overlayAlpha</code> 控制显示效果。<code>variants</code> 决定贴图变体数量，<code>oreScale</code> 与 <code>oreThreshold</code> 则用于矿物的地图生成参数。

除了数值字段，<code>Floor</code> 还有不少“观感型”参数。<code>walkEffect</code> 与 <code>walkSound</code> 可以塑造“踩上去的反馈”，<code>walkSoundPitchMin/Max</code> 用于随机音高避免机械重复；<code>drownTime</code> 会影响单位在深液体中的生存；<code>blendGroup</code> 影响与其他地板的边缘过渡；<code>supportsOverlay</code> 与 <code>needsSurface</code> 则决定能否叠加覆盖层或放置特殊装饰。这些字段不一定提高强度，但会让地形更“有存在感”。

<code>OreBlock</code> 的核心字段是 <code>itemDrop</code> 与 <code>variants</code>，前者决定掉落物，后者决定贴图变体数量。若你需要控制矿物生成密度，通常会调整 <code>oreScale</code> 与 <code>oreThreshold</code>，并结合 <code>oreDefault</code> 来决定是否参与地图默认生成。<code>StaticWall</code> 更关注 <code>health</code>、<code>variants</code> 与破坏音效；<code>Prop</code> 则多用于纯装饰。

'''文件：content/blocks/environment/tutorial-ore.json'''

<pre>{
    "type": "OreBlock",
    "name": "示例矿",
    "itemDrop": "copper",
    "variants": 3
}
</pre>
<span id="模组示例饱和火力-3.3.0-的环境方块"></span>
== 模组示例：饱和火力 3.3.0 的环境方块 ==

“铬”矿展示了 <code>oreDefault</code>、<code>oreScale</code> 与 <code>oreThreshold</code> 的组合用法，同时用 <code>playerUnmineable</code> 禁止玩家手动开采，避免早期获取高阶资源：

<pre>{
    "type": "OreBlock",
    "name": "铬",
    "itemDrop": "铬",
    "playerUnmineable": true,
    "oreDefault": true,
    "oreThreshold": 0.9,
    "oreScale": 20
}</pre>
“雪沙”则是一个带属性的地板，它在 <code>attributes</code> 里增加油与水属性，让这类地形在生产效率上更有意义：

<pre>{
    "type": "floor",
    "name": "雪沙",
    "itemDrop": "sand",
    "speedMultiplier": 0.95,
    "attributes": {"oil": 0.5, "water": 0.2},
    "variants": 2,
    "playerUnmineable": true
}</pre>
这两个例子说明了“环境方块并非只有装饰用途”，它们也可以直接参与生产与战役节奏的塑造。

如果你希望玩家“走上去就能感觉到地形差异”，可以配合 <code>walkEffect</code> 或 <code>walkSound</code>，让移动反馈成为环境设计的一部分。

== 环境方块与地图生成 ==

环境方块的 <code>oreScale</code> 与 <code>oreThreshold</code> 并不会直接“生成矿物”，它们只是告诉地图生成器在什么情况下使用该矿。真正的生成逻辑由生成器决定，因此你在 JSON 里设置这些字段之后，只有在对应生成器中引用了该矿，地图里才会出现它。这也是为什么很多自定义矿物“写了却不生成”的原因。

<code>oreDefault</code> 是一个很重要的开关：它决定该矿物是否参与“默认矿物池”。如果你希望它只出现在特定地图，<code>oreDefault</code> 就应该设为 <code>false</code>，然后在地图脚本或生成器里手动引用；否则它可能会在所有地图里随机出现，破坏战役节奏。类似的还有 <code>wallOre</code>，它允许矿物生成在墙体上，常用于“墙矿”或特殊地形，但玩家视角会更难察觉，需要配合明显的贴图。

对于液体地面，<code>liquidDrop</code> 与 <code>liquidMultiplier</code> 会影响泵类方块的效率，也会影响“水洼”扩散。若你希望某种液体地面更有威胁，可以提高 <code>damageTaken</code> 或直接设置 <code>status</code>。这些字段结合起来，能让地面从“背景”变成“机制”。

<span id="生成器generator"></span>
== 生成器（Generator） ==

行星生成器决定地形、矿物与噪声分布。原版中常见的生成器有 <code>SerpuloPlanetGenerator</code>、<code>ErekirPlanetGenerator</code>、<code>AsteroidGenerator</code>，但 JSON 目前只能反序列化出 <code>AsteroidGenerator</code>。如果你想在 JSON 里“复用原版生成器”，需要用 JS/Java 接管生成器字段，再回到 JSON 配置行星或区块。

区块的生成器则是 <code>FileMapGenerator</code>，它直接读取 <code>.msav</code> 地图文件。因此当你使用自定义区块时，真正影响地形与矿物的是地图文件本身，而不是 JSON 字段。理解这点有助于避免“在 JSON 里调矿物密度却不生效”的困惑。

== 小结 ==

行星和区块决定战役的“大地图”，天气与环境方块决定“战场体验”。当你想做更复杂的生成逻辑时，优先参照 Java 教程，再回到 JSON 实现，会少走很多弯路。

如果目标已经超出 JSON 能力，比如自定义生成器或复杂规则，就该直接转向脚本或 Java。

合理使用天气和环境，还能把战役“讲得更像一个世界”。