Shared Concepts

Shared Concepts

Almost every Polytone file, whatever feature it belongs to, is built from the same few pieces: how it points at a game object, how it decides whether to load, and how small JSON snippets nest and reuse. Learn them once here; the feature pages assume you have.

Note

New to resource packs or JSON? Start on the Home page. This page covers only the parts that are specific to Polytone.

Resource Locations (Identifiers)

Polytone points at things by their id, the same namespace:path string the whole game uses:

Part	Example	Meaning
Namespace	minecraft	The mod it comes from. Omit it (stone) and minecraft is assumed.
Path	stone	Its name.

Valid characters are a-z 0-9 . _ - / only.

Important

No capitals, no spaces. This applies to your file and folder names too, because Polytone often turns a file's path into an id. A stray capital in a folder name is a common reason a pack silently does nothing.

Modularity: inline vs. extract

Many pieces (a colormap, a color, a sound...) can be written inline where they're used, or extracted into their own file and referenced by id so several places share one copy.

Style	Looks like	Use when
Inline	"colormap": { ...definition... }	You use it in one place.
Extracted	"colormap": "my_pack:my_colormap"	You reuse it, or want it tidy.

Both do the same thing. An extracted colormap just lives on its own under the colormaps folder and is called by id.

Targeting

Most Polytone files are modifiers: they attach to an existing game object (a block, biome, item, particle...). They find their target one of two ways.

flowchart LR
    A[Your JSON file] -->|no targets field| B["<b>Implicit</b><br/>file path becomes the id"]
    A -->|targets field present| C["<b>Explicit</b>"]
    C --> D["<b>id</b><br/>minecraft:stone"]
    C --> E["<b>#tag</b><br/>#minecraft:flowers"]
    C --> F["<b>regex</b><br/>create:.*"]

Loading

Implicit is the tidy default: with no targets field, a file targets the object whose id matches its own path and namespace.

assets/byg/polytone/biome_modifiers/redwood_forest.json  →  byg:redwood_forest

Explicit: add a targets field to aim anywhere. It takes a single value or a list, and each entry is an id, a #tag, or a regular expression:

To target...	targets value
One or more ids	["minecraft:stone", "minecraft:dirt"]
Everything from one mod	"create:.*"
Everything	".*"
A tag	"#minecraft:flowers"

For an entry that shouldn't error when its target is missing (rarely needed, since conditions usually fit better), use the long form. required defaults to true:

"targets": [
  { "id": "create:brass_ingot", "required": false }
]

Note

A plain string is read as an id first, then a tag, then a regex. That's why minecraft:stone is a literal target while create:.* becomes a pattern: * isn't a legal id character. If a file has both a valid implicit target and explicit targets, Polytone warns you. Put explicit-target files under your own namespace folder so you don't overwrite another pack's file at that path.

Conditions

Any file can declare when it should load.

Warning

If a file references content from a mod that isn't installed, it must declare require_mods, or it will error on load.

Field	Effect
require_mods	Load only if the listed mod(s) are present. A string, a list, or { "mod": ..., "version": ... } for a version range.
require_config	Load only if a Polytone Config (referenced by id) is enabled.
version	Load only on a matching MC version range. Usually redundant with a require_mods version range.
polytone_ignore	true disables the file entirely. Also honored in legacy .properties files, to skip the OptiFine-compat conversion.
polytone_condition	(newer versions, 1.21.1+) A single field that either wraps all the fields above, or holds a Scripting Expression returning a boolean.

{
  "require_mods": [
    "create",
    "quark",
    { "mod": "jei", "version": "[1.0.0,2.0.0)" }
  ]
}

Tip

polytone_condition with an expression lets you gate on things the plain fields can't, e.g. the date, loader, or any Scripting Expression value:

{ "polytone_condition": "dateYear() == 2026 && modLoader() == 'neoforge'" }

Priority

Every file takes an optional priority integer (default 0). When more than one file applies, higher priority wins. Give a broad "catch-all" file a negative priority, for example a biome modifier that colors all modded biomes, so normal-priority files still override it case by case.

{ "priority": -2 }

Debugging a pack

Pack not doing anything? Reload it in-game with F3+T and work down this list. The goal is to narrow where it breaks: is the file even read, is it aimed right, or is something else overriding it?

1. Is the pack loaded and on top? Open the resource pack screen, move your pack above the others, and remove unrelated packs while testing.

2. Is the file even being read? This is the key trick:

   [!TIP] Deliberately break the JSON you're testing: add a stray , or delete a { near the top, then reload.

   • You get a load error / "Resource Reload Failed" → good, the file was being read. Your problem is the content or targeting.
   • Nothing happens → the file is in the wrong folder or has the wrong name. Re-check the path and filename against the feature page.

3. Is it aimed at the right thing? Temporarily retarget it to something obvious (a block you're standing on) to confirm the effect works at all, then narrow back down.

4. Does the modifier apply at all? Before blaming one field, change something you know is supported and obvious, then work back to the field you actually want.

   • Block modifier: alter the block's sound (or another simple property). If that takes effect, the modifier is applying and your real problem is the specific field, maybe it's misspelled or not supported on your Polytone / MC version.
   • Particle emitter: first emit a vanilla particle (a clearly visible one like flame) instead of your own custom type, which might simply be rendering invisible. Once the emitter works, swap your particle back in.

5. Is one specific line the problem? Repeat step 2's break-it trick on that single line to prove it's being parsed.

6. Only partly working? Another file or pack is likely overriding it. Test with just that one feature present. Watch for leftover OptiFine-format files; prefer Polytone-native, or set polytone_ignore on the legacy file.

Still stuck?

• Check the logs in your logs/ folder. Polytone writes its own polytone.log, and a failed reload also names the exact offending file and line in latest.log.
• Update every mod, and test without other graphical mods, which are the usual conflict.
• On a beta/alpha build? Try the latest stable; early builds can have missing or broken features.
• Restart from the Sample Pack, or ask in the Resource Pack Corner channel on Discord.