Block Breaking, Restoration, and Craters

Duck Shot has two destruction lanes that creators often mix together:

1. repeated weapon hits damaging world blocks over time
2. explosive payloads carving temporary craters and rebuilding them later

They can work together, but they are not the same system.

The two layers

Layer 1: hit-based block damage

This comes from block_breaking.yml plus the per-weapon block_breaking section.

Use this when you want things like:

• glass shattering under fire
• doors getting shot out
• planks eventually breaking under sustained pressure
• mounted weapons chewing through lighter cover

Layer 2: crater carving and rebuild

This comes from projectile.explosion.blocks.

Use this when you want:

• a mortar strike opening a temporary crater
• a rocket blasting a hole in terrain
• shrapnel debris and rebuild timing
• cinematic destruction that does not permanently grief the world

How hit-based block damage works

When a projectile hits a block, Duck Shot:

1. finds the first matching rule in block_breaking.yml
2. applies that weapon's damage_per_hit
3. breaks the block if the accumulated damage reaches the rule's health

That means the global rule file answers:

• what materials can break
• how much health they have
• whether neighbors connect and break together
• how long they stay gone before restoring

The weapon file answers:

• whether this weapon participates at all
• how hard each hit should count
• whether it should be restricted to only certain rule names

Reading the global rule file

The example block_breaking.yml is already a good example of sane server defaults.

It includes rules like:

• glass
• iron_openables
• wooden_openables
• leaves
• planks
• bricks

Example interpretation

• glass uses health: 1.0, so one meaningful hit can shatter it
• wooden doors and gates also break easily, but restore later
• planks are much tougher with health: 12.0
• bricks are tougher again with health: 18.0
• iron doors are effectively protected with an extreme health value

That is exactly the kind of material hierarchy most servers want:

• light cover feels breakable
• heavier cover feels earned
• protected utility blocks do not get accidentally deleted

Connected break modes

Rules can also define how nearby blocks should break together.

NONE

Only the hit block breaks.

Best for:

• planks
• bricks
• tougher cover

LIMITED

Breaks nearby connected blocks up to a cap.

Best for:

• leaves
• light decorative materials

ALL

Breaks the full connected component, still bounded by safety caps.

Best for:

• window panes
• stained glass walls
• thin breakable cover that should collapse fast

The per-weapon block-breaking section

This is the weapon-side entry point:

block_breaking:
  enabled: true
  damage_per_hit: 1.0
  allowed_rule_names: [glass, wooden_openables]

enabled

If false, the weapon will not use the hit-based block damage system.

damage_per_hit

This is the single most important feel knob.

It answers the question:

How much cover pressure should one hit from this item create?

allowed_rule_names

Use this when a weapon should only affect certain material groups.

That is helpful when you want a specialized breach tool without letting it chew through everything else in the world.

What damage_per_hit feels like in practice

These are good starting mental models, not hard rules:

Around 1.0

Feels like:

• normal firearms affecting fragile cover
• breaking glass, leaves, and light doors cleanly
• not instantly drilling through heavier structures

Around 2.0 to 4.0

Feels like:

• a stronger shotgun or breach-oriented weapon
• fast pressure on planks or lighter barricades
• more obvious anti-cover utility

Around 6.0 to 8.0

Feels like:

• heavy emplacement fire
• anti-material pressure
• something that can punish cover if players stay behind it too long

This is why values that feel fine on a mounted gun can feel absurd on a sidearm.

Good rule restrictions

Breach tool

Restrict it to:

• wooden_openables
• maybe glass

Do not let it chew through bricks unless that is truly intended.

Anti-cover LMG

Allow:

• glass
• wooden openables
• planks

Maybe keep bricks off-limits if you want defensive cover to still matter.

Decorative utility explosions

Leave hit-based breaking off entirely and rely on particles and sound instead.

Crack overlay and decay

The global block-breaking system can show client-side crack feedback before a block actually breaks.

Important knobs include:

• damage.decay_seconds
• crack_overlay.radius

Interpretation:

• shorter decay means blocks "heal" if fire stops quickly
• longer decay means sustained suppression matters more
• larger crack radius means more players can read the world damage state

This is one of the reasons the system feels understandable in play instead of invisible.

Restoration and persistence

Once a block breaks, Duck Shot stores the original BlockData and schedules a rebuild.

Important global knobs:

• restore.default_delay_seconds
• restore.max_blocks_per_tick
• restore.bottom_up
• restore.outside_in
• persistence.file
• persistence.autosave_interval_seconds

What these change

• delay controls how long damage stays visible
• max blocks per tick helps you manage rebuild cost on active servers
• bottom-up rebuild usually looks more natural for craters and floors
• outside-in changes the visual feel of the restoration sweep
• persistence keeps temporary damage from becoming permanent if the server restarts

That last point is one of the reasons Duck Shot can support cinematic destruction without turning into map grief.

Crater carving from explosions

Explosive terrain work lives under:

projectile:
  explosion:
    blocks:
      enabled: true

That is where you define things like:

• crater shape
• radius
• max depth
• max blocks
• rebuild timing
• debris shrapnel

The example MORTAR_STATION.yml is a strong real example:

projectile:
  explosion:
    blocks:
      enabled: true
      shape: SPHERE
      radius_x: 5.6
      radius_y: 4.4
      radius_z: 5.6
      max_depth: 6
      max_blocks: 300
      rebuild_delay_ticks: 60
      rebuild_duration_ticks: 180

What the crater knobs actually do

shape

Controls the general carve style.

Use crater-like shapes for ground impacts and hemisphere-style shapes for walls or angled surfaces.

radius_x, radius_y, radius_z

Define the size of the carve volume.

Wider radii feel more cinematic, but can turn into noise if the actual weapon fantasy is supposed to feel precise.

max_depth

Prevents the crater from tunneling too far downward.

max_blocks

Your main safety cap. Keep this sane.

rebuild_delay_ticks

How long the hole stays open before rebuild starts.

rebuild_duration_ticks

How long the rebuild takes once it begins.

Short duration feels snappier.

Long duration feels more dramatic and war-torn.

Shrapnel is visual storytelling, not just noise

Crater carving can also spawn display-based debris with blocks.shrapnel.

This is how you get:

• dirt and block fragments flying out
• sampled terrain materials
• a more expensive-looking blast

Do not confuse shrapnel with actual world damage. It is part of the effect layer.

That is useful because you can make an explosion look violent without always increasing real destruction.

Airstrike and explosive safety

Some explosive payloads intentionally avoid terrain damage even when they are visually intense.

For example:

• AIRSTRIKE_MARKER.yml uses break_blocks: false
• its airstrike payload keeps use_custom_block_break: false

That is the right call for:

• support items
• marking tools
• dramatic battlefield effects on public servers

Not every explosion should carve terrain just because the effect looks large.

Practical recipes

Recipe: breakable glass and doors on a live combat server

Use:

• hit-based block breaking
• easy global rules for glass and wooden openables
• damage_per_hit around normal firearm values
• short restore timers

This gives you readable breach moments without permanent grief.

Recipe: mounted gun that pressures wooden cover

Use:

• hit-based block breaking
• higher damage_per_hit
• allowed rules including planks
• bricks still protected or much tougher

This makes the emplacement scary without flattening the whole map.

Recipe: temporary mortar crater

Use:

• projectile.explosion.blocks.enabled: true
• limited max_blocks
• real rebuild delay and duration
• shrapnel enabled

This is where Duck Shot really shines for cinematic support weapons.

Recipe: flashy airstrike with no permanent terrain damage

Use:

• airstrike payloads
• strong sounds and particles
• telegraph messaging
• break_blocks: false
• use_custom_block_break: false

That is the safer public-server version.

Common mistakes

Letting the first global rule be too broad

Remember: first matching rule wins.

If a wildcard rule is too high in the file, a lot of materials can end up behaving wrong.

Setting damage_per_hit before deciding what the weapon fantasy is

Ask first:

Is this a pressure weapon, a breach tool, or just a firearm with cosmetic world feedback?

Huge crater caps on busy servers

If the carve budget is too high, performance becomes the real enemy instead of the weapon system.

Permanent terrain damage by accident

If you want live-server-safe destruction, always think through rebuild timing and whether the blast should be cosmetic or structural.

Related pages

• projectiles and Impacts
• throwables, Explosives, and Flashbangs
• sky Select, Airstrikes, and Support Callers