Projectile Configuration

Register projectiles fired by launchers — arrows, bullets, and similar physics entities.

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

Register the file in your mod’s manifest (mods/<YourMod>/<YourMod>.yaml):

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

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).

Typed shots (damage-type). By default a projectile deals physical damage, reduced by the target’s general armor. Set damage-type: fire or damage-type: blast and the hit routes through that channel instead — still reduced by general armor, then additionally by the matching per-type resistance if the target has any. This is how a flaming arrow or a concussive slug reads differently against a fire- or blast-resistant enemy. The type governs only the projectile’s own damage; if it also carries a spawn-aoe-on-impact zone, that zone’s damage uses the zone’s own type. (A direct hit’s type is server-side only — it never changes how the projectile looks.)

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.

Passing through enemies (pierce). By default a projectile despawns the moment it strikes an entity, so one shot hits one target. Give it a pierce budget and it keeps flying through that many entities before the next hit stops it — a full-draw longbow arrow that skewers a line of foes, or a heavy ballista bolt. Each entity in the projectile’s path is damaged at most once; blocks and static objects still stop it immediately, and a spawn-aoe-on-impact burst (or a thrown weapon’s retrieval drop) fires only when the projectile finally despawns, not on every enemy it threads. Keep the budget modest so it doesn’t trivialize crowds.

Returning boomerangs (return-to-owner). A boomerang flies out to max-range, turns around, and steers back to whoever threw it, hitting enemies on both the outbound and return legs (each enemy once per leg — the per-leg dedup re-arms at the turnaround). When it reaches the thrower it is reabsorbed, restoring the thrown item — so pair it with a thrown weapon whose thrown-info retrieval.chance is 1.0, and the flight time itself is the “reload.” If it can’t get home — the thrower dies, disconnects, or moves out of the loaded world, or it hits a wall on the way back — it falls to the ground as the usual retrieval pickup instead. Give a boomerang gravity-multiplier: 0 so it flies flat, and a max-range for how far out it travels before turning. This is a projectile-side flight mode; it composes with a thrown item exactly like throwing_knife does.

Bursting into an area effect (spawn-aoe-on-impact). When set, the projectile spawns the named AoE zone at its position the moment it despawns — on a block, entity, or object hit, and on a lifetime/range fuse-out (so a thrown flask that falls short still bursts). The zone is owned by whoever fired the projectile, so the shooter is exempt from its own burst (everyone else in range is affected). Direct-hit damage and the zone’s damage are independent: give a pure delivery projectile (a flask) damage: 0 so all the harm comes from the zone, or keep damage on an explosive arrow that both strikes and bursts. The zone supplies its own damage type (fire/blast/…), lifetime, radius, and visuals — see aoe-zone-config.md. A bare zone name is scoped to your mod; include a mod: prefix to reference a zone from another mod.

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

  # A full-draw longbow arrow that skewers a line of up to three enemies before stopping.
  - name: longbow_arrow
    damage: 10.0
    gravity-multiplier: 0.7
    pierce: 3

  # A boomerang: flies out 16 blocks, curves back to the thrower, hits foes on both legs.
  # Pair with a thrown item whose thrown-info retrieval.chance is 1.0 so it always returns.
  - name: boomerang_projectile
    damage: 7.0
    gravity-multiplier: 0.0
    max-range: 16
    return-to-owner: true

  # A flaming arrow: strikes for fire damage, cut by armor + any fire resistance.
  - name: fire_arrow
    damage: 7.0
    damage-type: fire
    gravity-multiplier: 0.8

  # A thrown flask: no direct damage, bursts into a fire zone on impact.
  - name: fire_flask
    damage: 0.0
    gravity-multiplier: 1.0
    max-range: 24
    spawn-aoe-on-impact: fire_burst   # an AoE zone defined in this mod's aoe-zone-config

Last updated Aug 17, 2026