Content mods

What a content mod is

A folder (while you work on it) or a .hmod file (to share it) holding a manifest, assets/ and data/. Here is a mod that adds a ruby gem and a block of ruby:

ruby/
├── horizon-mod.toml
├── data/ruby/horizon/block/ruby_block.json        the block: a template and what differs
├── data/ruby/horizon/item/ruby.json               the item
├── data/ruby/recipe/ruby_block.json               recipes, as in a data pack
├── data/ruby/recipe/ruby_from_ruby_block.json
├── data/ruby/loot_table/blocks/ruby_block.json    what the block drops
├── data/minecraft/tags/block/mineable/pickaxe.json   added to vanilla's tags
├── data/minecraft/tags/block/needs_iron_tool.json
├── assets/ruby/blockstates/ruby_block.json        models and textures, as in a resource pack
├── assets/ruby/models/block/ruby_block.json
├── assets/ruby/models/item/ruby.json
├── assets/ruby/items/ruby.json
├── assets/ruby/items/ruby_block.json
├── assets/ruby/textures/block/ruby_block.png
├── assets/ruby/textures/item/ruby.png
└── assets/ruby/lang/en_us.json                    the names players see

The manifest

Every content mod has a horizon-mod.toml at its root:

id = "ruby"
name = "Ruby"
version = "0.1.0"
description = "A ruby gem and a block of ruby"
authors = ["You"]
api = "0.2"
side = "both"
capabilities = ["registries"]

Unknown keys are refused, so a typo is an error, not something silently ignored.

Blocks

A block is a file data/<id>/horizon/block/<name>.json. It becomes the block <id>:<name>, with the template's behaviour, states and shapes:

{
  "template": "minecraft:iron_block",
  "properties": { "hardness": 4.0, "light": 3, "sounds": "minecraft:amethyst_block", "map_color": 28 }
}

Every property you leave out is the template's.

Items

An item is a file data/<id>/horizon/item/<name>.json, copying a vanilla item:

{ "template": "minecraft:diamond", "rarity": "uncommon" }

It may change max_stack_size (1 to 99) and rarity (common, uncommon, rare or epic, the colour of its name).

Recipes, loot, tags, models and names

Everything else uses vanilla 26.3's own formats, so the Minecraft Wiki's pages on data packs and resource packs apply:

• Recipes in data/<id>/recipe/, loot tables in data/<id>/loot_table/.
• Tags: your own in data/<id>/tags/. To add to vanilla's (which pickaxe mines the block, for example), put a tag file in data/minecraft/tags/; to add to the convention tags NeoForge and Fabric mods share, in data/c/tags/. They add to the tag as a data pack does; "replace": true drops what came before it, and the log says so.
• Block states, models, item models and textures in assets/<id>/, as in a resource pack. Models can use vanilla's parents, such as minecraft:block/cube_all.
• Names in assets/<id>/lang/en_us.json: "block.ruby.ruby_block": "Block of Ruby", "item.ruby.ruby": "Ruby".

Structures. A content mod can also carry structures, template pools and structure sets in its namespace, and add its own pieces to vanilla's villages or to another mod's pools. The mod design page has the details.

Namespaces

Your files go under your mod's id (assets/ruby/, data/ruby/), plus vanilla's and the convention tags (data/minecraft/tags/, data/c/tags/). Tags are the only files a mod may put under minecraft.

A mod made from a Java mod whose files use other names lists them in its manifest: namespaces = ["kaisyn", "towns_and_towers"]. A listed namespace is the mod's own, as its id is, but blocks and items are still declared under data/<id>/horizon/. minecraft, c and horizon can't be listed, and two mods that are on can't own the same namespace: the game keeps the first and logs the clash.

Limits

• A mod's files use vanilla's resource-name characters: at most 65,536 files, 16 MiB each and 512 MiB in all.
• A file the game can't read (a block model that doesn't parse, a recipe with a typo) is logged and skipped, as vanilla does: the rest of the mod still loads. Read the log while you work.
• Unknown keys in a block or item file are refused, and the mod stays off with the reason on its row.
• Content mods work in single player today. Playing them together on a server is planned.

Start one

Install cargo horizon-mod, the tool that makes, builds and checks content mods. It needs Rust to install, and builds from source in a few minutes; run it again later to update it:

cargo install --git https://github.com/horizon-rust/horizon cargo-horizon-mod
cargo horizon-mod new my-blocks --template content

makes a content mod with one block, Glowing Amethyst: an amethyst block that gives light, with its block state, model (using vanilla's amethyst texture), item model, name, loot table, a recipe (an amethyst block and glowstone dust) and the pickaxe tag. Rename and copy its files to add your own.

Try it and share it

While you work, give the game the folder as a dev mod, always on: in the launcher's Settings, put --dev-mod "/path/to/ruby" in Game arguments, then press Play (clear it when you are done). With a horizon-client you built yourself, cargo horizon-mod run --game <path> builds the mod and starts that game with it. The first start with a new set of mods takes a little longer while the game adds their content to its tables; after a change to the files, start the game again.

To share it, build the .hmod in the mod's folder:

cargo horizon-mod build
cargo horizon-mod check target/horizon-mod/ruby.hmod

build checks the files as the game will and packs the manifest, assets/ and data/ into target/horizon-mod/<id>.hmod, with no compiler involved. check reads it as the registry does and says "no code: content only, nothing to run". Players put that file in their horizon-mods folder and turn it on in Options, Mods..., and you can publish it like any mod.

A content mod has no code. For behaviour (a HUD, a command, a key), make a native mod; it can come beside a content mod that holds its blocks and items.

Next: test it.