For modpack makers

Shrinking recipes

A fixed recipe:

{
  "type": "familiarslib:shrinking_recipe",
  "input": {
    "item": "alshanex_familiars:armor_plate_tier_1"
  },
  "result": {
    "id": "alshanex_familiars:armor_plate_tier_1",
    "count": 1,
    "components": {
      "familiarslib:familiar_consumable": {
        "type": "armor",
        "tier": 1
      }
    }
  }
}

• input: the item that goes in.
• result: the item that comes out. Components are optional; this example shows how to make an item a familiar consumable.

Recipe files go in any recipe folder of a datapack or mod, for example data/mypack/recipe/shrinking/my_recipe.json.

When several recipes match the same item, fixed recipes win, then cosmetics, then dyes, then food.

Before the shrinking station moved to Familiars Lib, the types were alshanex_familiars:shrinking_recipe and alshanex_familiars:food_shrinking. Files using the old types keep working, but update them to the familiarslib: types.

Consumables

Items become familiar consumables through the familiarslib:familiar_consumable component:

"components": {
  "familiarslib:familiar_consumable": {
    "type": "armor",
    "tier": 1
  }
}

There are 6 types:

Colors

Color values

Anywhere a color is written in a data file, you can use:

How the tint works: a recolored part is a grayscale texture multiplied by the color. White parts of the texture become exactly your color, and darker parts become darker shades of it. This keeps the original shading, but a color can only get darker, never brighter, than what you write. Light or saturated colors usually look best.

Layer slots

Each familiar has 5 color slots, numbered 0 to 4. What each slot is depends on the familiar; each familiar mod documents its own. By default:

Override rules (below) replace this for the familiars and items they name.

Override files

Override files define "use this item on this familiar to set these colors" rules. They work on any familiar with color layers, with any item.

Files go in data/<namespace>/familiar_color_overrides/<name>.json. Familiars Lib ships an empty base file at data/familiarslib/familiar_color_overrides/overrides.json, which mods and datapacks add to.

{
  "replace": false,
  "entries": [
    {
      "familiar": "alshanex_familiars:druid_pet",
      "item": "minecraft:cherry_leaves",
      "layers": { "1": "#F2A7C8" },
      "consume": true,
      "sound": "minecraft:block.grass.place"
    }
  ]
}

How rules apply:

• Only the owner of a tamed familiar can use them.
• If the familiar already has those colors, nothing happens, the item isn't used up, and the click goes on to the familiar's normal interaction.
• When several rules match, the last one loaded wins: later entries in a file, files in alphabetical order of their id, and copies of the same file in pack load order.
• Rules come before dyes: a rule for a dye replaces normal dyeing for the familiars it names. Every other familiar keeps dyeing normally.
• Rules naming familiars or items from mods that aren't installed are skipped quietly.
• A slot the familiar doesn't use does nothing, so one rule can safely reset all slots on every familiar.
• Shrunk dyes only match rules with "shrunk": true, so existing dye rules keep affecting the main color only. For example, to make shrunk light blue dye give an archmage glowing cyan eyes: { "familiar": "alshanex_familiars:archmage_pet", "item": "minecraft:light_blue_dye", "shrunk": true, "layers": { "1": "#7FE3FF" } }.

Merging and replace: override files merge like tags. When several packs or mods provide the same file id:

• "replace": false adds its entries to the ones loaded before.
• "replace": true discards everything loaded before for that file id, then adds its own.

To add to the shared rules from a datapack, create data/familiarslib/familiar_color_overrides/overrides.json with "replace": false. To replace every default rule, use "replace": true. Files with different ids never affect each other.

Examples:

{ "familiar": "#alshanex_familiars:familiars", "item": "irons_spellbooks:shriving_stone",
  "layers": { "0": "default", "1": "default", "2": "default" }, "consume": false, "sound": "minecraft:block.grindstone.use" }

{ "familiar": "alshanex_familiars:archmage_pet", "item": "minecraft:black_dye", "layers": { "0": "#2B1838" } }

Since the last match wins, put broad rules (like #minecraft:leaves) before specific ones (like minecraft:cherry_leaves).

Retexturing color layers

Color layers are textures, so a resource pack can change their shape or shading without any code. Each colored part has two textures in the familiar mod's assets/<namespace>/textures/ folder (for Alshanex's Familiars, textures/entity/layers/):

• <name>.png: the part in its original colors, drawn when the slot has no color.
• <name>_bw.png: the same pixels in grayscale, tinted with the slot's color.
• Optionally <name>_glowmask.png and <name>_bw_glowmask.png, for parts that glow (such as eyes).

Keep the same size and UV layout as the familiar's base texture, and follow the rules in Layer textures. If you change which pixels a layer covers, change the base texture too, or the old pixels show under the layer. The exact file names are listed on each familiar mod's page.

Biome color files

Familiar mods can make familiars take their colors from the biome they spawn in. Each familiar mod decides its folders and color fields (see the mod's own wiki), but every biome color file has the same format:

{
  "entries": [
    { "biome": "#c:is_taiga",             "hat": "#CC7C66", "dog": "#5A2E1A" },
    { "biome": "minecraft:cherry_grove",  "hat": "#B27291", "dog": "#4A2433" }
  ]
}

• biome: a biome id, or a biome tag starting with #.
• Color fields: each one is optional; a missing field keeps that part's original look.

How a biome is matched:

1. An entry with the exact biome id wins over any tag entry.
2. Otherwise, the last tag entry containing the biome wins, so order tag entries from broad to specific.
3. A biome with no matching entry keeps the original look.

Every file in a folder is loaded and combined, from any namespace. A datapack file with the same path as a built-in one replaces it.

Prefer common #c: tags (#c:is_forest, #c:is_snowy...) so modded biomes get colors automatically. /reload reloads these files, but only affects familiars that spawn afterwards.

Shrunk dyes

The familiarslib:shrinkable_dyes item tag lists what the shrinking station turns into shrunk dyes. It contains #c:dyes by default, so modded dyes work too. Shrunk dyes carry the familiarslib:shrunk_dye component.

Dyes color the eyes automatically. Other items added to the tag (for example glow ink sacs) can be shrunk too, but only do something through override rules with "shrunk": true.

Cosmetic tags

familiarslib:familiar_hats contains Iron's Spellbooks' wizard_hat, tarnished_helmet, archevoker_helmet and electromancer_helmet by default. Other items can be added with "replace": false: helmets, mob and player heads, and blocks like carved pumpkins are all drawn correctly on familiars (see Hats).

familiarslib:familiar_weapons is empty in the lib: each familiar mod adds its familiars' weapon tags to it. If you add items to a familiar's weapon tag, make sure that tag is in familiarslib:familiar_weapons, or the items can't be shrunk.

Sit items

The familiarslib:familiar_sit_items item tag lists the items that make a familiar sit or stand up when its owner right-clicks it. It contains minecraft:stick by default.

To add items, ship data/familiarslib/tags/item/familiar_sit_items.json with "replace": false. Values can be item ids or tags:

{
  "replace": false,
  "values": [
    "minecraft:blaze_rod",
    "#c:rods"
  ]
}

To replace the stick entirely, use "replace": true and list only your items.

Avoid items that already do something on familiars, such as foods, consumables, dyes, totems or items in color override rules: those interactions run first, so the item won't toggle sitting (see Interaction order). A familiar mod can also give one familiar its own sit items, which ignore this tag (see Sitting and sleeping).

Familiar Compendium

The compendium is generated automatically from the loaded data: biome color files, override rules and dyes. Modpack changes show up after /reload, including modded biomes in common tags.

Config

The server config has:

The number of familiars summoned at the same time is always capped at 10.

Taming items

The familiarslib:familiar_taming item tag lists the items that tame familiars. Ship data/familiarslib/tags/item/familiar_taming.json with "replace": false to add items, or "replace": true to replace them.

Familiar Eggs

The egg is the item familiarslib:familiar_egg. A plain egg is an empty egg. A typed egg has the familiarslib:familiar_type component, holding a familiar's entity id. Any recipe that accepts item stacks with components can produce one:

"result": {
  "id": "familiarslib:familiar_egg",
  "components": { "familiarslib:familiar_type": "alshanex_familiars:druid_pet" }
}

The same works with commands:

/give @s familiarslib:familiar_egg[familiarslib:familiar_type="alshanex_familiars:druid_pet"]

Typed eggs work for any familiar, from any mod. An egg for an entity that isn't a familiar is popped off the bed when it would hatch.

Bound eggs use the familiarslib:bound_familiar component, which holds the familiar's full saved data. Don't write it by hand: bind familiars through the egg screen.

Other tags

Attributes

Both are player attributes, so gear can raise them for its wearer's familiars.