Full example and limits

Full example

{
  "id": "field_medkit",
  "display_name": "Field Medkit",
  "translation_key": "item.my_pack.field_medkit",
  "lore_translation_keys": ["tooltip.my_pack.field_medkit"],
  "type": "consumable",
  "stack_size": 4,

  "model": "my_pack:geo/item/field_medkit.geo.json",
  "texture": "my_pack:textures/item/field_medkit.png",
  "animation": "my_pack:animations/item/field_medkit.animation.json",
  "camera_bone": "Camera",
  "hide_second_skin_layer": true,

  "idle_animation": "idle",
  "use_animations": ["use", "use_alt"],
  "use_order": "random",
  "equip_animation": "equip",
  "unequip_animation": "unequip",
  "sounds": {
    "equip": "medkit_equip",
    "unequip": "medkit_unequip"
  },

  "use_mode": "single_use",
  "consume_tick": 35,
  "cooldown": 100,
  "cooldown_group": "medical",
  "result_item": "minecraft:glass_bottle",
  "always_use": true,
  "requirements": {
    "min_missing_health": 2,
    "failure_translation_key": "message.my_pack.health_full"
  },

  "equip_events": [
    { "type": "sound", "sound": "medkit_latch", "tick": 4, "volume": 0.8 }
  ],

  "use_events": [
    { "type": "sound", "sound": "medkit_open", "tick": 10 },
    { "type": "heal", "amount": 6, "tick": 35 },
    {
      "type": "effect",
      "effect": "minecraft:regeneration",
      "duration": 160,
      "amplifier": 0,
      "mode": "extend",
      "tick": 35
    },
    {
      "type": "effect",
      "effect": "minecraft:speed",
      "duration": 80,
      "animation": "use_alt",
      "tick": "end"
    }
  ]
}

The player can only use it while missing at least one heart. The latch sound plays 4 ticks into the equip clip, and the open sound 10 ticks into the use clip.

At tick 35 the use commits: one medkit is taken, the use is counted, the shared medical cooldown starts and a glass bottle is given back. On the same tick the player is healed three hearts and gets regeneration, added on to any they already have.

Each use picks use or use_alt at random. When use_alt finishes, the player also gets speed.

What gets checked

Items. Bad JSON, a missing required field, a wrong value type, a bad resource location, a number out of range, or an unknown enum value or action type skips that one item. The log names the file and line.

Packs. A bad pack.json skips the whole pack.

Armor. A bad field skips that one piece. Fields no installed addon reads are logged as warnings.

Unknown item fields are ignored, so a misspelled optional field silently does nothing. Check the spelling if a field seems to have no effect.

Missing files. A model, texture or animation missing from your own namespace logs a warning.

IDs and values. Duplicate item IDs in one pack are rejected. IDs, stack sizes, charge counts, durations, timing windows, sound keys and other bounded values are all checked.

Result items. result_item is checked for correct syntax at load. If the item doesn’t exist when the use commits, nothing is given.

Limits

Timelines and actions run on the server. The results reach clients through the normal inventory and effect syncing.
A player can only run one use at a time. A new use is refused until the current one ends or is cancelled. Switching away always works, and cancels or unequips.
An early consume_tick keeps following the stack that ends up in the hand, so later events still run. Actually switching slot or replacing the stack still cancels them.
Equip and unequip share one event timeline per player. A new equip or unequip replaces the old one.
equip_duration doesn’t block switching or using. That’s deliberate.
Off-hand equip and unequip animations aren’t supported.
The sounds object gives one sound per animation family, shared by every clip in it. Timed sound events don’t have that limit.
Built-in actions hit the user, or the living entity the item was used on. For anything aimed at blocks, the world or another mod’s mechanics, use a command event (from a pack you trust) or a custom action.