Bullet holes and Impact sounds

Bullet Holes and Impact Sounds

The bulletHoles feature adds customizable bullet-hole decals and impact sounds when bullets hit blocks. You can customize bullet-hole textures, sizes, lifetimes, limits, and impact sounds for different blocks and block tags.

Add the following feature inside your weapon's features array.

Example Configuration

{
  "type": "bulletHoles",
  "bullet_holes": {
    "enabled": true,
    "default_texture": "pointblankextra:textures/bullet_holes/default.png",
    "size": 0.12,
    "lifetime": 1200,
    "max_per_chunk": 128,
    "max_block_particles": 22,
    "max_distance": 16,

    "soundsPlayOnperBlockHit": {
      "enabled": true,
      "default": "pointblankextra:bullet_holes.default",
      "impact_volume": 1.9,
      "surface_sounds": {
        "minecraft:oak_planks": "minecraft:block.wood.hit",
        "minecraft:stone": "minecraft:block.stone.hit",
        "minecraft:dirt": "minecraft:block.gravel.hit",
        "minecraft:sand": "minecraft:block.sand.hit"
      },
      "tag_sounds": {
        "minecraft:logs": "minecraft:block.wood.hit",
        "c:glass_blocks": "pointblankextra:bullet_holes.glass",
        "minecraft:planks": "minecraft:block.wood.hit"
      }
    },

    "surface_textures": {
      "minecraft:oak_planks": "pointblankextra:textures/bullet_holes/wood.png",
      "minecraft:stone": "pointblankextra:textures/bullet_holes/stone.png",
      "minecraft:iron_block": "pointblankextra:textures/bullet_holes/metal.png"
    },

    "tag_textures": {
      "minecraft:logs": "pointblankextra:textures/bullet_holes/wood.png",
      "minecraft:planks": "pointblankextra:textures/bullet_holes/wood.png"
    }
  }
}

Bullet-Hole Settings

Option	Description
`enabled`	Enables or disables the bullet-hole feature.
`default_texture`	Texture used for blocks without a specific texture override.
`size`	Controls the size of bullet-hole decals.
`lifetime`	How long bullet holes remain before disappearing, in ticks.
`max_per_chunk`	Maximum number of bullet holes allowed per chunk.
`max_block_particles`	Controls the maximum number of block particles.
`max_distance`	Maximum distance at which bullet holes are displayed.

Custom Bullet-Hole Textures

You can assign different textures to individual blocks using surface_textures.

"surface_textures": {
  "minecraft:oak_planks": "pointblankextra:textures/bullet_holes/wood.png",
  "minecraft:stone": "pointblankextra:textures/bullet_holes/stone.png",
  "minecraft:iron_block": "pointblankextra:textures/bullet_holes/metal.png"
}

You can also assign textures to entire block tags using tag_textures.

"tag_textures": {
  "minecraft:logs": "pointblankextra:textures/bullet_holes/wood.png",
  "minecraft:planks": "pointblankextra:textures/bullet_holes/wood.png"
}

How it works:

surface_textures assigns a texture to a specific block.
tag_textures assigns a texture to blocks belonging to a specified tag.
default_texture provides the fallback texture.

Replace the texture paths with the resources you want to use.

Impact Sounds

The soundsPlayOnperBlockHit section allows you to configure sounds played when bullets hit blocks.

Option	Description
`enabled`	Enables or disables impact sounds.
`default`	Default sound used when no specific sound is configured.
`impact_volume`	Controls the volume of impact sounds.
`surface_sounds`	Assigns sounds to individual blocks.
`tag_sounds`	Assigns sounds to blocks belonging to specified tags.

Example:

"soundsPlayOnperBlockHit": {
  "enabled": true,
  "default": "pointblankextra:bullet_holes.default",
  "impact_volume": 1.9,
  "surface_sounds": {
    "minecraft:oak_planks": "minecraft:block.wood.hit",
    "minecraft:stone": "minecraft:block.stone.hit",
    "minecraft:dirt": "minecraft:block.gravel.hit",
    "minecraft:sand": "minecraft:block.sand.hit"
  },
  "tag_sounds": {
    "minecraft:logs": "minecraft:block.wood.hit",
    "c:glass_blocks": "pointblankextra:bullet_holes.glass",
    "minecraft:planks": "minecraft:block.wood.hit"
  }
}

default specifies the fallback impact sound.
surface_sounds lets you specify a sound for an individual block.
tag_sounds lets you specify a sound for an entire block tag.
impact_volume controls the volume of the impact sounds.

You can use registered Minecraft sounds or custom sounds registered by mods.

Tips

Use different textures for wood, stone, and metal to make bullet impacts look more realistic.
Use block tags when you want multiple blocks to share the same texture or impact sound.
Keep max_per_chunk and max_distance at reasonable values to help manage performance.
Set soundsPlayOnperBlockHit.enabled to false if you want bullet holes without impact sounds.
Set bullet_holes.enabled to false to disable the entire bullet-hole feature.

Registering Custom Impact Sounds

You can use your own custom sounds for bullet impacts by registering them in your content pack's sounds.json file.

⚠️ Important: All custom impact sound files MUST be converted to MONO (single-channel audio) from STEREO before being used. Stereo audio files may not work correctly for positional impact sounds.

1. Add Your Sound Files

Place your .ogg sound files inside your content pack's assets directory.

Make sure every sound file is converted to MONO, not STEREO.

For example:

assets/
└── pointblankextra/
    ├── sounds.json
    └── sounds/
        └── bullet_holes/
            ├── impact_default_1.ogg
            ├── impact_default_2.ogg
            └── impact_default_3.ogg

2. Register the Sounds

Open sounds.json and add an entry for your custom impact sounds.

Example:

{
  "bullet_holes.default": {
    "sounds": [
      "pointblankextra:bullet_holes/impact_default_1",
      "pointblankextra:bullet_holes/impact_default_2",
      "pointblankextra:bullet_holes/impact_default_3"
    ]
  }
}

Each entry references a sound file without the .ogg extension.

When multiple sounds are registered under the same sound event, Minecraft can select different variations when playing it.

3. Use the Sound in Your Weapon JSON

Once registered, reference the sound event in your bullet_holes configuration.

"soundsPlayOnperBlockHit": {
  "enabled": true,
  "default": "your_namespace:bullet_holes.default",
  "impact_volume": 1.9
}

Replace your_namespace:bullet_holes.default with the sound event identifier you registered in sounds.json.

4. Register Different Sounds for Different Surfaces

You can register separate sound events for different materials.

Example sounds.json:

{
  "bullet_holes.default": {
    "sounds": [
      "pointblankextra:bullet_holes/impact_default_1",
      "pointblankextra:bullet_holes/impact_default_2"
    ]
  },
  "bullet_holes.wood": {
    "sounds": [
      "pointblankextra:bullet_holes/wood_impact_1",
      "pointblankextra:bullet_holes/wood_impact_2"
    ]
  },
  "bullet_holes.glass": {
    "sounds": [
      "pointblankextra:bullet_holes/glass_impact_1",
      "pointblankextra:bullet_holes/glass_impact_2"
    ]
  }
}

You can then assign these sounds to specific blocks or block tags:

"soundsPlayOnperBlockHit": {
  "enabled": true,
  "default": "pointblankextra:bullet_holes.default",
  "impact_volume": 1.9,
  "surface_sounds": {
    "minecraft:oak_planks": "pointblankextra:bullet_holes.wood",
    "minecraft:glass": "pointblankextra:bullet_holes.glass"
  },
  "tag_sounds": {
    "minecraft:logs": "pointblankextra:bullet_holes.wood"
  }
}

Important Notes

All impact sound files MUST be MONO (single-channel), converted from STEREO if necessary.
Sound files must be in .ogg format.
Do not include .ogg when referencing a sound file in sounds.json.
The sound event identifier must match the identifier used in your weapon JSON.
Use surface_sounds for individual blocks and tag_sounds for block tags.
You can register multiple sound variations under one event to add variety to bullet impacts.

Navigation Menu

Repository navigation

Bullet holes and Impact sounds