Repository navigation
Home
Thanks for using Polytone. If you enjoy this mod, please remember to add Polytone to your pack's Optional Dependency section or use the provided banner.
Polytone is a Forge, Fabric and NeoForge client-side customization mod that lets you customize many additional game visuals through Resource Packs.
Important
🐚 The easiest way to make a Polytone pack is Nautilus Studio
A visual editor that lets you create any Resource Pack or Data Pack file.
Get Nautilus Studio here, strongly recommended for both beginners and experienced pack makers.
Tip
The mod can seem complex, but this wiki is in-depth and walks you through every aspect of it. If you have any questions, feel free to contact me on Discord.
Important
All the wiki pages are on the SIDEBAR to the right. Don't forget to also click show more pages at the bottom of it.
Polytone lets you tweak many visual aspects of the game. It does this by expanding the game's Resource Pack system.
The mod not only offers backwards compatibility with old concepts originating from McPatcher (such as Colormaps, Lightmaps and Custom Colors), but also adds a bunch of its own, like Biome Variant Textures, Biome Properties, Block Sounds, Gui Modifiers, Particle Modifiers, file conditions and more.
Having trouble following this wiki? Download the mod's example pack here.
The example pack only contains examples of a few concepts; the wiki is far richer in information, but it should give you an idea of how things can be set up.
Tip
When in doubt, take a look at the Existing Packs section on the CurseForge page to see how other people have done things.
The mod works by having Modifier objects defined in .json files. Each Modifier acts on, or is applied to, an existing game object such as a Block, Item, Particle, Biome, Dimension and so on. There can be more than one per game object.
Each Modifier is covered in detail on its own dedicated wiki page.
Before diving into any single feature, read Shared Concepts. Almost every Polytone file is built from the same pieces, and that page covers them once so the feature pages don't have to repeat them:
- Identifiers: how you name things
- Targeting: how a file picks the block/biome/item it affects
- Conditions: loading only with certain mods, configs or versions
- Priority: who wins when two files overlap
- Modularity: writing a snippet inline vs. reusing it
- Debugging a pack: a checklist for when nothing shows up
Important
Targeting, conditions and priority are used on every feature page. If a feature page tells you to "target" something, this is what it means.
Working with JSON and resource packs (click me)
The mod makes extensive use of JSON files. This is what the game already uses for its entire data and resource system, for example when adding models or recipes.
If you are not accustomed to datapacks or resource packs, be sure you are using a text editor with JSON syntax highlighting. Some options are:
- VSCode
- Notepad++ (with a JSON syntax plugin)
- Sublime Text
- Atom
JSON syntax is not something exclusive to Minecraft, and it's recommended you get comfortable with it (you can look it up online). For example, two important concepts to have clear are how lists are defined (enclosed by [] brackets) and how objects are defined (anything enclosed by {} brackets).
If you are using Forge or NeoForge, remember that the loader itself has a bunch of model customization of its own, so check out their docs first.
Polytone is Resource Pack based. If you don't know what a resource pack is, or have never made one, it's highly recommended you try making a simple one first. You can read all about them on the Official Minecraft Wiki.
If you don't want to do that, here's a quick reminder:
- Make a folder in the
resourcepacksfolder of your game directory. - Add a
pack.mcmetafile so it's recognized as a pack:
{
"pack": {
"pack_format": 34,
"description": "My new resource pack"
}
}Note
pack_format must match your Minecraft version. The value above is just an example; look up the correct number for your version on the Minecraft Wiki.
- Add an
assetsfolder there. Every resource will live inside it. - Every file and folder name may only contain
a-z 0-9 / _ -characters. No capitals! - In game, load the pack from the resource packs screen. You can change pack content while in-game and reload with F3+T.
See the Debugging a pack checklist on the Shared Concepts page. It walks you through checking whether a file is even being read, whether it's aimed at the right target, and whether another pack is overriding it.
Not familiar with resource packs? Start with the Official Minecraft Wiki, then download and start editing the Polytone Sample Pack.
Use the following chart for the most common things you might want to do with Polytone.
| I Want To Change... | Which Pages | TLDR |
|---|---|---|
| Water Color | Colormaps, Fluid Properties Modifiers, Biome Effect Modifiers | Changing a single biome's color? Use Biome Effect Modifiers. Want a colormap? Add a water.png in polytone/fluid_modifiers. |
| A Block's Colormap | Colormaps, Block Properties Modifiers | Add a colormap .png in polytone/block_modifiers named like your block. |
| A GUI's Visuals | Gui Modifiers | Follow the instructions on the page (Slot Modifiers and Sprites sections). |
| A villager's (or any entity's) menu texture | Gui Modifiers | 1.21.1+. Target the merchant menu and add a condition like global.hasInteracted() && global.lastInteractedEntity.profession() == 'minecraft:cleric', then draw a sprites background. |
| Lightmaps | Lightmaps | Add a texture at polytone/lightmaps/overworld.png. |
| Block Sounds | Block Properties Modifiers, Custom Sound Events | Use a block property JSON to specify a new Sound Type. |
| Particle Color | Custom Colors, Particle Modifiers | Add a single line in colors.json for static colors, or use Particle Modifiers for more control. |
| Fog Color / Sky Color | Biome Effect Modifiers, Dimension Effects Modifiers | Use biome modifiers to change a biome's fog color, or Dimension Effects for a colormap that controls them. |
| Dye / Map Colors | Custom Colors | Add a line such as dye.black = ff00ff00. |
| Make Hotbar bigger | Screen Sprite Modifiers | Follow the example there. |
| Add a new texture to a named item | Custom Item Models | Add a texture and JSON file in the custom_item_models folder. |
| Remove Items from a Creative Tab | Creative Tab Modifiers | Follow the first example there. |
| Add tooltip lines to an item | Item Modifiers | Follow the example there. |
| A texture that changes when it rains | Variant Textures | Add "mode": "weather" to your .mcmeta file. |
| A Block Render Type to Translucent | Block Properties Modifiers | Add a modifier with "render_type": "translucent". |
| Make seasonal textures | Variant Textures | Add an animated texture that uses an expression with the season variable. |
| Turn off parts of my pack with a config button | Polytone Configs | Add a config entries JSON file and use it in your pack.mcmeta. |
| Credit myself and add donation links | Pack Info | Add a polytone section with a title and content component to your pack.mcmeta. |
| Brighten a dark dimension | Dimension Effects Modifiers | Set ambient_light on the dimension. |
| Emit particles from a block | Block Properties Modifiers | Add a particle emitter in the block modifier. |
| Emit particles from an entity | Entity Modifiers | 1.21.11+. Attach an emitter to a model bone. |
| Create a brand-new particle | Custom Particle Types | Define a particle list JSON plus a custom_particles JSON. |
| Tens of thousands of weather or ambience particles without lag | GPU Particles | Spawn like normal particles, simulated and drawn entirely on the GPU. Custom shader hook. |
| Change an item's rarity or name color | Item Modifiers | Set rarity (and tooltips) in an item modifier. |
| Put a cosmetic (worn) model on an item | Item Modifiers | Use the worn_model field. |
| A different model in the GUI vs. in hand | Models Improvements | Use a separate-transforms model. |
| A model that changes by biome or position | Models Improvements | 1.21.1+. Use an expression-driven block model. |
| A custom post-processing shader | Shaders | Add a post chain in polytone/post_chains. |
| Make a block, entity or dropped item cast colored light | Colored Lights | 1.21.1. Add a colored_lights JSON with a colored_light color. Works out of the box. With the Veil mod, players can let Veil draw them instead. |
| Fine sky, sun, cloud or star control | Environment Attributes, Dimension Effects Modifiers | 1.21.11+. Set them through attributes_modifiers. |
| Move or hide a HUD element | Screen Sprite Modifiers, Gui Modifiers | Target the sprite and adjust its position or size. |
Q: Does this work on servers and in multiplayer?
Yes. Polytone is entirely client-side, so it works on any server (vanilla or modded) and only needs to be installed on your own client. The server does not need it.
Q: Do I still need OptiFine?
No. Polytone is an alternative to OptiFine's resource-pack features (and reads many of its formats). You don't need OptiFine installed, and mixing the two can actually cause conflicts.
Q: My modded block, biome or item isn't working. Why?
A file that references content from another mod must declare require_mods, otherwise it errors when that mod isn't present. See Conditions.
Q: Can I change all biomes (or all blocks) at once?
Yes, use a regex in the targets field, like ".*" for everything or "create:.*" for a single mod. See Targeting.
Q: Can one pack support multiple Minecraft versions?
Yes, using load conditions and pack overlays. See Conditions and Extra Features & Tweaks.
Q: How do I reload my pack without restarting the game?
Press F3+T in game. You can edit pack files and reload live.
Q: Does this support old OptiFine packs?
Yes, mostly. Concepts like Lightmaps and block colors work just the same.
Q: Does this work with Sodium?
Yes, but use its latest version. In case issues arise, report them to Sodium (and here).
Q: Does this have a performance impact?
No. The mod is designed to directly change the color value the game uses, with no lookup, so there are no downsides to using it. Experimental systems like Biome Variant Textures however do not follow this, which is why they are experimental.
Q: Does this support the OptiFine grid biome colormap?
Yes*. That system had terrible compatibility, since numerical IDs stopped being a thing back in 1.12, and they don't work at all in modded scenarios where you could exceed the count or have them assigned unpredictably as biomes are added. Use Biome Effect Modifiers instead! If you really want to use it, it's recommended you also add a biome_id_mapper to your colormap to specify the id mapping.
Q: I get a "Resource Reload Failed" when using my texture pack. What do I do?
This means something is wrong in your configuration JSONs. Check your latest.log (and Polytone's own polytone.log) in your logs folder; it will say exactly what.
Q: I want to tweak sky boxes.
If you want to do anything more than statically tweaking biome sky color, you should use a dedicated mod like Celestial.