Skip to main content
Version: latest - a1.3.0 ⚖️

🔫 Weapon

info

🟦 Authority: This class can only be spawned on Server.

Inheritance: This class inherits from Actor, Paintable and Pickable.

Weapons are fully customizable, all pieces of the weapon can be changed with immense possibility of creation

info

Please take a look at our Default’s Weapon package with all built-in Weapons already properly configured and ready to use: https://github.com/nanos-world/nanos-world-weapons.

Usage

Server/Index.lua
-- Spawning an AK47
local new_weapon = Weapon(Vector(-900, 185, 215), Rotator(0, 90, 90), "nanos-world::SK_AK47", CollisionType.Normal, true)

-- Configures Weapon Base Settings
new_weapon:SetAmmoSettings(30, 1000)
new_weapon:SetDamage(30)
new_weapon:SetSpread(30)
new_weapon:SetRecoil(0.25)
new_weapon:SetBulletSettings(1, 20000, 20000, Color(100, 58, 0))
new_weapon:SetCadence(0.1)
new_weapon:SetWallbangSettings(50, 0.75)

-- Configures how the Character Grabs and Aims the Weapon
new_weapon:SetHandlingMode(HandlingMode.DoubleHandedWeapon)
new_weapon:SetSightTransform(Vector(0, 0, -14.85), Rotator(-1, 0, 0))
new_weapon:SetLeftHandTransform(Vector(26, 0, 8.5), Rotator(0, 60, 90))
new_weapon:SetRightHandOffset(Vector(-10, 0, 0))

-- Configures Weapon Particles
new_weapon:SetParticlesBulletTrail("nanos-world::P_Bullet_Trail")
new_weapon:SetParticlesBarrel("nanos-world::P_Weapon_BarrelSmoke")
new_weapon:SetParticlesShells("nanos-world::P_Weapon_Shells_762x39")

-- Configures Weapon Sounds
new_weapon:SetSoundDry("nanos-world::A_Rifle_Dry")
new_weapon:SetSoundLoad("nanos-world::A_Rifle_Load")
new_weapon:SetSoundUnload("nanos-world::A_Rifle_Unload")
new_weapon:SetSoundZooming("nanos-world::A_AimZoom")
new_weapon:SetSoundAim("nanos-world::A_Rattle")
new_weapon:SetSoundFire("nanos-world::A_AK47_Shot")

-- Configures Weapon Animations
new_weapon:SetAnimationFire("nanos-world::A_AK47_Fire")
new_weapon:SetAnimationCharacterFire("nanos-world::AM_Mannequin_Sight_Fire")
new_weapon:SetAnimationReload("nanos-world::AM_Mannequin_Reload_Rifle")

-- Configures the Mesh to drop when reloading
new_weapon:SetMagazineMesh("nanos-world::SM_AK47_Mag_Empty")

-- Configures the Crosshair Material
new_weapon:SetCrosshairMaterial("nanos-world::MI_Crosshair_Regular")

Using our Default Weapons Package https://github.com/nanos-world/nanos-world-weapons (already built-in included) for spawning an AK47:

Server/Index.lua
-- Includes the nanos world Default Weapons Package in your Package (you don't need to download it, just include it!)
Package.RequirePackage("nanos-world-weapons")

-- Spawning the AK47
local my_ak47 = NanosWorldWeapons.AK47(Vector(1035, 154, 300), Rotator())

-- Giving the Weapon to a Character
my_character:PickUp(my_ak47)
Prop Shootergetting-started/tutorials-and-examples/prop-shooterWeapon Scopegetting-started/tutorials-and-examples/weapon-scopeWeapon Flashlightgetting-started/tutorials-and-examples/weapon-flashlight

Constructor Parameters

TypeNameDefault
VectorlocationVector(0, 0, 0)
RotatorrotationRotator(0, 0, 0)
SkeletalMesh Assetasset
CollisionTypecollision_typeCollisionType.Normal
booleangravity_enabledtrue

Functions

Inherited Actor Functions
Base Actorscripting-reference/classes/base-classes/actor
ReturnsNameDescription
AddImpulseApplies a Force in world space to this Actor
AttachToAttaches this Actor to another Actor
DestroyDestroys this Actor
DetachDetaches this Actor if attached
SetCollisionSets this Actor’s collision type
SetForceAdds a permanent force to this Actor
SetGravityEnabledSets whether gravity is enabled on this Actor
SetVisibilitySets the Actor visibility
SetHighlightEnabledSets whether the highlight is enabled on this Actor, and which highlight index to use
SetLifeSpanSets the time (in seconds) before this Actor is destroyed
SetLocationSets this Actor’s location in the game world
SetNetworkAuthoritySets the Player this Actor will have its physics calculated on Network Authority
SetRelativeLocationSets this Actor’s relative location in local space
SetRelativeRotationSets this Actor’s relative rotation in local space
SetRotationSets this Actor’s rotation in the game world
SetScaleSets this Actor’s scale
SetValueSets a value in this Actor, which can be accessed by any package
TranslateToSmoothly moves this Actor to the specified location
RotateToSmoothly rotates this Actor to the specified angle
booleanIsBeingDestroyedGets if this Actor is being destroyed
booleanIsGravityEnabledGets whether gravity is enabled on this Actor
booleanIsInWaterGets if this Actor is in water
booleanIsNetworkDistributedGets if this Actor is Network Distributed
booleanIsValidReturns if this Actor is valid (i.e. not destroyed)
tableGetAttachedEntitiesGets all Actors attached to this Actor
anyGetAttachedToGets the Actor this Actor is attached to
tableGetBoundsGets this Actor's bounds
numberGetCollisionGets this Actor’s collision type
numberGetIDGets the universal network ID of this Actor
VectorGetLocationGets this Actor’s location in the game world
RotatorGetRotationGets this Actor’s angle in the game world
VectorGetScaleGets this Actor’s scale
stringGetTypeGets the type of this Actor
anyGetValueGets a value stored on this Actor at the given key
VectorGetVelocityReturns this Actor's current velocity
functionSubscribeSubscribes to an Event
UnsubscribeUnsubscribes from an Event
Inherited Pickable Functions
Base Pickablescripting-reference/classes/base-classes/pickable
ReturnsNameDescription
AddSkeletalMeshAttachedSpawns and attaches a SkeletalMesh to this Pickable
AddStaticMeshAttachedSpawns and attaches a StaticMesh to this Pickable
PullUseTriggers the PullUse event on this Pickable
ReleaseUseTriggers the ReleaseUse event on this Pickable
RemoveSkeletalMeshAttachedRemoves, if it exists, a SkeletalMesh from this Pickable given its custom ID
RemoveStaticMeshAttachedRemoves, if it exists, a StaticMesh from this Pickable given its custom ID
SetAttachmentSettingsSets the adjustment of the Attachment
SetCrosshairMaterialSets the crosshair material for this Pickable
SetPickableSets if this Pickable can be grabbed
stringGetAssetNameGets the name of the asset this Pickable uses
CharacterGetHandlerGets the Character, if it exists, that's holding this Pickable
Inherited Paintable Functions
Base Paintablescripting-reference/classes/base-classes/paintable
ReturnsNameDescription
SetMaterialSets the material at the specified index of this Actor
SetMaterialFromWebUISets the material at the specified index of this Actor to a WebUI object
SetMaterialFromSceneCaptureSets the material at the specified index of this Actor to a SceneCapture object
ResetMaterialResets the material from the specified index to the original one
SetMaterialColorParameterSets a Color parameter in this Actor’s material
SetMaterialScalarParameterSets a scalar parameter in this Actor’s material
SetMaterialTextureParameterSets a texture parameter in this Actor's material to an image on disk
SetMaterialVectorParameterSets a Vector parameter in this Actor’s material
SetPhysicalMaterialOverrides this Actor's Physical Material with a new one
ReturnsNameDescription
ReloadForces this weapon to Reload
SetAmmoBagSets this Weapon’s Ammo in the Bag
SetAmmoClipSets this Weapon’s Ammo in the Clip
SetAmmoSettingsAuxiliary for setting and configuring ammo
SetAnimationFireAnimation played by the Weapon when Firing
SetAnimationCharacterFireAnimation played by the Character when Firing
SetAnimationReloadAnimation played by the Character when Reloading
SetBulletColorSet the Bullet Color
SetBulletSettingsAuxiliary for setting and configuring the Bullet
SetCadenceSpeed of shots
SetClipCapacityCapacity of the Weapon’s Clip
SetDamageBase Weapon’s Damage
SetHandlingModeSets how the Character grabs this Weapon
SetLeftHandTransformLeft Hand Offset
SetMagazineMeshThe mesh used when the Character reloads the weapon. Will drop this Mesh as an animation effect.
SetParticlesBulletTrailParticle of the Bullet flying
SetParticlesBarrelParticle of the Fire Blast in the muzzle
SetParticlesShellsParticle of the empty bullet flying from the weapon when shooting
SetRightHandOffsetOffset of Right Hand. To position relative to the camera.
SetSightFOVMultiplierThe FOV multiplier when ADS
SetSightTransformOffset applied to align player’s head to weapon’s sight and rotation applied on the weapon when ADS
SetSoundDrySound when weapon has not bullet and try to shoot
SetSoundLoadSound when Loading a magazine
SetSoundUnloadSound when Unloading a magazine
SetSoundZoomingSound when Zooming
SetSoundAimSound when Aiming
SetSoundFireSound when Shooting
SetSoundFireLastBulletsSound when Shooting last bullets
SetSpreadBase Weapon’s Spread (the higher the less precision)
SetRecoilBase Weapon’s Recoil Multiplier
SetUsageSettingsSets if the Weapon can hold to keep firing and if it needs to release to fire
SetWallbangSettingsSets how the bullets will pass through walls
numberGetAmmoBagGets this Weapon’s Ammo Bag
numberGetAmmoClipGets this Weapon’s Ammo Clip
numberGetAmmoToReload
stringGetAnimationCharacterFire
stringGetAnimationFire
ColorGetBulletColor
numberGetBulletCount
numberGetCadence
booleanGetCanHoldUse
numberGetClipCapacity
numberGetDamage
HandlingModeGetHandlingMode
booleanGetHoldReleaseUse
booleanGetLeftHandLocation
stringGetMagazineMesh
stringGetParticlesBulletTrail
stringGetParticlesBarrel
stringGetParticlesShells
VectorGetRightHandOffset
numberGetSightLocation
numberGetSightRotation
numberGetSightFOVMultiplier
stringGetSoundDry
stringGetSoundLoad
stringGetSoundUnload
stringGetSoundZooming
stringGetSoundAim
stringGetSoundFire
numberGetSpread
numberGetRecoil

Events

Inherited Actor Events
Base Actorscripting-reference/classes/base-classes/actor
NameDescription
DestroyTriggered when an Actor is destroyed
SpawnTriggered when an Actor is spawned/created
ValueChangeTriggered when an Actor has a value changed with :SetValue()
Inherited Pickable Events
Base Pickablescripting-reference/classes/base-classes/pickable
NameDescription
DropWhen a Character drops this Pickable
HitWhen this Pickable hits something
InteractWhen a Character interacts with this Pickable
PickUpWhen a Character picks this up
PullUseWhen a Character presses the use button for this Pickable (i.e. clicks left mouse button with this equipped)
ReleaseUseWhen a Character releases the use button for this Pickable (i.e. releases left mouse button with this equipped)
NameDescription
FireWhen Weapon is fired
ReloadWhen Weapon is reloaded

Functions Detailed

Reload

Forces this Weapon to reload (only if being handled by a Character)

my_weapon:Reload()

SetAmmoBag

Sets this Weapon's Ammo in the Bag

my_weapon:SetAmmoBag(new_ammo)
TypeParameterDefault ValueDescription
numbernew_ammo

SetAmmoClip

Sets this Weapon's Ammo in the Clip

my_weapon:SetAmmoClip(new_ammo)
TypeParameterDefault ValueDescription
numbernew_ammo

SetAmmoSettings

Aux for setting and configuring ammo

my_weapon:SetAmmoSettings(ammo_clip, ammo_bag, ammo_to_reload, clip_capacity)
TypeParameterDefault ValueDescription
numberammo_clip
numberammo_bag
numberammo_to_reloadammo_clipThe amount of ammo which will be effectively reloaded in the clip when reloading
numberclip_capacityammo_clipHow much ammo the clip can hold without needing to reload

SetAnimationFire

Animation played by the Weapon when Firing

my_weapon:SetAnimationFire(animation_asset_path)
TypeParameterDefault ValueDescription
Animation Assetanimation_asset_path

SetAnimationCharacterFire

Animation played by the Character when Firing

my_weapon:SetAnimationCharacterFire(animation_asset_path)
TypeParameterDefault ValueDescription
Animation Assetanimation_asset_path

SetAnimationReload

Animation played by the Character when Reloading

Currently this animation must be one of the default ones: AM_Mannequin_Reload_Rifle, AM_Mannequin_Reload_Pistol or AM_Mannequin_Reload_Shotgun, as they have internal triggers to finish the reload

my_weapon:SetAnimationReload(animation_asset_path, play_rate)
TypeParameterDefault ValueDescription
Animation Assetanimation_asset_path
numberplay_rate1

SetBulletColor

Set the Bullet Color

Only has effect if using Bullet Trail particle P_Bullet_Trail or if you particle has the Color parameter

my_weapon:SetBulletColor(color)
TypeParameterDefault ValueDescription
Colorcolor

SetBulletSettings

Aux for setting and configuring the Bullet

my_weapon:SetBulletSettings(bullet_count, bullet_max_distance, bullet_velocity, bullet_color)
TypeParameterDefault ValueDescription
numberbullet_count1 for common weapons, > 1 for shotguns
numberbullet_max_distance
numberbullet_velocityVisuals only
Colorbullet_color

SetCadence

Speed of shots

my_weapon:SetCadence(cadence)
TypeParameterDefault ValueDescription
numbercadence1 shot at each cadence second

SetClipCapacity

Capacity of the Weapon's Clip

my_weapon:SetClipCapacity(clip)
TypeParameterDefault ValueDescription
numberclip

SetDamage

Base Weapon's Damage

This will be multiplied by multiplier factors when hitting specific bones

my_weapon:SetDamage(damage)
TypeParameterDefault ValueDescription
numberdamage

SetHandlingMode

Sets how the Character grabs this Weapon

my_weapon:SetHandlingMode(mode)
TypeParameterDefault ValueDescription
HandlingModemode

SetLeftHandTransform

Left Hand Offset

my_weapon:SetLeftHandTransform(location, rotation)
TypeParameterDefault ValueDescription
Vectorlocation
Rotatorrotation

SetMagazineMesh

The mesh used when the Character reloads the weapon. Will drop this Mesh as an animation effect.

my_weapon:SetMagazineMesh(static_mesh_asset_path)
TypeParameterDefault ValueDescription
StaticMesh Assetstatic_mesh_asset_path

SetParticlesBulletTrail

Particle of the Bullet flying

my_weapon:SetParticlesBulletTrail(particle_asset_path)
TypeParameterDefault ValueDescription
Particle Assetparticle_asset_path

SetParticlesBarrel

Particle of the Fire Blast in the muzzle

my_weapon:SetParticlesBarrel(particle_asset_path)
TypeParameterDefault ValueDescription
Particle Assetparticle_asset_path

SetParticlesShells

Particle of the empty bullet flying from the weapon when shooting

my_weapon:SetParticlesShells(particle_asset_path)
TypeParameterDefault ValueDescription
Particle Assetparticle_asset_path

SetRightHandOffset

Offset of Right Hand. To position relative to the camera.

my_weapon:SetRightHandOffset(offset)
TypeParameterDefault ValueDescription
Vectoroffset

SetSightFOVMultiplier

The FOV multiplier when ADS

my_weapon:SetSightFOVMultiplier(multiplier)
TypeParameterDefault ValueDescription
numbermultiplier

SetSightTransform

Offset applied to align player's head to weapon's sight and rotation applied on the weapon when ADS

my_weapon:SetSightTransform(location, rotation)
TypeParameterDefault ValueDescription
Vectorlocation
Rotatorrotation

SetSoundDry

Sound when weapon has not bullet and try to shoot

my_weapon:SetSoundDry(sound_asset_path)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path

SetSoundLoad

Sound when Loading a magazine

my_weapon:SetSoundLoad(sound_asset_path)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path

SetSoundUnload

Sound when Unloading a magazine

my_weapon:SetSoundUnload(sound_asset_path)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path

SetSoundZooming

Sound when Zooming

my_weapon:SetSoundZooming(sound_asset_path)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path

SetSoundAim

Sound when Aiming

my_weapon:SetSoundAim(sound_asset_path)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path

SetSoundFire

Sound when Shooting

my_weapon:SetSoundFire(sound_asset_path)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path

SetSoundFireLastBullets

Sound when firing with only having X remaining bullets in the magazine, useful for last shot 'ping' or sound when low on bullets

my_weapon:SetSoundFireLastBullets(sound_asset_path, remaining_bullets_count)
TypeParameterDefault ValueDescription
Sound Asset or Special Pathsound_asset_path
numberremaining_bullets_count1The amount of remaining bullet to start playing this sound

SetSpread

Base Weapon's Spread (the higher the less precision - recommended value: 20)

my_weapon:SetSpread(spread)
TypeParameterDefault ValueDescription
numberspread

SetRecoil

Base Weapon's Recoil - 0 means no Recoil, default is 1

my_weapon:SetRecoil(damage)
TypeParameterDefault ValueDescription
numberrecoil

SetUsageSettings

Sets if the Weapon can hold to keep firing and if it needs to release to fire

my_weapon:SetUsageSettings(can_hold_use, hold_release_use)
TypeParameterDefault ValueDescription
booleancan_hold_use
booleanhold_release_use

SetWallbangSettings

Sets how the bullet will pass through walls

my_weapon:SetWallbangSettings(max_distance, damage_multiplier)
TypeParameterDefault ValueDescription
numbermax_distanceMax distance to pass through another wall
numberdamage_multiplierDamage given if wallbangged

GetAmmoBag

Gets this Weapon's Ammo Bag

Returns number

my_weapon:GetAmmoBag()

GetAmmoClip

Gets this Weapon's Ammo Clip

Returns number

my_weapon:GetAmmoClip()

GetAmmoToReload

Returns number

my_weapon:GetAmmoToReload()

GetHandlingMode

Returns HandlingMode

my_weapon:GetHandlingMode()

GetAnimationCharacterFire

Returns string

my_weapon:GetAnimationCharacterFire()

GetAnimationFire

Returns string

my_weapon:GetAnimationFire()

GetMagazineMesh

Returns string

my_weapon:GetMagazineMesh()

GetParticlesBulletTrail

Returns string

my_weapon:GetParticlesBulletTrail()

GetParticlesBarrel

Returns string

my_weapon:GetParticlesBarrel()

GetParticlesShells

Returns string

my_weapon:GetParticlesShells()

GetSoundDry

Returns string

my_weapon:GetSoundDry()

GetSoundLoad

Returns string

my_weapon:GetSoundLoad()

GetSoundUnload

Returns string

my_weapon:GetSoundUnload()

GetSoundZooming

Returns string

my_weapon:GetSoundZooming()

GetSoundAim

Returns string

my_weapon:GetSoundAim()

GetSoundFire

Returns string

my_weapon:GetSoundFire()

GetCanHoldUse

Returns string

my_weapon:GetCanHoldUse()

GetHoldReleaseUse

Returns boolean

my_weapon:GetHoldReleaseUse()

GetBulletCount

Returns boolean

my_weapon:GetBulletCount()

GetBulletColor

Returns Color

my_weapon:GetBulletColor()

GetCadence

Returns number

my_weapon:GetCadence()

GetClipCapacity

Returns number

my_weapon:GetClipCapacity()

GetDamage

Returns number

my_weapon:GetDamage()

GetRightHandOffset

Returns Vector

my_weapon:GetRightHandOffset()

GetLeftHandLocation

Returns Vector

my_weapon:GetLeftHandLocation()

GetLeftHandRotation

Returns Rotator

my_weapon:GetLeftHandRotation()

GetSightLocation

Returns Vector

my_weapon:GetSightLocation()

GetSightRotation

Returns Rotator

my_weapon:GetSightRotation()

GetSightFOVMultiplier

Returns number

my_weapon:GetSightFOVMultiplier()

GetSpread

Returns number

my_weapon:GetSpread()

GetRecoil

Returns number

my_weapon:GetRecoil()

Events Detailed

Fire

Triggered when Weapon fires (this will be triggered for each shot)

Weapon.Subscribe("Fire", function(self, shooter)

end)
TypeParameterDescription
Weaponself
Charactershooter

Reload

When a Weapon is reloaded, optionally by a Character

Weapon.Subscribe("Reload", function(self, character, ammo_to_reload)

end)
TypeParameterDescription
Weaponself
Charactercharacter
numberammo_to_reload