Skip to main content

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

Example

Equip a grenade launcher.

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

getWeaponType(subject)

Returns the WeaponType equipped on the target.

Parameters


getProjectileType(subject)

Returns the projectile type the target's weapon fires.

Parameters


setPrimaryColor(subject, color)

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

Parameters

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

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

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

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

setAttackSpeed(subject, attackSpeed)

Configures the speed of the animation for the melee weapon equipped on the Player or Entity to configure.

Parameters

  • subject Player or Entity to configure.
  • attackSpeed Controls the swiftness of your melee strikes. Higher attack speed means faster attacks.
    • Min: 0.1
    • Max: 4

Example

Set a very fast melee attack to a player.

function onPlayerJoin(player)
Weapon.equip(player, WeaponType.Hammer)
Weapon.setAttackSpeed(player, 3)
end

setBlockDamage(subject, blockDamage)


setBlockImpulse(subject, blockImpulse)

Sets the amount of impulse the Player or Entity blocks when using their weapon block action.

Parameters

  • subject Player or Entity to configure.
  • blockImpulse Amount to subtract from the incoming impulse magnitude. (incoming impulse - blockImpulse).
    • Min: 0
    • Max: 100

Example

Equip a Long Sword that blocks 100 of impulse from attacks.

function onPlayerJoin(player)
Weapon.equip(player, WeaponType.LongSword)
Weapon.setBlockImpulse(player, 100)
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

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

Example

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

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

startBlock(subject)

Starts blocking with equipped weapons. Works only for Entity objects that can use melee weapons (e.g. Citizens).

Parameters

Example

Make a Citizen block forever.

function onStart()
Weapon.equip(self, WeaponType.LongSword)
Weapon.startBlock(self)
end

stopBlock(subject)

Stops blocking with equipped weapons. Works only for Entity objects that can use weapons (e.g. Citizens).

Parameters

Example

Make a Citizen block for 3 seconds.

function onStart()
Weapon.equip(self, WeaponType.LongSword)
Weapon.startBlock(self)
Task.wait(3)
Weapon.stopBlock(self)
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
  • Hammer value = 8
  • LongSword value = 9
  • Spear value = 10
  • Karate value = 11
  • Ninjato value = 12
  • SwordAndShield value = 13