Skip to content

Weapons and ammunition

Manage a player’s inventory from the server with Player methods. This example gives a pistol with 60 rounds, selects it and adds an extended magazine and a suppressor:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
/** @param {revo.Player} player */
export function giveLoadout(player) {
player.giveWeapon(revo.WeaponHash.PistolMk2, 60, true);
player.addWeaponComponent(revo.WeaponHash.PistolMk2, revo.WeaponComponentHash.PistolMk2Clip02);
player.addWeaponComponent(revo.WeaponHash.PistolMk2, revo.WeaponComponentHash.AtPiSupp02);
}

Call it when applying the player’s loadout. giveWeapon(hash, ammo, true) selects the weapon immediately. With false, the current weapon stays selected. setCurrentWeapon(hash) selects an owned weapon, and setCurrentWeapon(revo.WeaponHash.Unarmed) puts it away.

getWeapon(hash) returns a snapshot of the inventory entry, or null. hasWeapon(hash) checks ownership. Use removeWeapon(hash) to remove one weapon or removeAllWeapons() to clear the inventory.

The server inventory is restored when the player’s ped is recreated, including respawn and model changes. Store the desired hashes, ammunition and components in your character data to restore them after a new connection.

Ammunition is the weapon’s total round count and accepts integers from 0 to 99999. To add rounds, read the current count with getWeapon() and pass the new total to setWeaponAmmo(). A player can hold up to 128 distinct weapons.

addWeaponComponent() replaces an existing component in the same slot. removeWeaponComponent() removes it. Use hasWeaponComponent() and getWeaponComponents() to inspect the loadout.

The supported component catalog currently covers Mk II weapons. Adding a component outside that weapon’s catalog returns false. A magazine can also change the ammunition variant, such as armour-piercing or incendiary rounds. Removing it restores the weapon’s default ammunition variant.

For a complete saved loadout, use setWeaponLoadout(hash, loadout) or the giveWeapon(hash, ammo, loadout, equip) overload. loadout.components accepts up to eight unique component hashes in ascending numeric order. ammoType must match the selected magazine.

Use the server’s beforeDamage event to change damage per weapon, target or mode rule. This example applies 36 damage for a pistol hit to the head and 18 for hits elsewhere on players and NPCs:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
revo.on('beforeDamage', event => {
if (!(event.target instanceof revo.Ped)) return;
if (event.type !== revo.DamageType.Hit) return;
if (event.weapon === revo.WeaponHash.PistolMk2) {
return event.component === revo.PedBodyPart.Head ? 36 : 18;
}
});

Compare event.component with PedBodyPart to identify the hit body part. The enum covers standard human peds and is available on the server and client. For custom ped models and animals, use indices that match their collision setup.

Return a number from 0 to 1000000 to replace the requested damage. Returning 0 cancels it. Returning undefined keeps the current amount. The normal damage application follows the handler, so avoid subtracting health again there.

Handlers run synchronously in registration order. Each receives the amount left by the preceding handler. Armour and other damage rules can affect the final health loss. Use DamageType.Hit, Explosion or Fire to distinguish the source.

A weapon with a new hash needs a server combat profile as well as its native assets. Register the profile during server startup before giving the weapon to a player. A replacement that keeps an existing weapon hash can use that hash’s profile and adjust damage through beforeDamage.

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
// These names must match the weapon definitions in your native assets.
export const customShotgun = revo.hash('WEAPON_CUSTOM_SHOTGUN');
export const customLauncher = revo.hash('WEAPON_CUSTOM_LAUNCHER');
if (!revo.registerWeaponProfile(customShotgun, {
range: 80,
damage: 14,
shotIntervalMs: 800,
maxPellets: 8,
spreadDegrees: 10,
})) {
throw new Error('Invalid custom shotgun profile');
}
if (!revo.registerProjectileProfile(customLauncher, {
kind: revo.ProjectileKind.Rocket,
damage: 180,
radius: 6,
range: 300,
maximumSpeed: 150,
launchIntervalMs: 1500,
lifetimeMs: 10000,
})) {
throw new Error('Invalid custom launcher profile');
}

registerWeaponProfile() covers bullet weapons, including shotguns. damage is per pellet. shotIntervalMs is the minimum time between shots. Set maxPellets and spreadDegrees to match the weapon’s pellet count and spread.

registerProjectileProfile() covers rockets, hand grenades, grenade launchers, pipe bombs and Molotov-style projectiles through ProjectileKind. Choose the kind matching the native weapon’s behavior. Range and radius use metres, speed uses metres per second, and intervals and lifetime use milliseconds. Grenades also undergo fuse validation. Molotov profiles require damage: 0, with fire damage handled through beforeDamage.

Profiles define server validation and damage rules. Match them to the native asset’s firing rate, flight and fuse settings. Native assets supply the weapon model, animations and projectile behavior. Clients receive registered projectile definitions automatically, including when connecting after registration.

Both registration methods return false for invalid settings and throw TypeError for wrong argument types. Bullet and projectile profiles cannot share a weapon hash. Up to 256 projectile profiles are supported, including the built-in profiles. Custom sticky bombs and proximity mines are not supported by these methods.

getWeaponProfile() and getProjectileProfile() return copies of the current settings, or null. Registering the same profile again replaces its settings for subsequent shots. Removing it with unregisterWeaponProfile() or unregisterProjectileProfile() prevents new shots from being accepted. Shots already accepted retain their profile until impact or expiry.

Custom bullet weapons currently use ammoType: 0 and an empty component list. The default ammoType argument for bullet profile methods is 0. Built-in Mk II ammunition variants can have separate profiles.

On the server, currentWeaponChanged reports weapon selection changes. weaponShotAccepted and projectileLaunched report accepted firing actions. Use beforeDamage for damage decisions.

Client events include weaponChange, weaponFired, weaponReloadStarted, weaponAimStarted and weaponAimStopped. They are useful for local HUD and presentation changes.

Player inventory methods · Weapon hashes · Weapon components · Damage event

For healing, scripted health loss and state notifications, see Health and damage.