Custom Biome
概述
Custom Biome 让你可以在 TypeWriter 网页面板中创建属于自己的生物群系：草地、树叶、水、天空和雾的颜色，云和太阳的设置，以及温度和降水。新的生物群系以一个原版基础生物群系为起点，因此生物生成、地物和其他属性都会被继承，你只需覆盖想要修改的部分。
生物群系有两种使用方式。你可以将它绘制到世界中，范围可以是一个方块半径、一个 WorldEdit 选区或一个已捕获的区域，之后还能通过快照恢复原来的生物群系。或者，你也可以通过按玩家的覆盖层（overlay）仅向某个玩家或某个 audience 显示它：世界本身不会改变，其他人也看不到变化。被腐化的森林只在某个任务期间出现，就是这样实现的。
功能
- 生物群系定义 — 颜色（草地、树叶、干燥树叶、水、天空、雾、水下雾、云、天空光、日出/日落）、雾和云的距离、太阳、月亮和星星设置、温度和降水。
- 预设 — 在多个生物群系之间共用一套配色，只覆盖有差异的部分。
- 实时注册 — 在可能的情况下，生物群系会被注入服务器的注册表，并写入生成的数据包，以便在重启后保留。
- 世界绘制 — 在玩家周围或某个区域上应用生物群系，并可选择保留快照以便撤销。
- 按玩家的覆盖层 — 通过动作、audience 或过场动画，向单个玩家或某个 audience 显示生物群系。
- 进入和离开事件 — 当玩家进入或离开某个生物群系时触发条目。
- 发现记录 — 记住每位玩家到访过的生物群系，并可在 facts 和任务中使用。
- Facts、变量和占位符 — 读取当前生物群系、其属性以及已发现数量。
- 管理员命令 — 列出生物群系、查看玩家所在位置的生物群系、绘制、刷新以及捕获区域。
- 支持 Folia — 写入操作会在拥有对应区块的区域线程上调度。
安装
- 安装 PacketEvents。覆盖层和区块刷新都通过它发送；没有它，覆盖层会被禁用。
- 在网页面板的 Extensions 选项卡中安装 TypeWriter 的 Quest 扩展（目标 objective 会用到它）。
- 可选：安装 WorldEdit 或 FastAsyncWorldEdit，以便绘制你在游戏中选取的选区。
- 可选：安装 PlaceholderAPI 以使用下面的占位符。
- 将 Custom Biome 的 JAR 放入
plugins/Typewriter/extensions/，然后重启服务器。
生物群系定义会写入世界 datapacks 文件夹中名为 typewriter_custom_biomes 的数据包。
源码中，这些视觉属性（雾的距离、云的高度、太阳、月亮和星星设置）标注为适用于 Minecraft 1.21.11 及更高版本。在更旧的版本上，只有颜色和气候生效。
快速上手
创建一片紫色森林，并在任务的某个步骤向玩家显示：
- 在 TypeWriter 网页面板中，打开一个 manifest 页面，添加一个 Custom Biome Definition 条目。
- 设置
biomeId（小写，使用下划线，例如corrupted_forest），并保持namespace为typewriter。将baseBiome设为minecraft:forest。 - 以十六进制填写你想修改的颜色，例如
grassColor为#6a3d9a，foliageColor为#4b2a73。留空的字段继承自基础生物群系。 - 发布，然后在游戏中运行
/tw biome list检查生物群系是否已生效。如果显示为等待重启，请重启服务器。 - 在 manifest 页面上添加一个 Biome Overlay Audience，在
biome中选择该定义，并把它放在与你的任务步骤相匹配的 audience 之下。玩家在该 audience 中时会看到该生物群系，离开后真实的生物群系会恢复（restoreOnExit）。 - 若要将其限制在某个区域内，请设置
cornerA和cornerB，或者在游戏中用 WorldEdit 选好选区，然后运行/tw biome region <entry>来填写这两个角点。
若要修改世界本身，请在动作序列中使用 Apply Biome 或 Paint Biome Region。如果想用 Restore Biome 来撤销绘制，请为绘制设置一个 snapshotId。
为一族共用同一套天空和雾的生物群系创建一个 Custom Biome Preset，并在每个定义的 preset 中选择它。定义上设置的值优先于预设，预设优先于基础生物群系。
工作原理
绘制会把生物群系写入世界数据，因此会影响所有玩家，并在重启后保留。覆盖层只会发送到玩家的客户端：不会保存任何内容，移除它就会恢复真实的生物群系。当多个覆盖层覆盖同一个区块时，显示最后应用的那个，移除它则会显露出前一个。
Facts、变量和占位符默认读取玩家看到的生物群系（PLAYER_VIEW，包含覆盖层）。在 facts 和变量上将 source 设为 REAL_WORLD，则会读取世界中真实存在的内容。
配置
运行时数据存储在 plugins/Typewriter/custombiome/ 下：
| 文件夹 | 内容 |
|---|---|
discovery/ | 每位玩家一个 JSON 文件（<uuid>.json），列出他们到访过的生物群系。 |
snapshots/ | 设置了 snapshotId 时，由 Paint Biome Region 记录的生物群系。 |
命令
根命令是 /tw biome，需要 typewriter.biome 权限。每个子命令还需要各自的权限。
| 命令 | 说明 |
|---|---|
/tw biome | 显示命令列表。 |
/tw biome list | 列出自定义生物群系，以及每个是已生效、等待重启还是未注册。 |
/tw biome info [player] | 显示玩家所处的生物群系：名称、ID、是否为自定义、温度、降水以及基础生物群系。 |
/tw biome apply <biome> [radius] | 在你自己或目标玩家周围、按指定的方块半径绘制生物群系。 |
/tw biome refresh [radius] | 为本扩展在玩家附近绘制过的区块重新发送生物群系数据（半径为 1 到 16 个区块）。 |
/tw biome region <entry> | 将你的 WorldEdit 选区复制到某个区域条目的 cornerA 和 cornerB 中，然后发布页面。 |
可编辑文本
/tw biome 命令在游戏中输出的所有内容都是 TypeWriter 的 snippet，因此无需重新构建即可改写、翻译或重新着色。打开 plugins/Typewriter/snippets.yml，找到 content.custombiome 下的键，修改值并运行 /tw reload。扩展在启动时会以默认文本注册其所有 snippet，因此首次启动后它们会出现在该文件中。
文本使用 MiniMessage。文本中的 {name} 会被表中所列的值替换；省略的占位符不会显示，不存在的占位符会原样保留。当命令由玩家执行时，PlaceholderAPI 占位符（%...%）同样会被解析。只有简短回复上的 Typewriter 回复前缀（Typewriter »）来自引擎，不属于这些 snippet；服务器控制台日志保持英文。
Snippet（位于 content.custombiome. 下） | 默认值 | 占位符 |
|---|---|---|
command.list.empty | <yellow>No custom biomes registered.</yellow> | 无 |
command.list.header | <gradient:#00d4ff:#0099ff><b>Custom Biomes ({count})</b></gradient>，前面有一个空行 | {count} |
command.list.strategy | <dark_gray>Strategy: {strategy}</dark_gray>，后面有一个空行 | {strategy} |
command.list.strategy_live | live registry injection (reflection) | 无 |
command.list.strategy_unsupported | unsupported ({reason}) | {reason} （技术性内容，英文） |
command.list.icon_live, icon_waiting, icon_missing | • 为绿色，⚠ 为黄色，✖ 为红色 | 无 |
command.list.status_live, status_waiting, status_missing | 悬停文本： Live in the registry, Written to the datapack — needs a restart, Not registered | 无 |
command.list.entry | 每个生物群系一行，带悬停文本和点击复制 | {icon}, {status}, {name}, {key}, {temperature}, {downfall} |
command.list.temperature, command.list.downfall | T:{value} 和 D:{value}，灰色 | {value} |
command.info.header | Biome Info for {player} | {player} |
command.info.name, id, temperature, downfall, base_biome | Name:, ID:, Temperature:, Downfall:, Base Biome:，后接对应的值 | {value} |
command.info.custom_yes, custom_no | Custom: Yes 和 Custom: No | 无 |
command.help.title | Custom Biome Commands | 无 |
command.help.list, info, apply, refresh, region | 每条命令一行帮助 | 无 |
command.region.no_selection | No WorldEdit selection (or WorldEdit is not installed). | 无 |
command.region.page_not_found | Could not find the page holding '{entry}'. | {entry} |
command.region.write_failed | Could not write the region: {failures} | {failures} （技术性内容，英文） |
command.region.done | Region of {entry} set to {min} → {max} in {world}. | {entry}, {min}, {max} （形如 x, y, z）, {world} |
command.region.publish_hint | Publish the page for it to take effect. | 无 |
command.refresh.none | No painted chunks near {player} to refresh. | {player} |
command.refresh.done | Resent biome data for {chunks} painted chunk(s) to {player}. | {chunks}, {player} |
command.apply.unknown | Unknown biome: {biome} | {biome} |
command.apply.unknown_hint | Use /tw biome list to see available custom biomes. | 无 |
command.apply.nothing | Nothing to paint at that location. | 无 |
command.apply.done | Painting {biome} over {cells} cell(s) across {chunks} chunk(s). | {biome}, {cells}, {chunks} |
placeholder.unknown | unknown | 无 |
/tw biome list 的三个悬停 snippet 位于用单引号括起来的 MiniMessage 参数中，因此不能包含单引号。
对于非自定义的生物群系，%typewriter_temperature%、%typewriter_downfall% 和 Biome Property 变量返回 placeholder.unknown。%typewriter_is_custom% 返回的 true 和 false 保持固定，因为条件会与它们比较。
权限
| 权限 | 授予 |
|---|---|
typewriter.biome | 访问 /tw biome 命令树。 |
typewriter.biome.list | /tw biome list |
typewriter.biome.info | /tw biome info |
typewriter.biome.apply | /tw biome apply |
typewriter.biome.refresh | /tw biome refresh |
typewriter.biome.region | /tw biome region |
占位符
PlaceholderAPI 占位符，由 typewriter expansion 提供。玩家相关的占位符读取的是玩家被显示的生物群系。
| 占位符 | 返回值 |
|---|---|
%typewriter_current% 或 %typewriter_id% | 玩家所处位置的生物群系键，例如 minecraft:plains。 |
%typewriter_name% | 生物群系的可读名称。 |
%typewriter_key% | 仅键的部分。 |
%typewriter_namespace% | 仅命名空间部分。 |
%typewriter_is_custom% | true 或 false。 |
%typewriter_temperature% | 自定义生物群系的温度，否则为 unknown。 |
%typewriter_downfall% | 自定义生物群系的降水，否则为 unknown。 |
%typewriter_base% | 自定义生物群系的基础生物群系，或生物群系键本身。 |
%typewriter_count% | 已注册的自定义生物群系数量。 |
%typewriter_list% | 自定义生物群系的显示名称，以逗号分隔。 |
%typewriter_discovered_count% | 玩家到访过的生物群系数量。 |
%typewriter_discovered_list% | 玩家到访过的生物群系的键。 |
该扩展响应上面这些不带前缀的名称（%typewriter_current%、%typewriter_count% 等）。其源码中的注释提到了 custombiome_ 前缀，但代码实际上只匹配不带前缀的名称。
条目
20 个条目，由扩展源码生成。
动作5
- Apply Biome ActionApply a biome to a location with optional radius
- Paint Biome Region ActionPaint a biome over a region, with an optional snapshot to undo it later
- Player Biome Overlay ActionShow a biome to a single player without changing the world
- Refresh Biome Chunks ActionRefresh biome data for chunks around the player
- Restore Biome ActionRestore biomes previously recorded by a paint snapshot
事件2
- Enter Biome EventTriggered when a player enters a biome
- Leave Biome EventTriggered when a player leaves a biome
目标1
- Explore Biome ObjectiveObjective completed by discovering one or more biomes
事实4
- Biome Discovery FactHow many biomes the player has discovered, or whether specific ones were found
- Custom Biome Count FactReturns the number of registered custom biomes
- Is in Custom Biome FactReturns 1 if player is in a custom biome, 0 otherwise
- Player Biome FactExpose the player's current biome as a fact value
受众2
- Biome Overlay AudienceShow a biome to the audience without changing the world
- Biome Region AudienceKeep the players standing inside a region defined by two captured corners
过场动画1
- Biome Transition CinematicChange the biome a player sees during a cinematic
变量3
- Biome Property VariableReturns a property of the player's current biome
- Current Biome VariableReturns the player's current biome name
- Custom Biome List VariableReturns a list of registered custom biomes
清单2
- Custom Biome DefinitionDefine a custom biome with colors and climate settings
- Custom Biome PresetA reusable set of colors and visual attributes shared by several biomes
故障排查
/tw biome list 显示警告标志和“需要重启”。 服务器无法将该生物群系加入其实时注册表，因此它只存在于生成的数据包中。请重启服务器。原因只会在控制台中写出一次。
动作或事件找不到我的生物群系。 生物群系标识符格式为 namespace:id，例如 typewriter:corrupted_forest。请在 /tw biome list 中查看确切的键。未知的标识符会作为警告记录（unknown biome '…'），且该动作不会执行任何操作。
玩家始终看不到覆盖层。 覆盖层需要 PacketEvents：否则控制台会显示 PacketEvents unavailable: per-player biome overlays are disabled。同时检查玩家是否在该 audience 中，是否配置了生物群系（自定义定义或 vanillaBiome），以及对于区域，两个角点是否都位于已加载的世界中。
Paint Biome Region 没有任何效果。 当 region 设为 WORLDEDIT_SELECTION 时，触发的玩家需要有 WorldEdit 选区，并且必须安装了 WorldEdit；控制台会记录 has no WorldEdit selection。否则请使用 RADIUS_AROUND_PLAYER。
Restore Biome 提示快照不存在。 只有当绘制动作设置了 snapshotId 时才会记录快照，且恢复时必须使用相同的名称。如果开启了 consume，快照会在恢复后被删除。