ItemTrapAsset — Trap Barricade Definition

Advanced15-20 minutesWindowsVisual Studio

Overview

ItemTrapAsset extends ItemBarricadeAsset to define proximity and powered traps: spike traps, landmines, electric fences, tripwires, and similar. Traps deal configurable damage to different entity types, can be explosive or non-explosive, break bones, damage tires, and require power. Each trap has a setup delay (arming time after placement) and a cooldown (minimum time between damage applications).

Traps use EBuild.TRAP or similar build types. The damage system is comprehensive: eight separate damage values for different target types, plus an explosive mode with blast radius and launch speed.

Source code location: Unturned/Bundles/ItemTrapAsset.cs (164 lines), inheriting from ItemBarricadeAsset.cs (605 lines), ItemPlaceableAsset.cs (454 lines), and ItemAsset.cs (base).

Inheritance Chain**

ItemAsset → IArmorFalloff
  └─ ItemPlaceableAsset
       └─ ItemBarricadeAsset
            └─ ItemTrapAsset — damage table, trigger, cooldown, explosive mode

---

Class Definition

public class ItemTrapAsset : ItemBarricadeAsset
{
    protected float _range2;
    public float range2 => _range2;

    public float playerDamage;
    public float zombieDamage;
    public float animalDamage;
    public float barricadeDamage;
    public float structureDamage;
    public float vehicleDamage;
    public float resourceDamage;
    public float objectDamage;

    public float trapSetupDelay;
    public float trapCooldown;
    public float explosionLaunchSpeed;

    public System.Guid trapDetonationEffectGuid;
    private ushort _explosion2;

    public bool isBroken => _isBroken;
    public bool isExplosive => _isExplosive;
    public bool damageTires;
    public bool requiresPower;
}

---

Damage Table

Traps have the most comprehensive damage table in the item system — eight per-type damage values:

Field	.dat Key	Type	Default	Target
playerDamage	Player_Damage	float	—	Players
zombieDamage	Zombie_Damage	float	—	Zombies
animalDamage	Animal_Damage	float	—	Animals
barricadeDamage	Barricade_Damage	float	—	Barricades (other placed items)
structureDamage	Structure_Damage	float	—	Structures (walls, floors)
vehicleDamage	Vehicle_Damage	float	—	Vehicles
resourceDamage	Resource_Damage	float	—	Harvestable resources (trees, rocks)
objectDamage	Object_Damage	float	= resourceDamage	Environmental objects

Object Damage Fallback

if (p.data.ContainsKey("Object_Damage"))
    objectDamage = p.data.ParseFloat("Object_Damage");
else
    objectDamage = resourceDamage;

If Object_Damage is not explicitly set, it defaults to resourceDamage. This prevents the need to specify both values for traps that deal equal damage to resources and objects.

---

Trigger Configuration

Trigger Radius

.dat Key	Type	Default	Description
Range2	float	Required	Trigger radius in meters

_range2 = p.data.ParseFloat("Range2");

The Range2 key (distinct from Range which is the placement range inherited from ItemBarricadeAsset) defines the trigger/proximity radius. When an entity enters this radius, the trap triggers.

Setup Delay

.dat Key	Type	Default	Unit	Description
Trap_Setup_Delay	float	0.25	Seconds	Arming time after placement

trapSetupDelay = p.data.ParseFloat("Trap_Setup_Delay", defaultValue: 0.25f);

After a trap is placed, it waits trapSetupDelay seconds before becoming active. This prevents the placing player from immediately triggering their own trap. The default 0.25 seconds allows the player to step back.

Cooldown

.dat Key	Type	Default	Unit	Description
Trap_Cooldown	float	Required	Seconds	Minimum interval between damage

trapCooldown = p.data.ParseFloat("Trap_Cooldown");

The cooldown prevents traps from dealing damage every physics tick. Without a cooldown, a trap could deal thousands of DPS to a stationary target. Always set a cooldown appropriate for the trap type.

Warning: If Trap_Cooldown is 0 or unset, the trap deals damage every physics frame (typically 50× per second). A trap with Player_Damage 10 and no cooldown deals 500 DPS. Always set a cooldown.

---

Explosive Mode

_isExplosive = p.data.ContainsKey("Explosive");

.dat Key	Type	Default	Behavior
Explosive	flag	—	Trap explodes on trigger

Explosive Description

When isExplosive is true, the description shows explosive-style damage lines:

if (isExplosive)
{
    int sortOrder = DescSort_ExplosiveTrapDamage;
    builder.Append(...blast radius..., sortOrder++);
    builder.Append(...player damage..., sortOrder);
    builder.Append(...zombie damage..., sortOrder);
    builder.Append(...animal damage..., sortOrder);
    builder.Append(...barricade damage..., sortOrder);
    builder.Append(...structure damage..., sortOrder);
    builder.Append(...vehicle damage..., sortOrder);
    builder.Append(...resource damage..., sortOrder);
    builder.Append(...object damage..., sortOrder);
}

Explosive traps use ItemDescription_Explosion* localization keys (same family as explosive charges).

Non-Explosive Description

When isExplosive is false, the description shows damage values selectively:

else
{
    if (isBroken) { /* breaks bones */ }
    if (damageTires) { /* damages tires */ }
    if (requiresPower) { /* requires power */ }

    if (playerDamage > 0.0f) { /* player damage */ }
    if (zombieDamage > 0.0f) { /* zombie damage */ }
    if (animalDamage > 0.0f) { /* animal damage */ }
}

Only non-zero damage values are shown. Keywords (broken bones, tire damage, power) are shown first as context, then damage stats.

---

Additional Flags

Broken Bones

.dat Key	Type	Default	Behavior
Broken	flag	—	Trap breaks bones on trigger

_isBroken = p.data.ContainsKey("Broken");

When true, the trap breaks the target's bones (inflicts the broken leg/arm status effect) in addition to dealing damage.

Damage Tires

.dat Key	Type	Default	Behavior
Damage_Tires	flag	—	Trap damages vehicle tires

damageTires = p.data.ContainsKey("Damage_Tires");

When true, the trap specifically damages vehicle tires. Useful for spike strips and caltrops.

Requires Power

.dat Key	Type	Default	Behavior
Requires_Power	bool	false	Trap needs electricity

requiresPower = p.data.ParseBool("Requires_Power");

When true, the trap only functions when connected to a power source (generator). Electric fences, laser grids, and powered spike traps use this.

---

Explosion Effect and Launch Speed

Detonation Effect

_explosion2 = p.data.ParseGuidOrLegacyId("Explosion2", out trapDetonationEffectGuid);

.dat Key	Type	Purpose
Explosion2	GUID/ID	Effect played on detonation

Explosion2 is distinct from Explosion (which is the barricade destruction effect). Explosion2 is the trap-specific detonation effect — the particle/sound effect played when the trap triggers.

Explosion Launch Speed

.dat Key	Type	Default	Description
Explosion_Launch_Speed	float	playerDamage * 0.1	Physics launch velocity on detonation

explosionLaunchSpeed = p.data.ParseFloat("Explosion_Launch_Speed",
    defaultValue: playerDamage * 0.1f);

When an explosive trap detonates, entities within range are launched with this velocity. Default is 10% of player damage — a trap dealing 100 player damage launches at velocity 10.

---

BuildDescription — Inventory Tooltip

The description splits into two major modes:

Explosive Mode

Shows all 8 damage values in a block, using explosion-specific localization keys.

Non-Explosive Mode

Shows keywords (breaks bones, damages tires, requires power) first, then non-zero damage values for players, zombies, and animals only. Barricade/structure/vehicle/resource/object damage is not shown for non-explosive traps.

---

BuildCargoData — Wiki Export

CargoDeclaration data = builder.GetOrAddDeclaration("Trap");
data.Append("GUID", GUID);
data.Append("Range2", range2);
data.Append("Player_Damage", playerDamage);
data.Append("Zombie_Damage", zombieDamage);
data.Append("Animal_Damage", animalDamage);
data.Append("Barricade_Damage", barricadeDamage);
data.Append("Structure_Damage", structureDamage);
data.Append("Vehicle_Damage", vehicleDamage);
data.Append("Resource_Damage", resourceDamage);
data.Append("Object_Damage", objectDamage);
data.Append("Trap_Setup_Delay", trapSetupDelay);
data.Append("Trap_Cooldown", trapCooldown);
data.Append("Explosion2", explosion2);
data.Append("Explosion_Launch_Speed", explosionLaunchSpeed);
data.Append("Broken", isBroken);
data.Append("Explosive", isExplosive);
data.Append("Damage_Tires", damageTires);
data.Append("Requires_Power", requiresPower);

---

.dat File Reference — Trap-Specific

.dat Key	Type	Default	Notes
Range2	float	Required	Trigger radius
Player_Damage	float	Required	Damage to players
Zombie_Damage	float	Required	Damage to zombies
Animal_Damage	float	Required	Damage to animals
Barricade_Damage	float	Required	Damage to barricades
Structure_Damage	float	Required	Damage to structures
Vehicle_Damage	float	Required	Damage to vehicles
Resource_Damage	float	Required	Damage to resources
Object_Damage	float	= resourceDamage	Damage to objects
Trap_Setup_Delay	float	0.25	Arming delay
Trap_Cooldown	float	Required	Damage interval
Explosion2	GUID/ID	—	Detonation effect
Explosion_Launch_Speed	float	playerDamage * 0.1	Launch velocity
Broken	flag	—	Breaks bones
Explosive	flag	—	Explosion mode
Damage_Tires	flag	—	Tire damage
Requires_Power	bool	false	Needs electricity

---

Modding Example — Spike Trap .dat

GUID a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Type Barricade
Build Trap
Health 100
Range 4
Radius 0.3
Offset 0.05
Range2 1.5
Player_Damage 20
Zombie_Damage 20
Animal_Damage 20
Trap_Setup_Delay 0.5
Trap_Cooldown 2.0
Broken

1.5m trigger, 20 damage, 2-second cooldown, breaks bones, 0.5s arm delay.

---

Modding Example — Landmine .dat

GUID f1e2d3c4b5a69788796a5b4c3d2e1f0a
Type Barricade
Build Trap
Health 50
Range 4
Radius 0.3
Offset 0.05
Range2 3.0
Player_Damage 100
Zombie_Damage 150
Animal_Damage 100
Barricade_Damage 200
Structure_Damage 150
Vehicle_Damage 300
Resource_Damage 100
Explosive
Trap_Setup_Delay 1.0
Trap_Cooldown 0.0
Explosion2 <effect_guid>
Explosion_Launch_Speed 25

3m trigger, explosive, 100–300 damage across types, 25 launch speed, 1.0s arm delay. Cooldown 0 (single-use — detonates once).

---

Modding Example — Electric Fence .dat

GUID d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
Type Barricade
Build Trap
Health 200
Range 4
Radius 0.5
Offset 0.1
Range2 0.5
Player_Damage 15
Zombie_Damage 15
Animal_Damage 15
Trap_Setup_Delay 0.0
Trap_Cooldown 1.0
Requires_Power true

0.5m trigger (touch range), 15 damage, 1.0s cooldown, requires power, instant arm (no setup delay).

---

Common Issues

1. Trap cooldown missing: Without Trap_Cooldown, traps deal damage every physics tick. A trap with 20 damage and no cooldown deals ~1000 DPS. Always set a cooldown.

2. Setup delay too short: Trap_Setup_Delay 0 means the trap arms instantly. The placing player triggers it immediately. At minimum, use 0.25–0.5 seconds.

3. Object_Damage fallback: Object_Damage defaults to resourceDamage. If your trap deals different damage to resources vs objects, set both explicitly.

4. Explosive traps show all damage types: In explosive mode, all 8 damage values are shown in the tooltip regardless of whether they're zero. For non-explosive traps, only non-zero player/zombie/animal damage is shown.

5. Explosion2 vs Explosion: Explosion is the barricade destruction effect (inherited from ItemBarricadeAsset). Explosion2 is the trap-specific detonation effect. These are separate GUIDs and serve different purposes.

Document history

Version	Date	Author	Notes
1.0	2026-07-28	57 Studios	Initial publication. Full trap asset documentation including damage table, explosive/non-explosive modes, and modding examples.