Projectile Texture Configuration

Configure textures for projectiles — the mob/mount sprite sheet system, plus rotation alignment data.

Projectiles (arrows, thrown items, fired shots) use the same sprite sheet, animation, states, and light mask system as Mob Texture Configuration. This page covers the projectile-specific file locations plus the extra projectile-texture-data block that controls how the sprite rotates to face its direction of travel and which animation loops while the projectile flies.

File Location

Config file:

mods/<your-mod>/assets/textures/projectiles/projectiles.yaml

Texture images go in the same folder:

mods/<your-mod>/assets/textures/projectiles/<name>.png

The file name must match the name field exactly (case-sensitive), with spaces kept as spaces in the file name.

Minimal Example

textures:
  - name: my_bolt
    sprites:
      - name: my_bolt
        frame-count: 1
    frame-width: 32
    frame-height: 32

This registers a projectile named my_bolt from my_bolt.png. It will be referred to as YourMod:my_bolt anywhere a projectile name is expected.

Full Field Reference

textures:
  - name: my_bolt                # Required. Registered as YourMod:my_bolt
    override: Creation:wooden_arrow  # Optional. Replace another mod's registered projectile (see below)
    light-mask: my_bolt_mask     # Optional. Light mask texture
    frame-width: 32              # Required. Width of one frame in pixels
    frame-height: 32             # Required. Height of one frame in pixels
    sprites:                  # Required. One or more named animation sequences
      - name: my_bolt             # Required. Animation name
        frame-count: 1           # Required. Number of frames in this animation
    states:                      # Optional. Named static poses
      - name: idle
        sprite: my_bolt
        frame: first
    projectile-texture-data:     # Optional. Rotation alignment + flight animation (see below)
      texture-rotation-offset-degrees: 45.0
      flight-animation: my_bolt_spin  # Optional. Sprite to loop for the projectile's lifetime

For the sprite sheet layout diagram, per-frame timing formats, light mask rules, YAML anchor/alias reuse, and override semantics — all identical here — see Mob Texture Configuration.

Rotation Alignment

Projectiles are drawn rotated to face their direction of travel. If your source art is drawn pointing in a direction other than straight right (0°), use texture-rotation-offset-degrees to correct the alignment:

projectile-texture-data:
  texture-rotation-offset-degrees: 45.0

This is applied as a fixed offset added to the computed travel-direction rotation, so it only needs to compensate for how the artwork itself is drawn — not for the projectile’s actual trajectory, which is handled automatically.

Flight Animation

By default a projectile holds a single static frame while flying (rotated to its direction of travel). Setting flight-animation to the name of one of the projectile’s sprites makes that animation loop for the projectile’s entire lifetime — a spinning throwing star, a flickering fireball, a pulsing magic bolt:

textures:
  - name: fire_bolt
    sprites:
      - name: fire_bolt_flight
        frame-count: 4
        frame-time-ms: 120
    frame-width: 32
    frame-height: 32
    projectile-texture-data:
      flight-animation: fire_bolt_flight

Notes:

• The animation starts automatically on every client as soon as the projectile appears — no scripting required — and works for players who join or come into range mid-flight.
• The name must match one of this projectile’s sprites entries exactly. An unknown name is ignored with a warning in the client log at load time.
• Per-frame timing via frame-durations-ms is honored, same as any other sprite.
• A one-shot animation triggered from a server script (entity:play_animation) temporarily takes over; the flight loop resumes when it finishes.

Complete Example

Based on the real shipped projectile texture:

textures:
  - name: wooden_arrow
    sprites:
      - name: wooden_arrow
        frame-count: 1
    frame-width: 32
    frame-height: 32
    projectile-texture-data:
      texture-rotation-offset-degrees: 45.0

Overrides

Your mod can replace the texture used for any projectile from another mod without changing that mod’s files. Add override with the full mod-namespaced name of the projectile to replace:

textures:
  - name: my_arrow
    override: OtherMod:arrow
    sprites:
      - name: my_arrow
        frame-count: 1
    frame-width: 32
    frame-height: 32
    projectile-texture-data:
      texture-rotation-offset-degrees: 45.0

• The name field is still required (it is used to locate your replacement PNG in your mod’s folder).
• Your texture file must match the frame dimensions of the original projectile.
• Your override entry fully replaces the animation configuration of the original, so you must redeclare all sprites, states, and timing you want to keep.