20 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

Weapons kit

Roblox offers the following prefab weapons to assist in creating competitive combat-based games. The core system features projectile-based weapons with an over-the-shoulder camera, and setting the projectile speed high enough can simulate raycasting weapons like laser guns.

Note

The content of this project and documentation can be used under Roblox's Limited Use License.

To use a prefab weapon in your game:

1. Select a weapon from below, navigating to the asset library link.

   

Pistol

 [![](https://prod.docsiteassets.roblox.com/assets/resources/weapons-kit/Weapon-Model-Shotgun.jpeg)][Marketplace-Shotgun]

Shotgun

 [![](https://prod.docsiteassets.roblox.com/assets/resources/weapons-kit/Weapon-Model-Auto-Rifle.jpeg)][Marketplace-Auto-Rifle]

Auto Rifle

Submachine Gun

Sniper Rifle

Crossbow

Grenade Launcher

Rocket Launcher

Railgun

1. On the weapon's item page, click the Get Model button and confirm the transaction.

2. In Studio, open the Toolbox and select your Inventory section.

   

3. Locate the weapon and click it to add it into the place. When prompted whether to put the tool into the starter pack, click Yes if you want players to start with the weapon in their backpack, or click No to simply place the weapon in the 3D world as a pickup.

4. If this is the first time bringing in a prefab weapon, move its WeaponsSystem folder into ServerScriptService to serve as the unified system folder for all prefab weapons in the game.

   

System folder structure

The WeaponsSystem folder is a unified folder that contains assets, configurations, and scripts that power all prefab weapons in the game. If located in ServerScriptService, it overrides any equivalent WeaponsSystem folders that may reside within individual weapons.

Within the WeaponsSystem folder, different aspects are controlled by the following ModuleScripts:

Weapon structure

Prefab weapons are tools and are named as they will appear in the player's backpack. Each weapon is structured with a similar hierarchy.

Weapon type

The WeaponType StringValue corresponds with the ModuleScript for the weapon in the WeaponsSystem/WeaponTypes folder. The two base values are BulletWeapon and BowWeapon.

Weapon model

Each weapon contains a Model made up of one or more BaseParts to form the physical weapon. One of these should be set as the model's PrimaryPart.

The model also includes the following important descendants which may be parented to one of the model's BaseParts:

• TipAttachment — Attachment whose position on the parent BasePart determines where bullets/projectiles come out.
• HandleAttachment — Attachment whose position on the parent BasePart determines where the tool's handle is welded.
• Fired — Sound that plays when the weapon is fired.
• Reload — Sound that plays when the weapon is reloaded.
• Additional descendants for any specialized options.

Configuration

The Configuration folder contains specific "value" types for weapon behavior. Beyond the defaults, you can add additional configuration items for specialized options when applicable.

As follows are the base configurations and their default values:

Specialized options

You can add/modify the following options for any weapon. These customizations require modifying either the weapon's Model, the weapon's Configuration, or both. Some configurations are dependent on others, such as muzzle particles which require the necessary children for projectile/hit effects and sounds.

Bolt animations and sounds

A weapon's bolt is the part that moves back and forth each time it's fired.

• Descendants of the weapon's weapon model:

  • Bolt — BasePart that moves when the weapon is fired.
  • BoltMotor — Motor6D used to animate the bolt. Make sure to set the motor's Part0 to the weapon model's PrimaryPart and Part1 to the Bolt part.
  • BoltMotorStart — Attachment whose position on the parent BasePart determines where the bolt is when it's at rest.
  • BoltMotorTarget — Attachment whose position on the parent BasePart determines where the bolt animates to when shooting.
  • BoltOpenSound — Sound that plays when the bolt opens.
  • BoltCloseSound — Sound that plays when the bolt closes.

• Descendants of the weapon's configuration folder:

  • ActionOpenTime — Time it takes for the bolt to animate to open position. Default is 0.025.
  • ActionCloseTime — Time it takes for the bolt to animate to closed position. Default is 0.075.

Ejected bullet casings

Weapons can include physical bullet casings that eject upon firing and fall to the ground.

• Descendants of the weapon's weapon model:

  • CasingEjectPoint — Attachment whose position on the parent BasePart determines where you want bullet casings to pop out. Note that its orientation determines the direction that casings pop out.

• Descendants of the weapon's configuration folder:

  • CasingEffect — Name of casing BasePart in Assets/Effects/Casings of the system folder.
  • CasingEjectSpeedMin — Minimum eject speed of casings. Default is 15.
  • CasingEjectSpeedMax — Maximum eject speed of casings. Default is 18.

• Child of the casing BasePart in Assets/Effects/Casings of the system folder:

  • CasingHitSound — Sound that plays when casings hit the ground.

Projectile/hit effects and sounds

You can configure physical projectiles for any weapon, along with Sounds, Beams, and ParticleEmitters for hit effects and other special effects.

• Descendants of the weapon's configuration folder:

  • ShotEffect — Name of a shot effect stored within Assets/Effects/Shots of the system folder.
  • ShouldMovePart — Set to true if the weapon's ShotEffect should move with the projectile or false if not. You should only set this to true if there's a visible object that moves with each shot, such as an arrow or rocket. Default is false.
  • BeamFadeTime — Time it takes for Beam0 or Beam1 (see below) to fade after the bullet/projectile hits something. By default, no manual fade will be applied by code. Default is 0.
  • BeamWidth0 — Thickness of Beam0 or Beam1 at Attachment0 (see below). Default is 1.5.
  • BeamWidth1 — Thickness of Beam0 or Beam1 at Attachment1 (see below). Default is 1.8.
  • NumHitParticles — Number of particles the HitParticles (see below) emitter will emit. Default is 3.
  • HitParticlesUsePartColor — Set to true if you want the hit particles to be the color of the hit surface; false if you want hit particles to not change color. Default is true.

• Descendants of the specified ShotEffect noted in the above section:

  • Flying — Sound that plays while the bullet/projectile is traveling.
  • Beam0 — First slot for a trailing Beam behind the bullet/projectile. Don't forget to set Attachment0 and Attachment1.
  • Beam1 — Second slot for a trailing Beam behind the bullet/projectile. Don't forget to set Attachment0 and Attachment1.
  • Attachment0 — Attachment whose position on the parent BasePart determines the back of trailing beams; make sure to set Beam.Attachment0 on both Beam0 and Beam1 to this.
  • Attachment1 — Attachment whose position on the parent BasePart determines the front of trailing beams; make sure to set Beam.Attachment1 on both Beam0 and Beam1 to this.
  • TrailParticles — ParticleEmitter parented as a direct child of Attachment0; this will emit while the bullet/projectile is traveling.
  • LeadingParticles — ParticleEmitter parented as a direct child of Attachment1; this will emit while the bullet/projectile is traveling.
  • HitEffect — Attachment whose position will be set to Beam.Attachment1 of Beam0 when the bullet/projectile hits. You must specify Beam0 and its attachments for this to work properly.
  • HitSound — Sound parented as a direct child of HitEffect; plays when the bullet/projectile hits.
  • HitParticles — Sound parented as a direct child of HitEffect; emits when the bullet/projectile hits.
  • Mesh — SpecialMesh that you want to appear as a physical projectile. Make sure you set ShouldMovePart in the weapon's configuration to true if you have a visible object here.

Muzzle particles

This option emits particles from the specified ParticleEmitter at the weapon's TipAttachment Attachment when it's fired. Descendants of the weapon's configuration folder include:

• ShotEffect — Name of a shot effect stored within WeaponsSystem/Assets/Effects/Shots. As a child of this shot effect, include a ParticleEmitter asset named MuzzleParticles.
• NumMuzzleParticles — Number of muzzle particles that will be emitted. Default is 50.

Muzzle flashes

This option creates a Beam flash effect when the weapon is fired.

• Descendants of the weapon's weapon model:

  • MuzzleFlash0 — Attachment used to specify one side of muzzle flash. Position doesn't matter.
  • MuzzleFlash1 — Attachment used to specify opposite side of muzzle flash. Position doesn't matter.
  • MuzzleFlash — Beam for the muzzle flash effect. Make sure to set the beam's Attachment0 to MuzzleFlash0 and Attachment1 to MuzzleFlash1.

• Descendants of the weapon's configuration folder:

  • MuzzleFlashTime — Length of time muzzle flash will show for. Default is 0.03.
  • MuzzleFlashRotation0 — Minimum rotation of muzzle flash. Default is -math.pi.
  • MuzzleFlashRotation1 — Maximum rotation of muzzle flash. Default is math.pi.
  • MuzzleFlashSize0 — Minimum size of muzzle flash. Default is 1.
  • MuzzleFlashSize1 — Maximum size of muzzle flash. Default is 1.

Particle trails

This option creates a trail of varying length from the weapon to the projectile impact point. Descendants of the weapon's configuration folder include:

• TrailLength — Length of trail behind bullet/projectile; default is nil which means the trail length will instead be calculated using TrailLengthFactor.
• TrailLengthFactor — If specified, the trail length will be set to this value multiplied by the distance the bullet/projectile traveled in the last frame; default is 1. Note that this will be overridden if you include TrailLength.
• ShowEntireTrailUntilHit — Set to true to render the trail from the weapon tip all the way to wherever the projectile is; this will override both TrailLength and TrailLengthFactor and the trail will only disappear once the projectile hits something. Set to false to use one of the above two options to calculate trail length. Default is false.

Hit marks

This visual addition appears on the surface where projectiles hit and is useful for arrows, bullet holes, scorch marks, etc. Descendants of the weapon's configuration folder include:

• HitMarkEffect — Name of a Part/MeshPart/SpecialMesh hit mark effect stored within WeaponsSystem/Assets/Effects/HitMarks. Default is BulletHole.
• AlignHitMarkToNormal — Set to true if the hit mark should always align flat against the surface like a bullet hole, or false if the hit mark should appear stuck in the surface from the direction the projectile came from (like an arrow). Default is true.

As noted by HitMarkEffect above, you can add a part/mesh within WeaponsSystem/Assets/Effects/HitMarks to appear as a physical projectile. For example, including an arrow MeshPart and setting AlignHitMarkToNormal to false will make the arrow stick out of the surface from the direction you shot it. This Part/MeshPart/SpecialMesh may contain the following descendants:

• Glow — Decal which appears on the hit surface fully opaque, then rapidly gets more transparent, like a glowing effect on the surface that fades quickly. Useful for things like showing a glowing red mark where explosives hit.
• BulletHole — Decal which appears on the hit surface fully opaque and, after 4 seconds, fades to transparent over 1 second.
• ImpactBillboard — BillboardGui which displays at the hit surface, always facing towards the camera.
• Impact — ImageLabel as a direct child of ImpactBillboard; this begins fully opaque, grows to the full size of the ImpactBillboard over 0.1 seconds, then shrinks to half its size and fades to full transparency over 0.1 seconds.

Exploding projectiles

Projectiles can include an Explosion object to damage player characters in an area around the impact point. Descendants of the weapon's configuration folder include:

• ExplodeOnImpact — Set to true if you want bullets/projectiles for the weapon to explode on impact, false otherwise. Default is false.
• BlastRadius — BlastRadius of explosion; default is 8.
• BlastPressure — BlastPressure of explosion; default is 10000.
• BlastDamage — Damage dealt to things in the center of the explosion. Note that the explosion does less damage the farther away hit objects are from the center of the explosion. Default is 100.

Charging weapon

A charging weapon like the Railgun must be charged up between shots before it can fire again.

• Descendants of the weapon's weapon model:

  • Charging — Sound which plays while the weapon is charging.
  • Discharging — Sound which plays while the weapon is discharging, for example if you charge the weapon just partially and release the shoot button.
  • ChargeComplete — Sound which plays when the weapon has reached full charge.
  • DischargeComplete — Sound which plays when the weapon has completely discharged.
  • ChargeGlow — BasePart which will get less transparent as the weapon charges up, such that it will be fully opaque at 100% charge.
  • ChargeCompleteParticles — ParticleEmitter which emits when the weapon has finished charging. This emitter can be a child of any model BasePart or a child of an Attachment within the BasePart.
  • DischargeCompleteParticles — ParticleEmitter which emits when the weapon has completely discharged. This emitter can be a child of any model BasePart or a child of an Attachment within the BasePart.
  • ChargingParticles — ParticleEmitter which emits while the weapon is charging. You can include multiple emitters of this name and each will emit while charging. This emitter can be a child of any model BasePart or a child of an Attachment within the BasePart.

• Descendants of the weapon's configuration folder:

  • ChargeRate — Rate at which the weapon will charge. This value must be specified to indicate that the weapon uses charging.
  • DischargeRate — Rate at which the weapon will discharge. Default is 0 which means the weapon will not discharge at all.
  • ChargePassively — Set to true if you want the weapon to passively charge so it will shoot instantly when you click, or false if you want to click/touch to charge the weapon and have it fire once full charge is reached. Default is false.
  • ChargingParticlesRatePerCharge — Number of particles that will emit out of all ChargingParticles emitters multiplied by the current charge of the weapon. Default is 20, meaning that if the weapon charge is at 10%, each ChargingParticles emitter will emit 2 particles (20*0.1), and if the weapon charge is at 90%, each emitter will emit 18 particles (20*0.9).
  • FireDischarge — Amount of charge the weapon will lose after firing a fully charged shot. Default is 1.
  • NumChargeCompleteParticles — Number of particles the ChargeCompleteParticles emitter will emit once the weapon is fully charged. Default is 25.
  • NumDischargeCompleteParticles — Number of particles the DischargeCompleteParticles emitter will emit when the weapon is completely discharged. Default is 25.

Bow weapon

A bow weapon like the Crossbow can include a realistic string and arms construction, as well as a visual arrow nocked to the string.

In addition to adding model descendants, you need to apply the following:

• Make the weapon into a charging weapon. For example, add the required ChargeRate within the weapon's Configuration that specifies how fast the string is drawn. Additionally, consider adding optional descendants to the weapon's Model such as a Charging sound for the string/arms being pulled back.
• Set the WeaponType to BowWeapon as indicated in weapon structure.

Descendants of the weapon's weapon model include:

• LeftString — Beam for the visual left half of the string.
• RightString — Beam for the visual right half of the string.
• Arrow — BasePart for the arrow that appears when the bow is fully drawn. Note that this is only for visual appearance on the bow (the actual fired arrow will be a ShotEffect as outlined in projectile/hit effects and sounds).
• String1 — Attachment for the center point of the string.
• StringLoose — Attachment point where String1 should be when the bow is at rest.
• StringTight — Attachment point where String1 should be when the bow is fully drawn.
• Arms — Part that just serves as an internal indicator that the bow arms will be animated. This may contain the following direct children:
  • LeftString0 — Attachment point where the left side of the string is attached to the bow.
  • RightString0 — Attachment point where the right side of the string is attached to the bow.
  • LeftLoose — Attachment point where LeftString0 should be when the bow is at rest.
  • RightLoose — Attachment point where RightString0 should be when the bow is at rest.
  • LeftTight — Attachment point where LeftString0 should be when the bow is fully drawn.
  • RightTight — Attachment point where RightString0 should be when the bow is fully drawn.
  • Mesh — SpecialMesh part of the bow that will actually bend when the bow is drawn. Note that you must specify the following four Vector3Value objects to make this animate.
    • LooseOffset — Vector3Value offset of the SpecialMesh when the bow is at rest.
    • TightOffset — Vector3Value offset of the SpecialMesh when the bow is fully drawn.
    • LooseScale — Vector3Value scale of the SpecialMesh when the bow is at rest.
    • TightScale — Vector3Value scale of the SpecialMesh when the bow is fully drawn.

Weapons GUI

The core weapons system interfaces with this system to update the GUI based on things like spread of the gun, indicators for when you get hit or hit others, etc.

The WeaponsSystemGui is a ScreenGui object in WeaponsSystem/Assets that is parented to PlayerGui when the game starts. WeaponSystemGui has four descendants as follows:

• ScalingElements is a Folder with the following descendants:

  • DirectionalIndicators — Folder where all directional indicators are stored.
  • Crosshair — A Frame containing a UIAspectRatioConstraint and image labels for the bottom, left, right, and top elements of the crosshair.
  • HitMarker — A Frame containing a UIAspectRatioConstraint and a HitMarkerImage image label that appears and fades when the player successfully hits another player character.

• LargeTouchscreen is a Frame containing AimButton and FireButton buttons that display on large touchscreens.

• Scope is a Frame that contains the ScopeImage image label which shows up when zooming on a weapon with HasScope enabled (see weapon structure).

• SmallTouchscreen is a Frame containing AimButton and FireButton buttons that display on small touchscreens.

Directional indicators

Directional indicators are used to show the direction of something around the player's crosshair. For example, if someone shoots you, a red semi-circle can show up around your crosshair in the direction the shot came from. Other examples include indicators to show the direction of footsteps, indirect gunfire, or even environmental objects such as chests.

To create a new indicator, add a new Frame in WeaponsSystemGui/ScalingElements/DirectionalIndicators with the following structure:

• Indicator (Frame)
  • UIAspectRatioConstraint
  • ImageLabel for the directional indicator. Tweaking the rotation of the image in Studio may be required unless you upload the image so that it's facing down and there's little or no blank space around it. This image label must also contain its own UIAspectRatioConstraint.
  • Configuration containing optional properties to adjust:
    • DistanceLevelFromCenter — Number of distance levels from the center of the screen (each distance level is about 0.03 screen scale). Default is 6.
    • FadeTime — Indicator fade time following its activation and the TimeBeforeFade time. Default is 1.
    • Name — Name of the directional indicator as you want to reference it in code. Default is the name of the indicator's top-level Frame.
    • TimeBeforeFade — Number of seconds that the indicator will appear for before fading. Default is 1.
    • TransparencyBeforeFade — Transparency of the indicator before it starts to fade. Default is 0.
    • WidthLevel — Number of width levels from center (each width level is about 0.03 screen scale). Default is the value of DistanceLevelFromCenter.

Once created, you can activate an indicator via the following command inside WeaponsSystem/Libraries/WeaponsGui where indicatorName is the string name of the indicator to activate and worldPos is the world position where the directional indicator should point:

self.DirectionalIndicatorGuiManager:ActivateDirectionalIndicator(indicatorName, worldPos)

Note

If an indicator is activated an additional time before it has had time to fade completely, a new indicator of that type will be instantiated. This allows an unlimited number of any type of indicator to be activated at the same time.

You can also activate directional indicators from outside of WeaponsGui by replacing self in the above code with the instance of WeaponsGui in your code. However, it's recommended that you activate it from inside WeaponsGui and trigger it via a RemoteEvent or a BindableEvent. For reference, see how DamageIndicator is activated within WeaponsGui.

Damage billboard

The damage billboard is used to show numbers above a character's head when they are damaged. These will only show up for the player that damaged another player's character, not for spectating players.

Damage billboards are handled in WeaponsSystem/Libraries/DamageBillboardHandler and can be activated from any client-side code as follows, where damage is the amount of damage done and adornmentPart is the part on which to adorn the billboard, such as the victim's head:

DamageBillboardHandler:ShowDamageBillboard(damage, adornmentPart)

Shoulder camera

The shoulder camera is a third-person camera that looks over the player character's right shoulder. To customize the shoulder camera, modify the variables under the -- Configuration parameters (constants) comment in the ShoulderCamera.new() function of WeaponsSystem/Libraries/ShoulderCamera. You can modify things such as field of view, offset from the character, walk speed while sprinting or zooming, etc.

Sprint and zoom

By default, the weapons system adds "sprint" capability so players can sprint by holding the Shift key, pushing fully up on the dynamic thumbstick (mobile), or pushing fully up on the left joystick (gamepad). If you want to disable sprinting, set the value of SprintEnabled within WeaponsSystem/Configuration to false.

The system also reduces player speed while they're aiming/zooming, but you can disable this behavior by setting the value of SlowZoomWalkEnabled within WeaponsSystem/Configuration to false.