Custom Biome
Overview
Custom Biome lets you create biomes of your own from the TypeWriter web panel: grass, foliage, water, sky and fog colours, cloud and sun settings, temperature and downfall. A new biome starts from a vanilla base biome, so mob spawns, features and other properties are inherited, and you only override what you want to change.
A biome can be used in two ways. You can paint it into the world, for a block radius, a WorldEdit selection or a captured region, and put the old biomes back later from a snapshot. Or you can show it to one player or an audience only, with a per-player overlay: the world is untouched and nobody else sees the change. This is how a corrupted forest can appear only during a quest.
Features
- Biome definitions — colours (grass, foliage, dry foliage, water, sky, fog, water fog, cloud, sky light, sunrise/sunset), fog and cloud distances, sun, moon and star settings, temperature and downfall.
- Presets — share a palette between several biomes and override only what differs.
- Live registration — biomes are injected into the server's registry when possible, and written to a generated datapack so they survive restarts.
- World painting — apply a biome around a player or over a region, with an optional snapshot to undo it.
- Per-player overlays — show a biome to one player or an audience, through an action, an audience or a cinematic.
- Enter and leave events — trigger entries when a player crosses into or out of a biome.
- Discovery — remember which biomes each player has visited, and use it in facts and quests.
- Facts, variables and placeholders — read the current biome, its properties and the discovery count.
- Operator commands — list biomes, inspect the biome under a player, paint, refresh and capture a region.
- Folia ready — writes are scheduled on the region that owns each chunk.
Installation
- Install PacketEvents. Overlays and chunk refreshes are sent with it; without it, overlays are disabled.
- Install the Quest extension of TypeWriter from the Extensions tab of the web panel (the objective uses it).
- Optional: install WorldEdit or FastAsyncWorldEdit to paint the selection you made in game.
- Optional: install PlaceholderAPI to use the placeholders below.
- Put the Custom Biome JAR in
plugins/Typewriter/extensions/and restart the server.
Biome definitions are written to a datapack named typewriter_custom_biomes in the datapacks folder of the world.
The visual attributes (fog distances, cloud height, sun, moon and star settings) are labelled for Minecraft 1.21.11 and later in the source. On older versions only the colours and climate apply.
Getting started
Create a purple forest and show it to players at a quest step:
- In the TypeWriter web panel, open a manifest page and add a Custom Biome Definition entry.
- Set
biomeId(lowercase, underscores, for examplecorrupted_forest) and keepnamespaceastypewriter. SetbaseBiometominecraft:forest. - Fill the colours you want to change in hex, for example
grassColor#6a3d9aandfoliageColor#4b2a73. Empty fields inherit from the base biome. - Publish, then run
/tw biome listin game to check the biome is live. If it shows as waiting for a restart, restart the server. - On a manifest page, add a Biome Overlay Audience, pick the definition in
biome, and place it under an audience that matches your quest step. The player sees the biome while in the audience, and the real biome returns when they leave (restoreOnExit). - To limit it to a zone, set
cornerAandcornerB, or stand in game with a WorldEdit selection and run/tw biome region <entry>to fill the corners.
To change the world itself, use Apply Biome or Paint Biome Region in an action sequence. Give the paint a snapshotId if you want Restore Biome to undo it.
Create a Custom Biome Preset for a family of biomes that share the same sky and fog, and select it in preset of each definition. Values set on the definition win over the preset, and the preset wins over the base biome.
How it works
Painting writes the biome into the world data, so it affects every player and survives a restart. An overlay is only sent to the player's client: nothing is saved, and removing it gives the real biome back. When several overlays cover the same chunk, the one applied last is shown, and removing it reveals the previous one.
Facts, variables and placeholders read the biome the player sees by default (PLAYER_VIEW, overlays included). Set source to REAL_WORLD on facts and variables to read what the world really contains.
Configuration
Runtime data is stored under plugins/Typewriter/custombiome/:
| Folder | Content |
|---|---|
discovery/ | One JSON file per player (<uuid>.json) listing the biomes they have visited. |
snapshots/ | Biomes recorded by Paint Biome Region when snapshotId is set. |
Commands
The root command is /tw biome, which needs typewriter.biome. Each sub-command also needs its own permission.
| Command | Description |
|---|---|
/tw biome | Show the list of commands. |
/tw biome list | List the custom biomes and whether each is live, waiting for a restart, or not registered. |
/tw biome info [player] | Show the biome a player is standing in: name, ID, whether it is custom, temperature, downfall and base biome. |
/tw biome apply <biome> [radius] | Paint a biome around yourself or a target player, within a radius in blocks. |
/tw biome refresh [radius] | Resend biome data (radius of 1 to 16 chunks) for the chunks this extension painted near the player. |
/tw biome region <entry> | Copy your WorldEdit selection into cornerA and cornerB of a region entry, then publish the page. |
Editable texts
Everything the /tw biome commands print in game is a TypeWriter snippet, so you can reword, translate or recolour it without rebuilding anything. Open plugins/Typewriter/snippets.yml, find the key under content.custombiome, change the value and run /tw reload. The extension registers all its snippets with their default text when it starts, so they appear in the file after the first start.
Texts are MiniMessage. A {name} in a text is replaced by the value named in the table; a placeholder you leave out is simply not shown, and one that does not exist stays as written. PlaceholderAPI placeholders (%...%) are also read when the command is run by a player. Only the Typewriter reply prefix on the short replies (Typewriter ») comes from the engine and is not part of these snippets, and the server console log stays in English.
Snippet (under content.custombiome.) | Default | Placeholders |
|---|---|---|
command.list.empty | <yellow>No custom biomes registered.</yellow> | none |
command.list.header | <gradient:#00d4ff:#0099ff><b>Custom Biomes ({count})</b></gradient>, with a blank line before | {count} |
command.list.strategy | <dark_gray>Strategy: {strategy}</dark_gray>, with a blank line after | {strategy} |
command.list.strategy_live | live registry injection (reflection) | none |
command.list.strategy_unsupported | unsupported ({reason}) | {reason} (technical, in English) |
command.list.icon_live, icon_waiting, icon_missing | • in green, ⚠ in yellow, ✖ in red | none |
command.list.status_live, status_waiting, status_missing | hover texts: Live in the registry, Written to the datapack — needs a restart, Not registered | none |
command.list.entry | one line per biome, with hover text and click-to-copy | {icon}, {status}, {name}, {key}, {temperature}, {downfall} |
command.list.temperature, command.list.downfall | T:{value} and D:{value} in gray | {value} |
command.info.header | Biome Info for {player} | {player} |
command.info.name, id, temperature, downfall, base_biome | Name:, ID:, Temperature:, Downfall:, Base Biome: followed by the value | {value} |
command.info.custom_yes, custom_no | Custom: Yes and Custom: No | none |
command.help.title | Custom Biome Commands | none |
command.help.list, info, apply, refresh, region | one help line per command | none |
command.region.no_selection | No WorldEdit selection (or WorldEdit is not installed). | none |
command.region.page_not_found | Could not find the page holding '{entry}'. | {entry} |
command.region.write_failed | Could not write the region: {failures} | {failures} (technical, in English) |
command.region.done | Region of {entry} set to {min} → {max} in {world}. | {entry}, {min}, {max} (as x, y, z), {world} |
command.region.publish_hint | Publish the page for it to take effect. | none |
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. | none |
command.apply.nothing | Nothing to paint at that location. | none |
command.apply.done | Painting {biome} over {cells} cell(s) across {chunks} chunk(s). | {biome}, {cells}, {chunks} |
placeholder.unknown | unknown | none |
The three hover snippets of /tw biome list sit inside a single-quoted MiniMessage argument, so they must not contain a single quote.
placeholder.unknown is what %typewriter_temperature%, %typewriter_downfall% and the Biome Property variable return for a biome that is not a custom one. The true and false returned by %typewriter_is_custom% stay fixed, because conditions compare against them.
Permissions
| Permission | Grants |
|---|---|
typewriter.biome | Access to the /tw biome command tree. |
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 |
Placeholders
PlaceholderAPI placeholders, served by the typewriter expansion. Player placeholders read the biome the player is shown.
| Placeholder | Returns |
|---|---|
%typewriter_current% or %typewriter_id% | Biome key under the player, for example minecraft:plains. |
%typewriter_name% | Readable name of the biome. |
%typewriter_key% | Key part only. |
%typewriter_namespace% | Namespace part only. |
%typewriter_is_custom% | true or false. |
%typewriter_temperature% | Temperature of a custom biome, unknown otherwise. |
%typewriter_downfall% | Downfall of a custom biome, unknown otherwise. |
%typewriter_base% | Base biome of a custom biome, or the biome key itself. |
%typewriter_count% | Number of registered custom biomes. |
%typewriter_list% | Display names of the custom biomes, separated by commas. |
%typewriter_discovered_count% | Number of biomes the player has visited. |
%typewriter_discovered_list% | Keys of the biomes the player has visited. |
The extension answers on the bare names above (%typewriter_current%, %typewriter_count%, and so on). The comment in its source mentions a custombiome_ prefix, but the code only matches the bare names.
Entries
20 entries, generated from the extension source.
Actions5
- 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
Events2
- Enter Biome EventTriggered when a player enters a biome
- Leave Biome EventTriggered when a player leaves a biome
Objectives1
- Explore Biome ObjectiveObjective completed by discovering one or more biomes
Facts4
- 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
Audiences2
- 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
Cinematics1
- Biome Transition CinematicChange the biome a player sees during a cinematic
Variables3
- 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
Manifests2
- 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
Troubleshooting
/tw biome list shows a warning sign and "needs a restart". The server could not add the biome to its live registry, so it only exists in the generated datapack. Restart the server. The reason is written once to the console.
My biome is not found by an action or an event. Biome identifiers are namespace:id, for example typewriter:corrupted_forest. Check /tw biome list for the exact key. An unknown identifier is logged as a warning (unknown biome '…') and the action does nothing.
A player never sees the overlay. Overlays need PacketEvents: the console shows PacketEvents unavailable: per-player biome overlays are disabled otherwise. Also check that the player is in the audience, that a biome is configured (a custom definition or vanillaBiome), and, for a region, that both corners are in a loaded world.
Paint Biome Region does nothing. With region set to WORLDEDIT_SELECTION, the triggering player needs a WorldEdit selection and WorldEdit must be installed; the console logs has no WorldEdit selection. Use RADIUS_AROUND_PLAYER otherwise.
Restore Biome says the snapshot does not exist. Snapshots are only recorded when the paint action has a snapshotId, and the restore must use the same name. If consume is on, the snapshot is deleted after a restore.