Home - MehVahdJukaar/polytone GitHub Wiki
Thanks for using Polytone. If you enjoy this mod, please remember to add Polytone to your pack Optional Dependency section or use the provided banner.
Polytone is a Forge, Fabric and Neoforge client side customization mod that allows you to customize many additional game visuals via Resource Packs.
Keep Calm The mod can seem complex but this wiki is VERY in depth and will walk you through every aspect of it.
If you have any questions feel free to contact ME HERE
Dont forget to also click on show more pages at the bottom
Polytone is a Mod that allows you to tweak many visual aspects of the game.
To do so it expands the game 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 owns like Biome Variant Textures, Biome Properties, Block Sounds, Gui Modifiers, Particle Modifiers, File conditions and more!
Having trouble following this wiki? Check out the mod example pack HERE.
Direct Download HERE
Note that example pack just contains examples on a few concept. The wki is more rich in information. Still it should give you an idea of how stuff can be setup.
Finally, when in doubt, I suggest taking a look at the Existing Packs section on the curseforge page to see how other people have been doing stuff.
The mod works by having Modifier objects defined in .json files. Each Modifier will act on/be applied to an existing game obect such as Block, Item, Particle, Biome, Dimension and so on. There can be more than one of these per game oblect.
Each Modifier will be covered in detail in a dedicated wiki page.
Expand this section to read about some IMPORTANT preliminary concepts that are needed when using the mod.
CLICK ME!
For the few that don't know what resource packs are it's first MANDATORY that you familiarize with them. Polytone builds on top of the existing resource pack system after all. Learn about them on the Official Minecraft Wiki
The mod makes extensive use of Json files. These is what the game already uses for the entire data and resource system, for example when adding models or recipes.
If you are however not accustomed to datapacks or resource packs be sure you are using a TEXT EDITOR with JSON SYNTAX HIGHLIGHT.
Some of these are:
- Atom
- VsCode
- Notepad++ with Json syntax plugin
- Sublime Text
Json syntax is not something exclusive to MC and its is recommened you get comfortable with it (you can look it up online).
For example, some important concepts to have clear are how lists are defined (enclosed by [] brackets) or how objects are defined (anything inclused by {} brackets)
The mod works by creating .json files that define speicfic behaviors. These can be nested in specific ways as explained in each section. In many of these cases a second option is also available that allows to EXTRACT commonly used Json "pieces" into their own separate folder.
For example you can assing AND create a colormap in a Block Property Modifier directly or extract it into the separate colormaps folder to be reused in other places. This applies to many objects that the mod defines. Here's an example:
Block Property Modifier with inlined colormap
{
"colormap":{
"[colormap definition]"
}
}Colormap extracted and defined into its own colormap folder. Note that their content are the same.
{
"[colormap definition]"
}And here is that same block modifier using that colormap
{
"colormap": "my_namespace:my_colormap"
}For anybody not familiar, this is a very important concept used everywhere (mods, packs, datapacks) so lets get over some definition. A resource location (or Identifier in newer MC versions) is a string composed by Namespace (mod of origin) and Path (name) like as follows:
"minecraft:stone"Its Namespace is minecraft while its Path is stone.
All resource locations without an explicit Namespace (i.e. "stone") will be automatically assigned minecraft namespace.
To be a valid Resource Location your string must ONLY contain [a-z,0-9,-/_] characters so no capitals!
Any file in a resource pack can and very often will have a resource locaton assigned. Often these are folder based so a TextureManager might assing the texture supplementaries\assets\textures\blocks\globe.png the resource location supplementaries:blocks\globe.
This means that file paths themselves MUST also be a valid resource location all the times so be careful of capitals and spaces.
If you ever find yourself wanting to reference an object from another mod in these .json files you will NEED to add the require_mods field, accepting either a list of a string, like so:
{
"require_mods": [
"create",
"quark",
{
"mod": "jei",
"version": "[1.0.0,2.0.0)"
}
]
}This will cause that file to ONLY load if the requrired mod is installed. If you omit that line it will error when loaded without that mod on.
You can also add polytone_ignore and it will disable the json entirely.
Both these can also be added to .properties files, relevant for the backward compatibility conversion that polytone uses.
If for example you want to exclude one of such files from the compatibily conversion, you can do as follows:
{
"polytone_ignore": true
}or in properties
polytone_ignore = true You can also specify MC version in your conditions as such. Tho this is redundant as you can do the same with the required_mods block
{
"version": "[1.20, 1.21.1)"
}Finally you can also use Polytone Configs here. See the appropriate wiki page for more info. You simply reference your config by ID. Said config will then appear under the resource pack meny brush button (1.21.11+).
{
"require_config": "my_cool_pack:my_boolean_config"
}NOTE on 1.21.11+:
In versions greater than 1.21.11 condition fields should be put in the polytone_condition field inside each json instead of being loose.
The polytone_condition also supports a Scripting Eexpression like such:
{
"polytone_condition": "dateYear() == 2026 && modLoader() == 'neoforge'"
}Similar to conditions, all files also have a priority key. Jsons will simply be ordered with their natural order followig their priority. Use this to for example make a biome modifier affect all modded biomes while still allowin higher priority ones to override it. Base priority is 0 if not specified.
{
"priority": -2
}As stated previously, most of Polytone Jsons are Modifiers which will be attached to specific game objects (blocks, biomes, items and so on). As such they will all have a targeting mechanism. This can be of two type:
- Explicit targeting, defined as a list of IDs in each Modifier
targetsfield. Can also be a single ID instead. - Implcit targeting, will atomatically target the game object with ID and Namespace same as the Json file itself (json name and its namespace folder)
For Explicit targeting you can also make use Regular Expressions to, for example, target all entries at once or all entries of the same namespace at once.
Here's an example of Explicit Targeting:
Targets filed can hold a single entry or a list. Each entry can hold an ID, a Tag, a Regular Expression or an optioanl entry
Targets minecraft:stone and minecraft:dirt objects
"targets": [
"minecraft:stone",
"minecraft:dirt"
]Targets all objects from create namespace
"targets": "create:.*"
Targets ALL objects
"targets": ".*"Target a Tag
"targets": "#minecraft:flowers"Targets some optional components (technically not that useful since conditions exist)
"targets":[
{
"id": "create:brass_ingot",
"required": "false"
}
]Here's an example of Implicit Targeting:
Biome Modifier Json location
assets/byg/polytone/biome_modifiers/redwood_forest.json.
will target -> byg:redwood_forest biome
If you are using forge or neoforge remember that IT itself has a bunch of customization of its own so check out this page first. https://docs.neoforged.net/docs/resources/client/models/
Polytone is Resource Pack based. If you dont know what a resource pack is or never made one you it's highly reccommended you try making a simple one first. You can read about all about them on the Official Minecraft Wiki.
If you dont want to do that here's a quick reminer here:
- Make a folder in your
/resourcepacksfolder in your game directory - Add a
pack.mcmetaso its recognized as a pack. Use the following content:
{
"pack": {
"pack_format": 24,
"description": "My new resource pack"
}
}- Add an
/assetsfolder there. Every resource will always be in this very folder. - Every time you add a file or create a folder remember that their file name can only contain [a-z,0-9,/-] characters. This means no capitals!
- When in game, actually load the pack with the resource packs screen. You can change the pack content while ingame and reload the packs by pressing
F3+T
Is stuff not wroking? Here's a bulletpoint list of thigns to check in order.
- Are all your mods updated? If not update them! Updates might have fixed bugs or conflicts.
- Do you have some other mods installed? Try without them first. Especially relevant for graphical mods.
- Is your pack even loaded and does it have high priority? Check resource pack screen and put it up top and remove other packs while testing.
- Is the folder structure correct? Open op a json file you are working with, remove some brackets or add some commas or other nonsense at the very start such that the format is invalid. Does the pack get rejected/ you get loading errors? Good news, that means the file was being read. Is the pack loading fine? Then it means you are using the wrong file name/folder structure. Check out the relevant wiki section again.
- Is your file targeting the right targets (blocks/biomes...)? Try altering the targeting to another entry and see if that works.
- Is a particular line of my json file being read? If you suspect that it isnt you can repeat step 4 but altering that particular line.
- Are your changes only partially applied? This could mean some different files/packs are overriding eachother. Test the pack in isolation, ideally with JUST the single feature you are working on. Pay special attention to files belonging to the legacy compat with optifine format and if you can avoid relying on that entirely in favour of polytone native, or use "polytone ignore" if you have to.
- Are you on a beta or alpha version? Try the latest stable release instead. Early versions might have some features missing or even broken
- Still struggling? Try starting again from the Polytone Sample Pack mentioned above
- All else fail? Join the discord and ask a question on Resource Pack Corner channel
TL/DR? Just two steps: Not familiar with resource packs? See the Official Minecraft Wiki. Then download and start editing the Polytone Sample Pack.
Use the following chart to add the most common things you might want to do with Polytone to your resource pack.
| I Want To Change... | Which Pages | TLDR on What To Do |
|---|---|---|
| Water Color | Colormaps, Fluid Properties Modifiers & Biome Effects | Want to change single biome Color? Go to Biome Effects Modifiers. Want to use colormap? Add a file named water.png in polytone/fluid_modifiers. More info in Fluid Properties Modifiers page |
| 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 (Sprites and Slot Modifiers section) |
| Lightmaps | Lightmaps | Add a texture in 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 color.properties for static colors or use Particle Modifiers for more control |
| Fog Color / Sky Color | Biome Effects Modifiers, Dimension Effects Modifiers | Use biome modifiers to change a biome fog color or Dimension Effects to have a colormap that controls them |
| Dye/Map Colors | Custom Colors | Add a line in there such as dye.black = ff00ff00
|
| Make Hotbar bigger | Overlay Modifiers | Follow the example there. |
| Add a new texture to a named item | Custom Item Models | Add a texture and json file in custom_item_models folder |
| Remove Items from a Creative Tab | Creative Tab Modifiers | Follow the first example there. |
| Add some tooltip lines to an item | Item Modifiers | Follow the example there. |
| Add a texture that changes when it rains | Variant Textures | Add "mode": "weather" to your .mcmeta file. |
| Change a Block Render Type to Translucent | Block Modifiers | Add a modifier with "render_type": "translucent" |
| Make seasonal textures | Variant Textures | Add an animated texture which uses an expression that uses the season variable |
| Turn off certain parts of my pack with a config button | Config Entries | Add a config entries json file and use it your pack.mcmeta |
Q: Does this support old Optifine packs?
A: Yes, mostly. Concepts like Lightmaps, Block colors will work just the same.
Q: Does this work with Sodium?
A: Yes but use its latest version! Incase isseus arises tho report to Sodium (and here)
Q: Does this have performance impact?
A: No, the mod is designed to directly change the color value the game ises, no lookup used! This means theres no downsides in using it. Experimental systems like Biome Variant Textures however do not follow this hence why they are experimental.
Q: Does this support Optifine grid biome colormap?
A: Yes*. That system had terrible compatibility as numerical IDs are not only no loner a thing since 1.12 but also dont work at all in the modded scenarios where one could exceed the number or have them in a non predictable manner when biomes are added. Use Biome Effects instead!
If you really want to use it you can but its 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?
A: This means you did something wrong with the configuration jsons. Check your latest.log, in your /log/ folder it will say exactly what.
Q: I want to tweak Sky boxes.
A: If you want to do anything more than statically tweaking biome sky color, you should use a dedicated mod like Celestial