Item Types

Throwable

Defines an item that can be thrown by right-clicking. As an entity, a thrown item can be caught by anyone by right-clicking it. When a thrown item hits an entity, it will deal damage based on its speed.

Field	Default	Description
damage_multiplier	1.0	When the thrown item hits an entity, the damage it deals will be multiplied by this value.
requires_crouch	false	If true, the player will need to crouch in order to throw the item with right click.
breaks	"#minecraft:leaves"	A HolderSet of the blocks that the thrown item will break upon impact.
bounce	false	If true, the thrown item will bounce off of a surface (block or mob). Otherwise, it will drop as an item.
bounce_off_floor	false	If false, the thrown item will not be able to bounce off of the floor.
loyalty	0.0	Determines how "much" the thrown item will return to its owner, on a scale of 0-1. Only takes effect if bounce is true. See below.
throw_sound	"vibranium:item.thrown.whoosh"	The sound to play when the item is thrown.
bounce_sound	"vibranium:item.thrown.whoosh"	The sound to play when the thrown item bounces off a surface.
catch_sound	"vibranium:item.thrown.whoosh"	The sound to play when the thrown item is caught or picked up.
auto_catch	true	If true, the thrown item entity will be automatically caught when it hits its owner. If false, then the thrown item will damage its owner on hit.

Examples:

addon/test/item/throwing_axe.json

{
  "type": "vibranium:throwable",
  "damage_multiplier": 2,
  "auto_catch": false
}

addon/test/item/shield.json

{
  "type": "vibranium:throwable",
  "bounce": true,
  "bounce_off_floor": false,
  "loyalty": 1,
  "requires_crouch": true,
  "throw_sound": "vibranium:item.vibranium_shield.throw",
  "bounce_sound": "vibranium:item.vibranium_shield.bounce",
  "catch_sound": "vibranium:item.vibranium_shield.catch",
  "properties": {
    "components": { "minecraft:blocks_attacks": {} }
  }
}

Loyalty

If loyalty is 1, the thrown item will bounce directly back to its owner after hitting something. If it is 0, then it will bounce normally, i.e. via a reflection across the hit surface's normal vector. The thrown item's new motion vector after bouncing is a linear interpolation of the "true" bounce vector and the "directly return to player" bounce vector using the loyalty field.

The angles and magnitudes of the vectors are approximations (I made the desmos graph freehand instead of actually doing the math). In-game, the reflected motion vector always has the same magnitude as the "true" reflection vector, which is always 0.9 times the magnitude of the incoming motion vector.

It is also noteworthy that when a thrown item hits a mob, the normal vector is the opposite of the item's motion vector. This means that when a thrown item that can bounce hits a mob, it will bounce directly back in the direction that it came from.