ItemTireAsset — Tire Service Items

Advanced20-25 minutesWindowsVisual Studio

Replacing damaged wheels and upgrading vehicle performance in Unturned involves understanding how ItemTireAsset discriminates between ADD and REMOVE modes, validates wheel hub compatibility, and integrates with the vehicle physics system through UseableTire. ItemTireAsset defines tire items — tools for adding and removing wheels from vehicles. It extends ItemVehicleRepairToolAsset, inheriting repair tool functionality while adding a mode discriminator that completely changes the item's behavior.

Source code location: Unturned/Bundles/ItemTireAsset.cs

Inheritance Chain

ItemAsset
  → ItemToolAsset
    → ItemVehicleRepairToolAsset
      → ItemTireAsset

ItemVehicleRepairToolAsset provides the vehicle-repairing base behavior and shares the useDurability property (quality degrades with use). ItemTireAsset extends this to add wheel-specific interaction.

Class Definition

public enum EUseableTireMode { ADD, REMOVE }

public class ItemTireAsset : ItemVehicleRepairToolAsset
{
    private EUseableTireMode _mode;
    public EUseableTireMode mode => _mode;

    public override bool shouldFriendlySentryTargetUser =>
        mode == EUseableTireMode.REMOVE;

    public override bool canBeUsedInSafezone(SafezoneNode safezone, bool byAdmin)
    {
        return mode == EUseableTireMode.ADD;
    }
}

Core Fields

Field	Type	.dat Key	Description
_mode	EUseableTireMode	Mode	ADD (place tire) or REMOVE (remove tire)

Mode Behavior Comparison

Property	ADD Mode	REMOVE Mode
Action	Places a tire on an empty wheel hub	Removes an existing tire
Sentry targeting	No	Yes
Safezone allowed?	Always allowed	Blocked
Quality degrades?	No (consumes item)	Yes
Useable class	UseableTire	UseableTire
Tire ID check	Must match VehicleAsset.tireID	Any tire tool works

Sentry Targeting

public override bool shouldFriendlySentryTargetUser => mode == EUseableTireMode.REMOVE;

Friendly sentries consider tire removal a hostile act (destroying a vehicle's mobility). Tire placement is neutral/constructive.

Safezone Rules

public override bool canBeUsedInSafezone(SafezoneNode safezone, bool byAdmin)
{
    return mode == EUseableTireMode.ADD;
}

Tire placement is always allowed in safezones (constructive). Tire removal is blocked (destructive). Admins bypass this restriction through the byAdmin parameter in the parent class.

PopulateAsset

public override void PopulateAsset(in PopulateAssetParameters p)
{
    base.PopulateAsset(in p);

    _mode = (EUseableTireMode)Enum.Parse(typeof(EUseableTireMode),
        p.data.GetString("Mode"), true);
}

The Mode key is required and parsed case-insensitively. Valid values are "ADD" and "REMOVE".

UseableTire Runtime Behavior

The UseableTire class implements the actual wheel interaction:

ADD Mode — Tire Placement

1. Raycast: Camera forward ray detects a WheelCollider component on the vehicle.
2. Hub state check: The wheel hub must be empty (no existing tire).
3. Tire ID validation: ItemTireAsset.id must match the vehicle's tireID (default 1451 for vanilla).
4. Tire prefab instantiation: The tire prefab from the vehicle asset's wheel configuration is instantiated.
5. Collider enablement: The WheelCollider is enabled on the appropriate hub.
6. Physics update: The wheel configuration's physics properties (mass, damping, suspension) are applied.
7. Item consumption: The tire item is decremented from inventory (stack size reduced).

REMOVE Mode — Tire Removal

1. Raycast: Camera forward ray detects an existing tire on a vehicle.
2. Hub state check: The wheel hub must have a tire (non-empty).
3. Tire detachment: The existing tire GameObject is destroyed.
4. WheelCollider disable: The WheelCollider on the hub is disabled.
5. Quality degradation: The tool's quality decreases (inherited from ItemVehicleRepairToolAsset.useDurability).
6. No tire ID check: Any tire tool in REMOVE mode works on any wheel.

Wheel Hub Matching

The UseableTire matches wheel hubs by hierarchy:

1. The vehicle's prefab contains a "Tires" transform with children named Tire_N.
2. Each Tire_N has a WheelCollider component (or inherits from the wheel configuration).
3. The raycast detects the WheelCollider and identifies its hub index.
4. The hub index is used to check current state and instantiate/destroy the visual wheel model.

Tire Compatibility

The vehicle determines which tire item is compatible via VehicleAsset.tireID:

Vehicle	Default tireID	Vanilla Tire ID
All vehicles	1451	Tire item

Custom vehicles can specify a different tireID to require custom tires. The tire item's id must match the vehicle's tireID for ADD mode to succeed. REMOVE mode does not check tire ID — any socket wrench (REMOVE tire tool) works on any tire.

Vehicle Effects of Tire Changes

Missing Tires Cause:

• Reduced traction (skidding).
• Uneven vehicle stance (visual model tilts toward the missing wheel).
• Increased steering difficulty.
• Increased collision damage to the exposed hub.
• Slower top speed (friction imbalance).

Tire Replacement Improves:

• Traction restoration.
• Level vehicle stance.
• Normal steering response.
• Reduced collision risk.
• Normal top speed.

Multiple missing tires compound handling penalties. Each replacement incrementally restores normal behavior.

Cargo Data Export

ItemTireAsset does not override BuildCargoData. Data is exported by the parent chain (ItemVehicleRepairToolAsset → ItemToolAsset → ItemAsset). The mode field is not exported to any Cargo table and must be inferred from the asset's configuration by wiki tools.

Common Issues

1. Tire ID mismatch silent failure — VehicleAsset.tireID defines which ItemTireAsset is compatible. If the tire's mode doesn't match what the vehicle expects or the IDs don't match, the interaction silently fails with no feedback to the player.
2. REMOVE doesn't check tire ID — In REMOVE mode, any tire tool works regardless of tireID. A custom tire can be removed by a standard wrench. This is intentional (gameplay convenience for anti-griefing) but may surprise modders who expect removal to require matching tools.
3. Quality degrades on REMOVE only — Inherited from ItemVehicleRepairToolAsset.useDurability, quality only decreases when removing tires. ADD mode consumes the item (decrements amount) rather than degrading quality.
4. ADD in safezone, REMOVE blocked — The canBeUsedInSafezone override returns false for REMOVE mode. Admins are exempt through the parameter but regular players cannot remove tires in safezones even from their own vehicles.
5. Wheel hub validation — The raycast must hit a valid WheelCollider on a recognized vehicle. If the vehicle's wheel colliders are misconfigured, the tire interaction fails with no error.

Worked Code Example: Tire Compatibility Checker

using SDG.Unturned;
using UnityEngine;

public static class TireCompatibilityChecker
{
    /// <summary>
    /// Returns all valid wheel hub positions on a vehicle, useful
    /// for UI indicators showing where tires can be placed.
    /// </summary>
    public static List<Transform> GetWheelHubs(VehicleAsset vehicleAsset)
    {
        List<Transform> hubs = new List<Transform>();
        // Wheel colliders define valid hub positions
        foreach (WheelCollider wheel in vehicleAsset.GetComponentsInChildren<WheelCollider>())
        {
            if (wheel != null && wheel.transform != null)
                hubs.Add(wheel.transform);
        }
        return hubs;
    }

    /// <summary>
    /// Validates whether a tire item is compatible with a specific
    /// vehicle's wheel hub, checking both tire ID and mode.
    /// </summary>
    public static bool IsTireCompatible(ItemTireAsset tire, VehicleAsset vehicle, WheelCollider hub)
    {
        if (tire == null || vehicle == null || hub == null)
            return false;
        return vehicle.tireID == tire.id;
    }
}

Mermaid Diagram: Tire Interaction Flow

Comparison: Tire Tool vs. Other Vehicle Service Tools

Feature	ItemTireAsset	VehicleRepairTool	VehicleLockpickTool	VehiclePaintTool
Primary function	Wheel ADD/REMOVE	Repair damage	Unlock vehicle	Paint color
Mode system	ADD/REMOVE toggle	None	Lock pick attempt	Color selection
Compatibility	vehicle.tireID match	Any vehicle	Any locked vehicle	Paintable vehicles
Item consumed	ADD: yes, REMOVE: no	Degrade quality	Consumed on success	Degrade quality
Safezone blocked	REMOVE mode	No	No	No
Sentinel hostility	Based on mode	Hostile when held	Hostile when held	Non-hostile

Failure Modes and Common Mistakes

6. Tire ADD failing on "full" vehicle — A vehicle has a fixed number of wheel hubs. If all hubs are occupied, ADD mode silently fails. The player consumes no item but receives no feedback — they may try repeatedly believing the interaction is bugged.

7. REMOVE producing wrong tire item — When REMOVE succeeds, the removed tire becomes an item. If a custom tire was attached (different from the vehicle's default tireID), the returned item matches the attached tire's ID, not the default. This preserves modded tire value.

How This Differs from SDG Docs

• SDG docs describe tire as "repair only." Community documentation groups tires under repair tools. In the SDK, ADD mode is an upgrade/installation mechanic — you can install a better tire than what was originally on the vehicle, not just repair damaged ones.
• SDG docs claim tire items are consumed in REMOVE mode. Some guides say removal consumes the tool. In the SDK, REMOVE degrades quality (useDurability) but does not consume the item. Only ADD decrements the item amount.

Performance Considerations

Tire interaction is a single raycast per right-click. Wheel hub lookup is O(1) (direct transform reference check). Tire prefab instantiation is one GameObject.Instantiate per wheel. With 200 vehicles each having 4 wheels, tire rendering adds ~800 draw calls — negligible compared to the vehicles themselves.

Deeper FAQ

Q: Can I change tire pressure or performance through the tire item?

Not directly. The tire item attaches a wheel prefab with its own WheelCollider configuration (suspension, friction, radius). Changing tire performance requires modifying the wheel prefab, not the ItemTireAsset fields.

Q: Can tires be "damaged" without being removed?

Yes. External damage (gunfire, explosions, caltrops) can damage the wheel's WheelCollider physics properties without removing the tire. A damaged wheel behaves differently (lower friction, visible wobble) but the tire item remains "attached."

Cross-References

• Vehicle Asset — VehicleDefinition and Driveables — tireID field that determines tire compatibility.
• Vehicle Physics Profile — WheelCollider properties affected by tire changes.
• ItemCaliberAsset — Weapon Mod Base Class — Different attachment system but shares the prefab instantiation pattern.

Document history