UseableGun

List of events that can be used in Rocket plugins from the UseableGun class. These events track weapon actions such as shooting, reloading, aiming, and attachment changes.

Important Notes

Events can be subscribed using the static format: UseableGun.EventName += HandlerMethod
Always unsubscribe from events in Unload() to prevent memory leaks
Event handlers must match the exact signature of the event
Use ref parameters when required by the event signature
In attachment events, if newItem is null the player is removing the attachment

onBulletHit

Called when a raycast bullet hits a target. Allows cancelling the damage by setting shouldAllow to false. Check hit.player for player hits and hit.zombie for zombie hits.

private void UseableGun_onBulletHit(UseableGun gun, BulletInfo bullet, InputInfo hit, ref bool shouldAllow)
{
    // gun.player is a Player object (SDG.Unturned.Player)
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(gun.player);

    // Check if we hit a player
    if (hit.player != null)
    {
        UnturnedChat.Say(unturnedPlayer, $"You hit player: {hit.player.name} in {hit.limb}!");
    }
    // Check if we hit a zombie
    else if (hit.zombie != null)
    {
        shouldAllow = false;
        UnturnedChat.Say(unturnedPlayer, "You cannot hurt zombies!");
    }
}

onBulletSpawned

Called when a raycast bullet is fired. Useful for ammo tracking. Access bullet.magazineAsset.amount to get the remaining ammo count.

private void UseableGun_onBulletSpawned(UseableGun gun, BulletInfo bullet)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(gun.player);

    // Get the amount of ammo in the magazine
    byte ammo = bullet.magazineAsset.amount;

    if (ammo < 5)
    {
        UnturnedChat.Say(unturnedPlayer, $"WARNING: You are running low on ammo! Remaining: {ammo}");
    }
}

onProjectileSpawned

Called when a physical projectile spawns (e.g. rockets, arrows). The projectile GameObject can be destroyed immediately to cancel its effect. Useful for anti-raid plugins.

private void UseableGun_onProjectileSpawned(UseableGun sender, GameObject projectile)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(sender.player);

    // Check if it's a rocket launcher (you can also check by weapon ID sender.equippedGunAsset.id)
    if (sender.equippedGunAsset.id == 519) // 519 is the Rocket Launcher
    {
        UnturnedChat.Say(unturnedPlayer, "Using rocket launchers is not allowed!");

        // Destroy the projectile object immediately after it spawns
        UnityEngine.Object.Destroy(projectile);
    }
}

OnAimingChanged_Global

Called when a player starts or stops aiming (right mouse button). Check gun.isAiming for the current aiming state.

private void UseableGun_OnAimingChanged_Global(UseableGun gun)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(gun.player);

    if (gun.isAiming)
    {
        // Player just zoomed in with the sight
        // You can change FOV here or add an effect
    }
}

OnReloading_Global

Called when a player begins reloading their weapon. Useful for logging, sound triggers, or reload restrictions.

private void UseableGun_OnReloading_Global(UseableGun gun)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(gun.player);
    UnturnedChat.Say(unturnedPlayer, "Reloading weapon...");
}

onChangeTacticalRequested

Called when a player attempts to attach or remove a tactical attachment (laser, flashlight, rangefinder). Set shouldAllow to false to cancel the action.

private void UseableGun_onChangeTacticalRequested(PlayerEquipment equipment, UseableGun gun, Item oldItem, ItemJar newItem, ref bool shouldAllow)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(equipment.player);

    // 1008 is the Rangefinder ID
    if (newItem != null && newItem.item.id == 1008)
    {
        UnturnedChat.Say(unturnedPlayer, "This server does not allow the use of rangefinders!");
        shouldAllow = false; // Cancel the action
    }
}

onChangeSightRequested

Called when a player attempts to attach or remove a sight (red dot, ACOG, scope). Set shouldAllow to false to cancel the action.

private void UseableGun_onChangeSightRequested(PlayerEquipment equipment, UseableGun gun, Item oldItem, ItemJar newItem, ref bool shouldAllow)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(equipment.player);

    // Check if the player is equipping a 16x scope (ID 21)
    if (newItem != null && newItem.item.id == 21)
    {
        // Here you would normally check Rocket permissions, e.g.:
        // if (!equipment.player.HasPermission("use.scope")) ...

        UnturnedChat.Say(unturnedPlayer, "The 16x scope is too powerful!");
        shouldAllow = false;
    }
}

onChangeMagazineRequested

Called when a player attempts to attach or remove a magazine. Use Assets.find to resolve the magazine asset and get its name or other properties.

private void UseableGun_onChangeMagazineRequested(PlayerEquipment equipment, UseableGun gun, Item oldItem, ItemJar newItem, ref bool shouldAllow)
{
    if (newItem != null)
    {
        // Get the asset (data) of the new magazine to know its name
        ItemAsset magAsset = (ItemAsset)Assets.find(EAssetType.ITEM, newItem.item.id);
        if (magAsset != null)
        {
            // UnturnedChat.Say(equipment.player, $"Loaded: {magAsset.itemName}");
        }
    }
}

onChangeGripRequested

Called when a player attempts to attach or remove a grip (bipod, vertical grip). Set shouldAllow to false to cancel the action.

private void UseableGun_onChangeGripRequested(PlayerEquipment equipment, UseableGun gun, Item oldItem, ItemJar newItem, ref bool shouldAllow)
{
    // By default, shouldAllow is true.
    // We don't change anything here, so the player can freely change grips.
}

onChangeBarrelRequested

Called when a player attempts to attach or remove a barrel attachment (suppressor, flash hider). Set shouldAllow to false to cancel the action.

private void UseableGun_onChangeBarrelRequested(PlayerEquipment equipment, UseableGun gun, Item oldItem, ItemJar newItem, ref bool shouldAllow)
{
    UnturnedPlayer unturnedPlayer = UnturnedPlayer.FromPlayer(equipment.player);

    // Check if the weapon is a Maplestrike (ID 363)
    if (gun.equippedGunAsset.id == 363)
    {
        // Check if the new item is a suppressor (e.g. ID 7 - Military Suppressor)
        if (newItem != null && newItem.item.id == 7)
        {
            UnturnedChat.Say(unturnedPlayer, "You cannot attach a suppressor to the Maplestrike!");
            shouldAllow = false;
        }
    }
}