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

🔫 Weapon

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 AK47local new_weapon = Weapon(Vector(-900, 185, 215), Rotator(0, 90, 90), "nanos-world::SK_AK47", CollisionType.Normal, true)
-- Configures Weapon Base Settingsnew_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 Weaponnew_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 Particlesnew_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 Soundsnew_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 Animationsnew_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 reloadingnew_weapon:SetMagazineMesh("nanos-world::SM_AK47_Mag_Empty")
-- Configures the Crosshair Materialnew_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 AK47local my_ak47 = NanosWorldWeapons.AK47(Vector(1035, 154, 300), Rotator())
-- Giving the Weapon to a Charactermy_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)
stringmodel_nameSkeletal Mesh Path
CollisionTypecollision_typeCollisionType.Normal
booleangravity_enabledtrue

Functions#

Inherited Actor Functions
Base Actorscripting-reference/classes/base-classes/actor
ReturnsNameDescription
AddImpulseApplies a Force in world coordinate on this Actor
AttachToAttaches this Actor to any other Actor
DestroyDestroys this Actor
DetachDetaches this Actor if attached
SetCollisionSets the actor’s collision type
SetForceAdds a permanent force to this actor
SetGravityEnabledSets the actor’s gravity enabled
SetHighlightEnabledEnables this Actor Highlighting at a specific Index color
SetLifeSpanSets the actor’s life span to be destroyed
SetLocationSets the actor’s location in the game world
SetNetworkAuthoritySets this actor’s new Player Network Authority
SetRelativeLocationSets the actor’s relative location in local space
SetRelativeRotationSets the actor’s relative rotation in local space
SetRotationSets the actor’s rotation in the game world
SetScaleSets the actor’s scale
SetValueSets a value in this entity, which can be accessed by any package
TranslateToSmoothly moves this actor to a Location
RotateToSmoothly rotates this actor to a Rotation
booleanIsGravityEnabledGets the actor’s gravity enabled
booleanIsInWaterGets if the actor is in Water
booleanIsNetworkDistributedGets if the actor is Network Distributed
booleanIsValidReturns if this entity is valid (i.e. not destroyed)
tableGetAttachedEntitiesGets all actors attached to this entity
anyGetAttachedToGets the actor this actor is attached to
tableGetBoundsGets the actor bounds size
numberGetCollisionGets the current actor’s collision
numberGetIDGets the universal network ID of this entity
VectorGetLocationGet the actor’s position in the game world
VectorGetInitialLocationGets the initial location
RotatorGetRotationGets the actor’s rotation in the game world
VectorGetScaleGets the actor’s scale
stringGetTypeReturns the type of this Actor
anyGetValueGets a value given a key
VectorGetVelocityReturns the current actor Velocity
SubscribeSubscribes for an Event
UnsubscribeUnsubscribes from Events
Inherited Pickable Functions
Base Pickablescripting-reference/classes/base-classes/pickable
ReturnsNameDescription
AddSkeletalMeshAttachedSpawns and Attaches a SkeletalMesh into this Actor
AddStaticMeshAttachedSpawns and Attaches a StaticMesh into this Actor
PullUseForce this Pickable to be used
ReleaseUseForce this Pickable to be released the usage
RemoveSkeletalMeshAttachedRemoves, if existing, a SkeletalMesh from this Actor given it's custom ID
RemoveStaticMeshAttachedRemoves, if existing, a StaticMesh from this Actor given it's custom ID
SetCrosshairMaterialSets the Crosshair Material
stringGetAssetNameGets the Asset name
CharacterGetHandlerGets the Character (if existing) which is hol
Inherited Paintable Functions
Base Paintablescripting-reference/classes/base-classes/paintable
ReturnsNameDescription
SetMaterialReplace a materials of this actor with another Material
SetMaterialFromWebUIReplace a materials of this actor with a WebUI
SetMaterialColorParameterSets a Color parameter in this actor’s material
SetMaterialScalarParameterSets a scalar parameter in this actor’s material
SetMaterialTextureParameterLoads a image from computer (relative to Assets/ folder) and sets as parameter in this actor’s material
SetMaterialVectorParameterSets a Vector parameter in this actor’s material
ReturnsNameDescription
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 Entity is Destroyed
SpawnTriggered when an Entity is Spawned/Created
ValueChangeTriggered when an Entity has it’s value changed
Inherited Pickable Events
Base Pickablescripting-reference/classes/base-classes/pickable
NameDescription
DropWhen a Character drops this
HitWhen this Entity hits something
InteractTriggered when a Character tries to Pick up this
PickUpWhen a Character picks up this
PullUseWhen a Character Pulls the Usage of this (i.e. pulls Left Mouse button when using it)
ReleaseUseWhen a Character Releases the Usage of this (i.e. releases Left Mouse button when using it)
NameDescription
FireWhen Weapon is fired
ReloadWhen Weapon is reloaded

Functions Detailed#

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
stringanimation_asset_path

SetAnimationCharacterFire#

Animation played by the Character when Firing

my_weapon:SetAnimationCharacterFire(animation_asset_path)
TypeParameterDefault ValueDescription
stringanimation_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
stringanimation_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
stringstatic_mesh_asset_path

SetParticlesBulletTrail#

Particle of the Bullet flying

my_weapon:SetParticlesBulletTrail(particle_asset_path)
TypeParameterDefault ValueDescription
stringparticle_asset_path

SetParticlesBarrel#

Particle of the Fire Blast in the muzzle

my_weapon:SetParticlesBarrel(particle_asset_path)
TypeParameterDefault ValueDescription
stringparticle_asset_path

SetParticlesShells#

Particle of the empty bullet flying from the weapon when shooting

my_weapon:SetParticlesShells(particle_asset_path)
TypeParameterDefault ValueDescription
stringparticle_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
stringsound_asset_path

SetSoundLoad#

Sound when Loading a magazine

my_weapon:SetSoundLoad(sound_asset_path)
TypeParameterDefault ValueDescription
stringsound_asset_path

SetSoundUnload#

Sound when Unloading a magazine

my_weapon:SetSoundUnload(sound_asset_path)
TypeParameterDefault ValueDescription
stringsound_asset_path

SetSoundZooming#

Sound when Zooming

my_weapon:SetSoundZooming(sound_asset_path)
TypeParameterDefault ValueDescription
stringsound_asset_path

SetSoundAim#

Sound when Aiming

my_weapon:SetSoundAim(sound_asset_path)
TypeParameterDefault ValueDescription
stringsound_asset_path

SetSoundFire#

Sound when Shooting

my_weapon:SetSoundFire(sound_asset_path)
TypeParameterDefault ValueDescription
stringsound_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
stringsound_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