Projectile Configuration

Projectiles are the physics entities fired by projectile launchers (bows, guns, etc.) — arrows, bullets, and similar. This is the catalog file that registers them; a launcher’s ammo item references one by name (see item-config.md’s ammo-info).

File Location

projectile-config: projectile-config.yaml

Then create the file it points to, relative to your mod’s folder:

mods/<YourMod>/projectile-config.yaml

The file is a single list of projectile entries:

projectiles:
  - name: my_arrow
    damage: 5.0
    gravity-multiplier: 0.8

Names are automatically prefixed with your mod name unless you write one already containing a colon.

Minimal Example

projectiles:
  - name: my_arrow

Fields

Field	Default	Description
`name`	(required)	The projectile’s identifier — referenced by an ammo item’s `projectile:` field.
`damage`	`1.0`	Damage dealt on hit.
`knockback`	`0.0`	Shoves a struck entity along the projectile’s flight direction on a landed hit (a blocked, deflected, or invincibility-framed hit imparts none). A velocity magnitude in blocks/second that briefly overrides the target’s movement and decays over a fraction of a second. `0` = no knockback.
`gravity-multiplier`	`1.0`	Scales how much gravity affects this projectile in flight — `0.0` disables fall entirely, `1.0` is normal gravity.
`hitbox`	`{width: 1.0, height: 1.0}`	`{ width, height }` in blocks, used for collision.
`max-lifetime-ms`	`30000`	How long (in milliseconds) the projectile may stay in flight before it despawns on its own. Set `0` to disable the time limit.
`max-range`	`256`	How far (in blocks) the projectile may travel from where it was fired before it despawns on its own. Set `0` to disable the range limit.

Why the lifetime and range limits exist. A projectile normally despawns when it hits a block, entity, or object. But one that flies off into open sky (especially with a low gravity-multiplier) or past the loaded world never hits anything — without a limit it would linger forever and accumulate. max-lifetime-ms and max-range are safety backstops that guarantee every projectile eventually goes away. The defaults are generous enough not to affect normal shots; raise them for deliberately long-range weapons, or set either to 0 to opt out (not recommended, since that reintroduces the possibility of lingering projectiles).

A launch speed isn’t set here. How fast a projectile actually flies is controlled by the launcher item’s launch-velocity field (see item-config.md’s projectile-launcher-info), not anything in this file — a projectile’s own config only affects its damage, fall behavior, and hitbox once it’s already moving.

Unknown fields are rejected. Only the fields listed above (plus hitbox) are accepted. A misspelled or unrecognized key — for example a stray horizontal-velocity, which the projectile does not control — fails the entry at load with an error naming the offending field, rather than being silently ignored. Fix or remove the key to load the projectile.

Complete Example

projectiles:
  - name: steel_arrow
    damage: 8.0
    gravity-multiplier: 0.9
    max-lifetime-ms: 20000
    max-range: 300
    hitbox:
      width: 0.5
      height: 0.5