ItemSentryAsset — Sentry Turret Definition

Advanced20-25 minutesWindowsVisual Studio

Overview

ItemSentryAsset extends ItemStorageAsset to define automated sentry turrets. A sentry is a storage barricade (inventory for ammunition and weapon) with autonomous targeting and firing capability. The sentry scans within a detection radius, locks onto valid targets, fires using a stored weapon, and manages ammunition and quality consumption independently.

Sentries use EBuild.SENTRY or EBuild.SENTRY_FREEFORM and inherit the full ItemStorageAsset inventory grid for ammo/weapon storage. The turret does not need to be manually reloaded — it draws ammunition from its internal inventory.

Source code location: Unturned/Bundles/ItemSentryAsset.cs (224 lines), inheriting from ItemStorageAsset.cs (149 lines), ItemBarricadeAsset.cs (605 lines), ItemPlaceableAsset.cs (454 lines), and ItemAsset.cs (base).

Inheritance Chain

ItemAsset → IArmorFalloff
  └─ ItemPlaceableAsset
       └─ ItemBarricadeAsset
            └─ ItemStorageAsset — inventory grid (ammo + weapon storage)
                 └─ ItemSentryAsset — targeting, firing, ammo management

---

ESentryMode

public enum ESentryMode { NEUTRAL, FRIENDLY, HOSTILE }

Mode	Behavior
NEUTRAL	Default. Targets hostiles only
FRIENDLY	Never targets group members or allies
HOSTILE	Targets everyone including group members

Parsing

if (p.data.ContainsKey("Mode"))
    _sentryMode = (ESentryMode) System.Enum.Parse(typeof(ESentryMode), p.data.GetString("Mode"), true);
else
    _sentryMode = ESentryMode.NEUTRAL;

---

Targeting Configuration

Core Targeting Fields

Field	.dat Key	Default	Description
detectionRadius	Detection_Radius	48.0	Target acquisition range in meters
targetLossRadius	Target_Loss_Radius	detectionRadius * 1.2	Target release range in meters
SweepHalfYaw	Sweep_Yaw / 2	60.0	Half-angle of yaw sweep arc from forward
SweepPeriod	Sweep_Period	2π (TAU)	Full sweep cycle time in seconds
requiresPower	Requires_Power	true	Needs electricity to function

Target Loss Radius Validation

targetLossRadius = p.data.ParseFloat("Target_Loss_Radius", defaultValue: detectionRadius * 1.2f);

if (targetLossRadius < detectionRadius - 0.00001f)
{
    ReportAssetError($"Target_Loss_Radius ({targetLossRadius}) is less than Detection_Radius ({detectionRadius})");
}

targetLossRadius must be greater than or equal to detectionRadius. If it's smaller, the sentry would lose the target immediately after acquiring it, causing erratic behavior. An asset error is reported when this validation fails.

Sweep Configuration

.dat Key	Default	Calculation
Sweep_Yaw	120.0	SweepHalfYaw = Sweep_Yaw / 2
Sweep_Period	2π	Direct assignment

The sentry yaws left and right within ±SweepHalfYaw degrees from its forward direction. A full left-right-left sweep cycle takes SweepPeriod seconds.

---

Targeting Filters

Field	.dat Key	Default	Description
CanTargetPlayers	Target_Players	true	Can attack players
CanTargetZombies	Target_Zombies	true	Can attack zombies
CanTargetAnimals	Target_Animals	true	Can attack animals
CanTargetVehicles	Target_Vehicles	true	Can attack vehicles
BypassesPvEMode	Sentry_Bypasses_PvE	false	Can damage players/vehicles in PvE
CanReactToAttacks	React_To_Attacks	false	Immediately targets attacker

BypassesPvEMode

When true, the sentry can damage players and vehicles even on PvE servers where player-to-player damage is disabled. By default (false), sentries respect PvE mode and won't damage players.

CanReactToAttacks

When true, if a player attacks the sentry, the sentry immediately targets the attacker regardless of its current target. This enables sentries with a "retaliation" behavior rather than purely passive scanning.

---

Ammo and Quality Management

Infinite Modes

Field	.dat Key	Default	Description
infiniteAmmo	Infinite_Ammo	false	Never consumes ammunition
infiniteQuality	Infinite_Quality	false	Never degrades weapon quality

When infiniteAmmo is true, the sentry fires without consuming any ammunition from its inventory. The weapon still needs to be present in storage.

When infiniteQuality is true, the sentry's weapon never loses quality from firing.

Consumption Probabilities

Field	.dat Key	Default	Range	Description
AmmoConsumptionProbability	AmmoConsumptionProbability	1.0	[0, 1]	Per-shot chance to consume ammo
QualityConsumptionProbability	QualityConsumptionProbability	1.0	[0, 1]	Per-shot chance to degrade quality

These provide granular control between "infinite" and "always consumes." A value of 0.5 means 50% of shots use ammo — effectively doubling the ammo duration without full infinite mode.

Description Display

if (!infiniteAmmo && AmmoConsumptionProbability < 1.0f)
{
    builder.Append(localization.format("ItemDescription_AmmoConsumptionProbability",
        AmmoConsumptionProbability.ToString("P0")), DescSort_Important);
}

if (!infiniteQuality && QualityConsumptionProbability < 1.0f)
{
    builder.Append(localization.format("ItemDescription_QualityConsumptionProbability",
        QualityConsumptionProbability.ToString("P0")), DescSort_Important);
}

Probabilities are displayed as percentages (e.g., "75%").

---

Target Acquisition Flow

1. Scan: Sentry rotates within its yaw sweep arc
2. Detect: Entities within detectionRadius are evaluated against targeting filters
3. Lock: Closest valid target is locked; targetAcquiredEffect plays
4. Engage: Sentry fires at locked target using its stored weapon
5. Release: Target exits targetLossRadius, dies, or line-of-sight breaks; targetLostEffect plays

Target Acquired/Lost Effects

public AssetReference<EffectAsset> targetAcquiredEffect;
public AssetReference<EffectAsset> targetLostEffect;

Field	.dat Key	Default Effect GUID
targetAcquiredEffect	Target_Acquired_Effect	ab5f0056b54545c8a051159659da8bea (Target_On)
targetLostEffect	Target_Lost_Effect	288b98b718084699ba3653c592e57803 (Target_Off)

These effects play when the sentry locks onto and releases a target. The defaults are vanilla target-acquired/target-lost sound effects.

---

Ammo Management Flow

1. Scans inventory for a compatible weapon (any ItemGunAsset)
2. Transfers weapon from inventory to internal weapon slot
3. Scans remaining inventory for compatible magazines
4. Fires using weapon's firing logic, consuming ammo from its own tracking
5. Reloads from magazine items in inventory when internal ammo reaches 0
6. Consumption check: Random.value < AmmoConsumptionProbability per shot

The sentry does not use a magazine item directly — it tracks ammo internally and reloads from magazines in storage.

---

BuildDescription — Inventory Tooltip

if (!infiniteAmmo && AmmoConsumptionProbability < 1.0f)
    builder.Append(..., DescSort_Important);

if (!infiniteQuality && QualityConsumptionProbability < 1.0f)
    builder.Append(..., DescSort_Important);

Only non-default consumption probabilities are shown. Full consumption (1.0) and infinite modes (infiniteAmmo = true) are not displayed.

---

BuildCargoData — Wiki Export

CargoDeclaration data = builder.GetOrAddDeclaration("Sentry");
data.Append("GUID", GUID);
data.Append("Mode", sentryMode);
data.Append("Requires_Power", requiresPower);
data.Append("Infinite_Ammo", infiniteAmmo);
data.Append("Infinite_Quality", infiniteQuality);
data.Append("AmmoConsumptionProbability", AmmoConsumptionProbability);
data.Append("QualityConsumptionProbability", QualityConsumptionProbability);
data.Append("Detection_Radius", detectionRadius);
data.Append("Target_Loss_Radius", targetLossRadius);
data.Append("Target_Acquired_Effect", targetAcquiredEffect);
data.Append("Target_Lost_Effect", targetLostEffect);

---

.dat File Reference — Sentry-Specific

.dat Key	Type	Default	Notes
Mode	enum	NEUTRAL	NEUTRAL, FRIENDLY, HOSTILE
Detection_Radius	float	48.0	Acquisition range (meters)
Target_Loss_Radius	float	detectionRadius * 1.2	Release range (must be ≥ detection)
Sweep_Yaw	float	120.0	Total yaw sweep (degrees)
Sweep_Period	float	2π	Sweep cycle duration (seconds)
Requires_Power	bool	true	Need electricity
Infinite_Ammo	bool	false	Never consume ammo
Infinite_Quality	bool	false	Never degrade weapon
AmmoConsumptionProbability	float	1.0	Per-shot ammo usage chance
QualityConsumptionProbability	float	1.0	Per-shot quality loss chance
Target_Players	bool	true	Target players
Target_Zombies	bool	true	Target zombies
Target_Animals	bool	true	Target animals
Target_Vehicles	bool	true	Target vehicles
Sentry_Bypasses_PvE	bool	false	Damage in PvE
React_To_Attacks	bool	false	Retaliate against attacker
Target_Acquired_Effect	AssetRef	Vanilla default	Effect on target lock
Target_Lost_Effect	AssetRef	Vanilla default	Effect on target release

---

Modding Example — Basic Sentry .dat

GUID a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
Type Barricade
Build Sentry
Health 300
Range 4
Storage_X 4
Storage_Y 4
Mode NEUTRAL
Detection_Radius 48
Target_Players true
Target_Zombies true
Requires_Power true

48m detection range, targets players and zombies, 4×4 ammo storage, requires power.

---

Modding Example — Hostile Sentry .dat

GUID f1e2d3c4b5a69788796a5b4c3d2e1f0a
Type Barricade
Build Sentry
Health 500
Range 4
Storage_X 6
Storage_Y 6
Mode HOSTILE
Detection_Radius 72
Target_Loss_Radius 90
Sweep_Yaw 360
Sweep_Period 4.0
Target_Players true
Target_Zombies true
Target_Animals true
Target_Vehicles true
Sentry_Bypasses_PvE true
Requires_Power false
Infinite_Ammo true

Hostile sentry: 72m detection, 90m loss radius, full 360° sweep, targets everything including PvE, no power needed, infinite ammo. A "raid boss" style turret.

---

Modding Example — Eco Sentry .dat

GUID d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
Type Barricade
Build Sentry
Health 200
Range 4
Storage_X 3
Storage_Y 3
Mode FRIENDLY
Detection_Radius 36
Infinite_Quality true
AmmoConsumptionProbability 0.25
QualityConsumptionProbability 0.0

Friendly-mode sentry: 36m range, only 25% of shots consume ammo (quadruple ammo efficiency), weapon never degrades.

---

Common Issues

1. Target loss radius < detection radius: Results in an asset error and erratic sentry behavior. targetLossRadius must be ≥ detectionRadius. The validation enforces this.

2. Sweep_Yaw confusion: The .dat key is Sweep_Yaw (full arc), but the internal field is SweepHalfYaw (half-arc). Setting Sweep_Yaw 180 gives SweepHalfYaw = 90 — sentry sweeps ±90° from forward.

3. No ammo consumption: If AmmoConsumptionProbability is 0, the sentry never uses ammo. This is distinct from Infinite_Ammo true — both achieve the same result but through different paths.

4. Sentry not firing: Verify a compatible weapon exists in storage. Sentries scan for ItemGunAsset instances. If no gun is found, the sentry will scan but never engage.

5. Power not connecting: Requires_Power true requires an electrical source within wire range. If no powered generator or other source is connected, the sentry won't function.

Document history

Version	Date	Author	Notes
1.0	2026-07-28	57 Studios	Initial publication. Full sentry asset documentation including targeting system, ammo/quality management, and modding examples.