Weapon

Contains functions for configuring and customizing weapons.

info

This module can only be used in Entity scripts.

Functions

equip(subject, type)

Loads the weapon on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• type — WeaponType to load.

Example

Equip a grenade launcher.

function onStart()
    Weapon.equip(self, WeaponType.GrenadeLauncher)
end

---

setPrimaryColor(subject, color)

Customizes the primary color of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• color — Color of the weapon skin.

Example

Equip a laser beam and change the primary color to green after 2 seconds.

function onStart()
    local green = Color.new(0,255,0)
    Weapon.equip(self, WeaponType.LaserBeam)
    Task.wait(2)
    Weapon.setPrimaryColor(self, green)
end

---

setSecondaryColor(subject, color)

Customizes the secondary color of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• color — Color of the weapon skin.

Example

Equip a rifle and change the secondary color to red after 2 seconds.

function onStart()
    local red = Color.new(255,0,0)
    Weapon.equip(self, WeaponType.Rifle)
    Task.wait(2)
    Weapon.setSecondaryColor(self, red)
end

---

setBarrelSkin(subject, barrelId)

Customizes the barrel of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• barrelId — ID of the part to equip.

Example

Equip a rifle with the rail gun barrel skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.Rifle)
    Task.wait(2)
    Weapon.setBarrelSkin(self, "barrel.ricochet.0")
end

---

setBodySkin(subject, bodyId)

Customizes the body of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• bodyId — ID of the part to equip.

Example

Equip a RPG with the pistol body skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.RPG)
    Task.wait(2)
    Weapon.setBodySkin(self, "body.pistol.0")
end

---

setGripSkin(subject, gripId)

Customizes the grip of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• gripId — ID of the part to equip.

Example

Equip a pistol with the laser bean grip skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.Pistol)
    Task.wait(2)
    Weapon.setGripSkin(self, "grip.laserbeam.0")
end

---

setMagazineSkin(subject, magazineId)

Customizes the magazine of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• magazineId — ID of the part to equip.

Example

Equip a RPG with the laser bean magazine skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.RPG)
    Task.wait(2)
    Weapon.setMagazineSkin(self, "magazine.laserbeam.0")
end

---

setMuzzleSkin(subject, muzzleId)

Customizes the muzzle particle effect for the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• muzzleId — ID of the particle effect to equip.

Example

Equip a rifle with the rpg muzzle skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.Rifle)
    Task.wait(2)
    Weapon.setMuzzleSkin(self, "rpg.0")
end

---

setSightSkin(subject, sightId)

Customizes the sight of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• sightId — ID of the part to equip.

Example

Equip a rifle with the ricochet sight skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.Rifle)
    Task.wait(2)
    Weapon.setSightSkin(self, "sight.ricochet.0")
end

---

setStockSkin(subject, stockId)

Customizes the stock of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• stockId — ID of the part to equip.

Example

Equip a pistol with the grenade launcher stock skin after 2 seconds.

function onStart()
    Weapon.equip(self, WeaponType.Pistol)
    Task.wait(2)
    Weapon.setStockSkin(self, "stock.grenadelauncher.0")
end

---

setProjectileColor(subject, color)

Customizes the color for the projectile of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• color — Color of the projectile.

Example

projectile color to green and after 2 seconds set it to blue.

function onStart()
    Weapon.setProjectileColor(self, Color.green)
    Weapon.attack()
    Task.wait(2)
    Weapon.setProjectileColor(self, Color.blue)
    Weapon.attack()
end

---

setSkin(subject, properties)

Customizes multiple parts of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• properties — WeaponSkinConfig properties.

Example

Equip a rifle with a custom skin after 2 seconds.

function onStart()
    local green = Color.new(0,255,0)
    local red = Color.new(255,0,0)
    local customSkin = {
        primaryColor = green,
        secondaryColor = red,
        body = "body.pistol.0",
        barrel = "barrel.ricochet.0",
        grip = "grip.laserbeam.0"
    }
    Weapon.equip(self, WeaponType.Rifle)
    Task.wait(2)
    Weapon.setSkin(self, customSkin)
end

---

setReloadTime(subject, reloadTime)

Configures the time required to reload the clip on the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• reloadTime — Time required to reload the clip (in seconds).
  • Min: 0.1
  • Max: 10

Example

Attack 5 times, then wait 2 seconds and change the reload time to 0.1.

function attackEnemy()
    Weapon.setAmmo(self, 3)
    for i=1,5 do
        Weapon.attack()
    end
end

function onStart()
    attackEnemy()
    Weapon.setReloadTime(self, 0.1)
    Task.wait(1)
    attackEnemy();
end

---

setCooldown(subject, cooldown)

Configures the minimum time it takes to shoot the weapon equipped on the Player or Entity to configure. This is useful for controlling the maximum rate for shooting the weapon.

Parameters

• subject — Player or Entity to configure.
• cooldown — Minimum time between shots (in seconds).
  • Min: 0.1
  • Max: 100

Example

Set weapon cooldown to 2.

function attackEnemy()
    Weapon.setAmmo(self, 10)
    for i=1,5 do
        Weapon.attack()
    end
end

function onStart()
    attackEnemy()
    Task.wait(1)
    Weapon.setCooldown(self, 2)
    attackEnemy()
end

---

setClipSize(subject, clipSize)

Configures the clip capacity (rounds) of the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• clipSize — Quantity of rounds that can be fired before reloading.
  • Min: 1
  • Max: 999999

Example

Set clip size to 200.

function attackEnemy()
    Weapon.setAmmo(self, 10)
    for i=1,5 do
        Weapon.attack()
    end
end

function onStart()
    Weapon.setClipSize(self, 3)
    attackEnemy()
    Task.wait(1)
    Weapon.setClipSize(self, 200)
    attackEnemy()
end

---

setAmmo(subject, ammo)

Configures the quantity of ammo (rounds) remaining for the weapon equipped on the Player or Entity to configure.

Parameters

• subject — Player or Entity to configure.
• ammo — Total quantity of rounds that can be fired.
  • Min: 1
  • Max: 999999

Example

Set ammo to 3 and then change it to 100.

function attackEnemy()
    Weapon.setAmmo(self, 10)
    for i=1,5 do
        Weapon.attack()
    end
end

function onStart()
    Weapon.equip(self, WeaponType.LaserBean)
    Weapon.setAmmo(self, 5)
    attackEnemy()
    Task.wait(1)
    Weapon.setAmmo(self, 100)
    attackEnemy()
end

---

setInfiniteAmmo(subject, infinite)

Configures whether the weapon equipped on the target Player or Entity has unlimited ammo.

Parameters

• subject — Player or Entity to configure.
• infinite — Determines whether the weapon has unlimited ammo. If true, the configured ammo capacity is ignored and the weapon will never run out of ammo. Otherwise, the configured ammo capcity applies.

Example

Set infinite ammo.

function attackEnemy()
    for i=1,10 do
        Weapon.attack()
    end
end

function onStart()
    Weapon.setInfiniteAmmo(self, true)
    attackEnemy()
end

---

setAutomatic(subject, automatic)

Configures whether the weapon equipped on the target Player or Entity is automatic.

Parameters

• subject — Player or Entity to configure.
• automatic — Determines whether the weapon fires automatically. If true, the weapon will fire repeatedly at the maximum rate, whilst the player holds down the trigger. Otherwise, the player must release the trigger before the next shot can be fired.

Example

Equip a non automatic rifle.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.setAutomatic(self,false)
    attackEnemy(10)
    Task.wait(1)
    Weapon.setAutomatic(self,true)
    attackEnemy(10)
end

---

setDamage(subject, damage)

Sets the amount of damage dealt when the projectile impacts an object.

Parameters

• subject — Player or Entity to configure.
• damage — Amount of damage dealt.
  • Min: 0
  • Max: 255

Example

Equip a rifle with no damage, then add damage after shooting 5 times.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.equip(self, WeaponType.Rifle)
    Weapon.setDamage(self,0)
    attackEnemy(5)
    Task.wait(1)
    Weapon.setDamage(self,10)
    attackEnemy(5)
end

---

setDamageRadius(subject, radius)

Sets the radius of the damage zone - objects within the damage zone when the projectile impacts, will receive damage.

Parameters

• subject — Player or Entity to configure.
• radius — Radius of the damage zone.
  • Min: 0.1
  • Max: 100

Example

Set damage radius to 10.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    attackEnemy(3)
    Task.wait(2)
    Weapon.setDamageRadius(self,10)
    attackEnemy(3)
end

---

setImpulse(subject, impulse)

Sets the amount of impulse to apply to objects within the damage radius.

Parameters

• subject — Player or Entity to configure.
• impulse — Amount of impulse to apply.
  • Min: 0
  • Max: 100

Example

Set impulse to 5.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    attackEnemy(3)
    Task.wait(1)
    Weapon.setImpulse(self, 5)
    attackEnemy(3)
end

---

setSpeed(subject, speed)

Sets the speed of the projectile (only applies to bullet-type projectiles).

Parameters

• subject — Player or Entity to configure.
• speed — Speed of the projectile.
  • Min: 0.1
  • Max: 15

Example

Set speed to 1 and then change it to 15.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.setSpeed(self, 1)
    attackEnemy(3)
    Task.wait(1)
    Weapon.setSpeed(self, 15)
    attackEnemy(3)
end

---

setGravity(subject, gravity)

Sets the amount of gravity to apply to the projectile (only applies to bullet-type projectiles).

Parameters

• subject — Player or Entity to configure.
• gravity — Amount of gravity to apply.
  • Min: -100
  • Max: 100

Example

Set gravity to 1 (light gravity) then change it to 4.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.setGravity(self, 1)
    attackEnemy(3)
    Task.wait(1)
    Weapon.setGravity(self, 4)
    attackEnemy(3)
end

---

setLifetime(subject, lifetime)

Sets the maximum time (in seconds) the projectile can exist (only applies to bullet-type projectiles).

Parameters

• subject — Player or Entity to configure.
• lifetime — Time (in seconds).
  • Min: 0.1
  • Max: 10

Example

Set projectile life time to 1 seconds, then change it to 3 seconds.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack(Vector3.new(1,0,-6))
    end
end

function onStart()
    Weapon.equip(self, WeaponType.GrenadeLauncher)
    Weapon.setLifetime(self, 1)
    attackEnemy(3)
    Task.wait(1)
    Weapon.setLifetime(self, 3)
    attackEnemy(3)
end

---

setSpeedMultiplier(subject, multiplier)

Sets how much the velocity of the object shooting the projectile is added to the initial velocity of the projectile (only applies to bullet-type projectiles).

Parameters

• subject — Player or Entity to configure.
• multiplier — Multiplier factor.
  • Min: 0.1
  • Max: 10

Example

Set speed multiplier to 0.1 (this will only add 10% velocity of the object shooting the projectile).

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.setSpeedMultiplier(self, 0.1)
    attackEnemy(5)
end

---

setProjectileSize(subject, projectileSize)

Sets the physical size of the projectile (only applies to bullet-type projectiles).

Parameters

• subject — Player or Entity to configure.
• projectileSize — Physical size of the projectile.
  • Min: 0.1
  • Max: 10

Example

Equip a grenade launcher with a projectile size of 2 (twice the regular size) after shooting 3 times.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.equip(self, WeaponType.GrenadeLauncher)
    attackEnemy(3)
    Task.wait(1)
    Weapon.setProjectileSize(self, 2)
    attackEnemy(3)
end

---

setRange(subject, value)

Sets the maximum range of the projectile (only applies to hitscan-type projectiles).

Parameters

• subject — Player or Entity to configure.
• value — Maximum range of the projectile.

Example

Set range to 3 (very short range), then increase it to 10.

function attackEnemy(n)
    for i=1,n do
        Weapon.attack()
    end
end

function onStart()
    Weapon.equip(self, WeaponType.LaserBeam)
    Weapon.setRange(self, 3)
    attackEnemy(5)
    Task.wait(1)
    Weapon.setRange(self,10)
    attackEnemy(5)
end

---

getAmmo(subject, countTotal)

Gets current ammo of the weapon equipped on the Player or Entity.

Parameters

• subject — Player or Entity to get ammo from.
• countTotal — If true, returns the total ammo (clip + ammo). If ammo is infinite, capacity is used. Otherwise, returns only the current clip (optional).

---

attack(subject)

Starts an attack with equipped weapons. Works only for Entity objects that can use weapons (e.g. Citizens or Robots).

Parameters

• subject — Entity or Vector3 position to attack.

Example

Attack, wait 2 seconds, then attack again.

function onStart()
    Weapon.attack()
    Task.wait(2)
    Weapon.attack()
end

---

explode(damage, radius, impulse)

Explodes the Entity.

Parameters

• damage — Damage amount. Positive whole number only.
• radius — Radius of the explosion. Damage is applied to objects within this radius.
• impulse — Amount of impulse applied to objects within the radius.
  • Min: 0
  • Max: 100

Example

Make an explosive entity explode after 2 seconds. The explosion will deal 10 damage, will have an explosion radius of 5 and will impulse the objects withing the radius by 50.

function onStart()
    Weapon.explode(10, 5, 50)
end

---

setProjectileIgnore(subject, targetObject, ignored)

Sets an Player's or Entity's weapon to ignore certain targets.

Parameters

• subject — Player or Entity.
• targetObject — Player, Entity, Entity Code or ProjectileLayer to ignore.
• ignored — If projectiles fired by the weapon should ignore the target.

Example

Make an Entity's projectiles ignore players when they join the server.

function onPlayerJoin(player)
    Weapon.setProjectileIgnore(self, player, true)
end

---

resetProjectileIgnore(subject)

Reset a Player's or Entity's weapon so it collides with everything again.

Parameters

• subject — Player or Entity.

Example

Reset a Player's weapon ignore settings when they intersect this Entity.

function playerEnter(player)
    Weapon.resetProjectileIgnore(player)
end

Enums

WeaponType

• None — value = 0
• RPG — value = 1
• Rifle — value = 2
• Pistol — value = 3
• Ricochet — value = 4
• LaserBeam — value = 5
• Fist — value = 6
• GrenadeLauncher — value = 7