Villager API

Villager API

A simple data-driven framework for making custom villager professions, types, and trades without touching any code. Just drop JSON files in a folder and you’re done. You can also override or merge custom trades into vanilla or other modded villager’s trades.

What does it do?

This mod lets you create completely custom villagers with your own:

• Professions – New jobs with custom workstations and trading lists
• Types – Different villager appearances tied to specific biomes
• Trades – Full control over what villagers buy and sell at each level
• Hero Gifts – Custom loot tables for post-raid rewards

Everything is handled through JSON files in the villagerpacks folder. No coding, no complex setup—just make your files and load up the game.

Quick Example

Want an Alchemist villager who uses a crying obsidian block as their workstation?

1. Create villagerpacks/my_pack/villagers/poi_types/alchemist.json and villagerpacks/my_pack/villagerapi_config.json
2. Define the workstation block
3. Add the profession file linking to that POI type
4. Set up your trades
5. Drop in textures for the profession overlay

That’s it. The mod handles registration, trade mechanics, and everything else.

What can you customize?

• Workstations – Any block can be a job site
• Trading pools – Define exactly what villagers offer at each experience level (Novice through Master)
• Item components – Full support for enchantments, custom names, potions, and all the data components Minecraft uses
• Treasure maps – Sell maps to modded or vanilla structures with custom markers
• Biome appearances – Make villagers look different depending on where they spawn
• Biome-specific trades – Same profession, different inventory based on villager’s biome type

Who and what is this for?

If you’ve ever wanted to add villagers to your modpack or mod without dealing with Java code, this is for you. It’s built for pack makers and modders who want villager content without the headache of getting into learning and writing java code.

Works with both regular resource pack like villager packs and as part of mods by simply putting a villagers folder in your mods main directory. Multiple packs can run at once—later packs override earlier ones where there’s overlap.

Full Documentation

Check the complete documentation with examples and all available options here:
https://github.com/frikinjay/villagerapi/blob/main/DOCUMENTATION.md

You can generate a pack online here without having to manually create all the files:
Villager Pack Generator

The docs include the full pack structure, all JSON formats, item component examples, and a complete example pack to get you started.