XSF Docs

What XSF is #

XSF is a first person shooter framework for Roblox. You drop it into your place and you get the whole gun side of a shooter in one go: weapons that feel heavy in your hands, real bullets that drop and go through walls, recoil you can learn, positional sound, leaning, crouching, prone, sliding, vaulting, a downed and revive system, explosives, pickups, attachments, skins and the menus that go with all of it. It works on PC, console, phones and tablets, with R6 and R15 characters.

What it doesn't do is make your game for you. There are no maps, rounds, teams, scoreboards or shops built in. That part is yours. XSF gives you the shooting and the feel, plus a server and client API so your own scripts can hand out guns, react to kills, sell skins or run a battle royale on top of it.

Two ways to set it up

You can mix both, and most people do:

• The website dashboard. No code. Pick a game style, a camera, a loadout and tweak sliders. Every game running XSF with your key reads it when a server starts.
• Studio. Open GameConfig and each weapon's Config and change the values directly. Everything is commented, so you rarely need to look anything up.

If the same setting is changed in both places, the Studio value wins in that game. That rule is explained properly in Presets and Studio.

What makes it feel different

• Bullets are real projectiles. They have a speed in meters per second, they drop over distance, they lose power going through walls and they can skip off concrete or metal at a shallow angle. Nothing is a hitscan ray.
• The server checks every shot. Your screen fires the bullet so it feels instant, then the server simulates the same bullet again and decides what it hit. An exploiter can't just tell the server "I hit that guy in the head".
• Lag is accounted for. The server rewinds other players to where they were when you pulled the trigger, so a hit on your screen is a hit on the server, within reason.
• Everything moves on springs. Recoil, sway, bob and inertia are spring simulations, not canned animations. They feel the same at 60 fps and at 240 fps.
• Hands that actually hold the gun. The realistic arms pose every finger against the real shape of each gun when it's drawn, so the hand wraps the grip and the finger sits on the trigger. Custom guns get this too.

How these docs are laid out

The left column is the table of contents, and the search box at the top of it filters by section titles and text. Roughly:

• Start here gets XSF into your place and running, and explains how the pieces fit together.
• Set up your game is everything you can change without writing code: the dashboard, GameConfig, keys, camera, movement and so on.
• Weapons covers every gun setting, attachments, skins, damage, explosives and how to add your own guns.
• Scripting is the API for your own Scripts and LocalScripts, plus copy and paste recipes for common game modes.
• Help is testing, performance, error messages and fixes for the problems people actually run into.

New in 2.1 #

2.1 is mostly what developers building on 2.0 asked for: empty hands, menus that never shoot, crouch and slide poses other players can see on R6, and a lot more hooks for your own scripts. Nothing in your game changes unless you turn it on, apart from the fixes. To update from 2.0, see Updating from 2.0 to 2.1.

Empty hands

Press Y, or the number key of the gun you're holding, to put it away. The gun leaves your hands for everyone, and the server won't accept shots until a weapon is out again. In first person you see your hands: relaxed when standing, swinging as you walk and pumping when you run, with every arms style. See Holster.

Crouch and slide on R6

Other players now see an R6 character kneel when it crouches and lean back with its legs out when it slides, and the server lowers its hitboxes to match. R15 already bent at the knees. See Movement and stances.

Menus and clicks

A click on your UI never fires the gun, and the click that closes a menu doesn't either. Hold Left Alt to free the cursor for a moment. Your own menus get SetMenuOpen, which frees the mouse and stops XSF reading input, and a GuiButton with Modal = true works like it does in any Roblox game. Clicking empty space inside the settings menu no longer closes it. See Menus and the mouse.

Quick throw

Two new keybinds, QuickLethal and QuickTactical, throw your first grenade of that kind without switching to it, cook it while held, and go back to your gun. They're unbound by default; bind them in GameConfig or let players set them. See Keys and key names.

New GameConfig options

• Movement.SprintReload: keep sprinting through a reload. See Movement.
• Throwables: the arc, lift, gravity, bounce, friction, spin and roll of grenades, for every throwable or one at a time. See Throwables.
• Audio.CutFade, Audio.Voices, Audio.StealFade, Audio.ParentGroup and Audio.StepSets (your own footsteps per floor material). Per gun: Sounds.Fade and Sounds.Tail, and lists of takes for FireSuppressed and FireThird. See Audio.
• Holster: empty hands, the number key rule and the hands. See Holster.
• Customization.Required (slots players can't leave empty) and Customization.Access = "Off". See Customization.
• SettingsSave: save player settings on the XSF site, only in your game, or not at all. UseWebsite = false runs the game on GameConfig alone. See Preset and the website.
• New keybinds: Holster, Pickup, QuickLethal, QuickTactical, FreeCursor.
• The GameConfig that ships now has GiveLoadout, Vault, Pickups, Ragdoll, Damage.Modify and Debug.LogRejects written in, so you don't have to look them up.

More for your scripts

• Server: GetInventory, GetAmmo, GetAttachments, SetCustomizeCheck, a from and weapon option on Damage, and the Equipped, Holstered and Reloaded events. See Server scripts.
• Client: IsDown, GetMovementState, OnMovement, AddSpeedModifier, SetMenuOpen, SetHUDVisible, the kit functions (GetKit, SetKit and friends), SetGunshotHandler, OnReady, GetAllSettings, and signals for input, menus, equip, holster, reloads, new arms and other players' shots. See Client scripts.

Fixes

• A second grenade could be thrown after LoadCharacter while one was cooking.
• SetLoadout left the player with nothing equipped on the server, so shots were refused until they switched weapons.
• The settings menu and loadout screen are easier to use with a controller: the D-pad stays inside the menu and moves through tabs and rows in order.
• Clicking empty space in the settings menu closed it and fired the gun. Pressing P could close the menu and open it again straight away.
• Players with nothing in their hands couldn't sprint.
• When every copy of a sound is busy, the oldest one now fades out instead of cutting off with a click.
• If your game removes the character without killing it, XSF's hotbar and scope overlay no longer stay on screen.

New in 2.0 #

2.0 is the biggest update XSF has had. If you're coming from 1.3, read Updating to 2.0 first so you don't lose your changes, then skim the parts below that matter for your game.

59 weapons, up from 20

Rifles, battle rifles, machine guns, SMGs, bolt action and semi auto snipers, pump, semi and full auto shotguns, pistols, a revolver, seven knives, three grenades, C4, a claymore and two launchers. Every one has its own sound, recoil, damage profile and inspect. The full list with every number is in Every weapon's stats.

Explosives

The RPG-7 fires a rocket that leaves the tube slowly and then lights its motor. The M320 lobs a 40mm grenade on a real arc with a range ladder. C4 sticks to whatever it hits and goes off on right click. The claymore sits facing where you put it and fires a fan of steel at the first enemy in front. Blast damage checks for cover, so a wall really saves you. See Explosives.

Pickups

Players can drop the gun in their hands and pick up someone else's, attachments, skin and ammo included. Dead players drop their gun. Your scripts can spawn guns and ammo boxes anywhere, which is most of a battle royale loot system already. See Pickups.

Zeroing, night vision and thermal

Snipers, DMRs and the M320 have range steps you change with ] and [. Two new sights, Night Vision and Thermal, change what you see through the scope. See Zeroing and special optics.

Vault and mantle

Run at a low wall and jump to vault it. Jump at a ledge you can reach and you climb up. The left hand plants on the edge and the camera dips with you. It works on any part in your map with no setup. See Vault and mantle.

108 skins and an unlock system

Skins from plain Matte Black up to Galaxy and Damascus, in five rarities. By default players only get the attachments and skins your game gives them, so you can sell them, put them in crates or tie them to levels with a few lines of code. See Skins and Unlocks.

Proper reloads

Bolt actions work the bolt by hand. The Kar98k and Mosin reload with stripper clips. The revolver swings its cylinder out, punches the cases and uses a speedloader. Pump shotguns load shell by shell. The M320 breaks open, the RPG takes a warhead in the front. See Reloads and feeds.

Every attachment fits every gun

Before 2.0 an attachment only looked right on the guns it was made for. Now XSF measures each attachment and seats it from its real shape, so an ACOG sits on the rail of a SCAR as well as it sits on an M4.

A self test and a test map

Press F6 in a Studio playtest and XSF equips, fires, aims, reloads and inspects every weapon in your game, then prints a pass or fail line for each. The download also has an optional test map with a house, a range, a vault course, penetration walls and an explosives yard. See Testing your game.

Fixes

• The echo after every shot is gone.
• Indoor sound is muffled properly.
• Bare arms no longer glow with layered clothing.
• A flashbang error is fixed.
• Skinned guns no longer show a second copy of themselves (fixed in the current 2.0.0 download, so re-download if you grabbed it on day one).

Install in 3 minutes #

The download is a single .rbxmx file. Inside it everything is already sorted into folders named after where they go, so installing is really just matching names. Do it once and you'll never think about it again.

1. Download

Sign in on your account page and download XSF-2.1.0.rbxmx. Your license is baked into the file, so there's no key to paste anywhere. Don't share the file: it's tied to your account, and every game that runs it shows up on your dashboard.

The very first time you download, the site offers a one minute setup of your game (four questions). It's optional. Skip it and XSF runs with its shipped defaults, and you can run the setup later from the dashboard. See Website dashboard.

2. Put it in Studio

Open your place in Studio and drag the file into the 3D view. You can also right click Workspace in the Explorer and pick Insert from File. A folder called XSF_Release appears in Workspace. Open it and you'll see this:

XSF_Release
├── ReplicatedStorage        (a folder)
│   └── XSF
├── ServerScriptService      (a folder)
│   └── XSF
├── StarterPlayerScripts     (a folder)
│   └── XSF_Boot
├── ServerStorage            (a folder, optional)
│   └── XSF_Tools
├── Workspace                (a folder, optional)
│   └── XSF_TestMap
├── _README
└── _ABOUT_THIS_MODEL

3. Match the names

Each folder inside XSF_Release is named after a service in your Explorer. Drag what's inside each folder to the service with the same name:

Drag the XSF folder itself, not the folder around it. If you end up with ReplicatedStorage.ReplicatedStorage.XSF, you dragged one level too high. Move the inner XSF up and delete the empty folder.

4. Clean up and turn on HTTP

1. Delete the now empty XSF_Release folder from Workspace. Leaving it there doesn't break anything, but it's clutter.
2. Open Home > Game Settings > Security and turn on Allow HTTP Requests, then save. XSF uses HTTP to check its license, save player settings and read your dashboard. Without it XSF still runs, but settings fall back to DataStores and the dashboard is ignored.
3. If you want player settings to save while testing in Studio without HTTP, also turn on Enable Studio Access to API Services on the same page.

5. Check it

Your Explorer should now have exactly these three things:

ReplicatedStorage
└── XSF                  (GameConfig, Weapons, Assets, Client, Shared ...)
ServerScriptService
└── XSF                  (Main, Server, Weapons, Damage ...)
StarterPlayer
└── StarterPlayerScripts
    └── XSF_Boot

Press Play. You should spawn holding the first weapon of the default loadout (the HK416), with the rest on the hotbar along the bottom of the screen. Press 1 to 5 to switch, B to see the whole backpack.

Things to remove first

• Other gun systems. ACS, FE Gun Kit, Carbon and so on all want the camera and the mouse. Two frameworks fighting over the camera is a mess. Remove the old one before testing XSF.
• Custom camera scripts that force first person or move the camera every frame. XSF runs its own camera. If you need the camera for a cutscene, use SetCameraEnabled(false) from the client API.
• Scripts that change WalkSpeed every frame. XSF sets WalkSpeed itself for sprinting, aiming, crouching and reloading. Change speeds in GameConfig instead.

What goes where #

Once installed, this is what you're looking at and which parts you're meant to touch.

Most of the code is protected and can't be read or edited. GameConfig, the weapon Configs and the two API modules are left readable on purpose, so you can set things up and script around XSF without ever needing the inside.

Folders XSF makes at runtime

While a game runs you'll see a few folders appear in Workspace. They're XSF's, so leave them alone and don't parent your own things into them:

Your first game #

Here's a full walk through from an empty baseplate to a small team deathmatch you can play with friends. It takes about fifteen minutes and touches most of what you'll use later. If you already know what you want, skip ahead, nothing here is required.

Step 1: install and press Play

Do the install, drop in XSF_TestMap if you don't have a map yet, and press Play. Walk around. Try the basics so you know what the defaults feel like:

• Left click fires, right click aims, R reloads, V switches fire mode.
• Shift sprints, C crouches, C while sprinting slides, Z goes prone, Q and E lean.
• Run at a low wall and press Space to vault it.
• N opens the loadout screen, where you fit attachments. P opens settings.
• Press 1 to 5 to switch weapons, and B to open the backpack with the rest.

It ships with the Bodycam camera and free aim on, which is a strong look. If you want a normal shooter feel, that's two lines in step 2.

Step 2: pick the feel

Open ReplicatedStorage.XSF.GameConfig. For a regular arcade style shooter, change these:

Camera = {
	Style = "Standard", -- was "Bodycam"
	-- leave the rest of Camera as it is
},
FreeAim = {
	Enabled = false, -- gun locked to the centre of the screen
},
Damage = {
	FriendlyFire = false,
	Hitmarkers = true, -- a small marker when your shots land
},

Don't retype whole tables. Find the line and change the value. Anything you don't touch keeps working as before. Press Play again to try it.

Step 3: choose the guns

Still in GameConfig, set Loadout to what each player spawns with. The first five go on the number keys.

Loadout = { "M4A1", "MP5", "G17", "KaBar", "M67" },

The names are folder names from XSF.Weapons, spelled exactly the same. The full list is in Choosing the weapons.

Step 4: add teams

XSF uses normal Roblox Teams. Insert two Teams under the Teams service (Model tab, then Service, if you don't see it), name them Red and Blue, give them colours and turn AutoAssignable on for both. Add a SpawnLocation for each team with its TeamColor set to match and Neutral off.

That's all XSF needs. With Damage.FriendlyFire = false, players on the same team can't hurt each other, and with downed on, only teammates can revive.

Step 5: count kills

Add a Script to ServerScriptService. This gives each player a Kills and Deaths counter on the leaderboard and fills them from XSF's events:

local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

Players.PlayerAdded:Connect(function(player)
	local stats = Instance.new("Folder")
	stats.Name = "leaderstats"
	local kills = Instance.new("IntValue")
	kills.Name = "Kills"
	kills.Parent = stats
	local deaths = Instance.new("IntValue")
	deaths.Name = "Deaths"
	deaths.Parent = stats
	stats.Parent = player
end)

XSF.Killed:Connect(function(victim, attacker, weapon)
	local victimPlayer = Players:GetPlayerFromCharacter(victim.Parent)
	if victimPlayer then
		victimPlayer.leaderstats.Deaths.Value += 1
	end
	if attacker and attacker ~= victimPlayer then
		attacker.leaderstats.Kills.Value += 1
	end
end)

Killed fires for every death caused by XSF damage, including bleeding out after being downed, with the player who did it. You don't have to track who shot whom yourself.

Step 6: make it fair

A few choices that matter a lot for a deathmatch:

• Downed or not? Downed and revive is great for squads and terrible for quick respawn games. For TDM turn it off: Downed = { Enabled = false } (keep the other lines).
• Armour. Without armour everyone takes full damage. If you want body armour, set XSF_Armor on characters, see How damage works.
• Unlocks. By default players only own the FMJ ammo and each gun's own attachments. That's what you want if you plan to sell or unlock attachments later. If you want everyone to have everything from the start, set Customization.Ownership = { Attachments = false, Skins = false }. See Unlocks.

Step 7: test with real players

In Studio, open the Test tab, set the player count to 2 or 3 and press Start. You get a server window and one window per player, which is the only proper way to test hits, revives and team rules on your own. When it plays well, publish it, turn on HTTP in the live game's settings if you haven't, and invite people.

Where to go next

• Fine tune everything from the dashboard without republishing.
• Change gun stats in Weapon settings.
• Build a shop, a leveling system or a main menu with the Recipes.

How XSF works #

You don't need any of this to use XSF. It helps when something behaves in a way you didn't expect, or when you start scripting.

Two halves

XSF has a client half and a server half, like every Roblox game.

• The client (in ReplicatedStorage.XSF.Client, started by XSF_Boot) runs on each player. It handles input, the camera, the first person arms and gun, recoil, sounds, effects, the HUD and menus. It fires bullets on your screen the moment you click, so shooting never feels delayed.
• The server (in ServerScriptService.XSF) is the referee. It owns everyone's inventory and ammo, simulates every bullet again, decides what was hit, applies damage, runs downed and revive, explosions and pickups, and saves settings and unlocks.

The client asks, the server decides. If the client says "I fired", the server checks the player is alive, holding that gun, has ammo, isn't firing faster than the gun can, and that the shot started near where the player actually is. Shots that don't add up are thrown away and fire the Rejected event (see Server scripts).

What happens when you pull the trigger

1. Your client spawns the bullet at the muzzle, plays the shot, kicks the camera and starts simulating the round with gravity and speed.
2. It tells the server what it fired and where it was pointing.
3. The server validates the shot, then rewinds every other player to where they were at the moment you fired (this is lag compensation, it keeps up to about a second of history).
4. The server simulates the same bullet through that rewound world, through walls if it has the power, and finds what it hit.
5. Damage is worked out from the body part, the gun, the ammo, distance, walls and armour, then applied. See How damage works.
6. The shooter gets a hit confirm, the victim gets a hurt effect, and everyone else hears the shot with distance and walls taken into account.

Configs are merged, not replaced

XSF builds its final settings in layers, from the bottom up:

1. Built in defaults (in XSF.Shared.Defaults and XSF.Shared.WeaponDefaults).
2. The website preset for this game, if there is one.
3. Anything you changed in Studio, in GameConfig and the weapon Configs.

So a weapon Config only needs the lines that differ from the defaults, and GameConfig can lose any line without breaking. Delete Movement.ProneSpeed and XSF quietly uses 3.2. The full rules for how the website and Studio combine are in Presets and Studio.

Players don't have to be the only targets

Anything in Workspace with a Humanoid can be shot, takes damage by body part, ragdolls and fires the same events. XSF finds new ones automatically, so NPCs and dummies just work. See NPCs with guns.

Settings follow the player

A player's settings (sensitivity, FOV, keybinds, attachment choices and presets) are saved on the XSF site, so they carry across every server and every game that uses XSF. If HTTP is off they save to the game's own DataStore instead. A game can change where they are saved, or turn saving off, with SettingsSave in GameConfig (see Preset and the website).

Units

Website dashboard #

Open xsfshooter.vercel.app/dashboard (or the dashboard button on your account page) to set XSF up without touching code. Everything you do there is saved on your account. Every game that runs XSF with your key reads it the next time one of its servers starts.

The dashboard is the fastest way to try things. Change walk speed, press Play in Studio, feel it, change it again. No republishing, no editing Lua. When something feels right you can leave it on the website forever or copy it into GameConfig, whichever you prefer.

The quick setup

The first time you download XSF, the site asks four questions before the download starts. It takes about a minute and Skip setup is always there. You can run it again from the Setup tab whenever you like.

1. Game style. Picks a starting point for movement, health, aiming and combat. Each card lists what it changes, so nothing happens behind your back.
2. Camera and body. Standard or Bodycam camera, and realistic gloved arms or the classic blocky ACS arms. Picking a style also picks the camera it's built around, and you can change it here.
3. Loadout. Tap weapons to add or remove them. The numbers show which ones go on the hotbar keys, the rest wait in the backpack. Select all and Clear do what they say.
4. Platforms. Computer, console, phone and tablet, as many as you like. Console keeps aim assist and vibration on. Phone and tablet turn on low effects by default and use a 4 slot hotbar that fits small screens.

The review screen lists every setting your answers change, in plain words. Save and download saves it as your Default preset and starts the download. Save and fine tune saves it and opens the Settings tab. Running the setup again replaces Default with the new answers, so if you've hand tuned Default, copy it to a new preset first.

Here's exactly what each game style sets. Anything not listed stays at XSF's default.

The styles are starting points, not modes. Pick the closest one and change what you don't like. Battle royale with hitmarkers off is fine. Tactical with Standard camera is fine.

Settings

Every common GameConfig option, grouped and explained in plain words. Changes save by themselves (watch the save note in the corner), and anything you leave alone keeps XSF's default. Each setting has a reset button. The search box finds a setting by name or description. Settings that only matter for another setting (Bodycam field of view only matters with the Bodycam camera) only show up when they apply.

A small STUDIO tag on a setting means one of your games changed it in Studio, so that game keeps its own value for it. See Presets and Studio.

This is every setting on the website, the GameConfig option it writes, the default and the range the slider allows:

Options that aren't on the website (keybinds, ballistics, slide timings, aim assist angle and a few more) are Studio only. Set them in GameConfig.

Weapons

The top card is the spawn loadout: tap a weapon to add or remove it, and use the arrows to change the order. The first ones in the list go on the hotbar keys. Under it, tap any weapon to change its stats. A stat you change gets a mark, and the reset button puts it back to how XSF ships the gun. Knives only have damage, and grenades have no stats here.

Recoil is one multiplier for the whole recoil of the gun: 1 is normal, 0.5 halves every kick and climb, 2 doubles them. It only applies when that gun's Recoil table hasn't been changed in Studio. If you want to shape recoil (more climb, less sideways, a pattern), do it in the gun's Config, see Recoil and sway.

Presets

A preset is one full setup: settings, weapon stats and loadout together. You can have up to 20. Names can use letters, numbers, spaces, - and _, up to 32 characters. New preset starts empty or as a copy of the one you're editing, and every preset can be copied, renamed or deleted. The Editing preset picker at the top of Settings and Weapons decides which preset your changes go into. Check it before you start changing things. Editing the wrong preset is the most common reason "my change didn't do anything".

Good uses for presets:

• One preset per game, when you run several games on one account.
• One preset per mode in the same game, picked with Preset = "Name" in a separate place (a TDM place and a hardcore place in the same universe).
• A test preset you try in Studio before switching your live game over to it.

Games

Every game that has started XSF with your key shows up here, with when it was last seen and which XSF version it runs. For each game you can:

• Pick which preset it uses. Games you never pick for use Default.
• See how many settings it changes in Studio. Those keep the Studio value in that game.
• Revoke it, which stops XSF working in that game only, the next time a server starts. Restore undoes it. Use this if someone got hold of your file and is running it in a game that isn't yours.

If a game's GameConfig names a preset with Preset = "Name", the picker is locked and shows that name. If no preset has that name, the game shows a warning and uses Default.

When changes reach your game

• A server reads the dashboard once, when it starts, before any player spawns. A round never changes its rules halfway through.
• Servers that are already running keep what they started with. New servers get the new settings. To push a change to everyone, use Restart servers for updates on the game's page in the Roblox Creator Hub, or wait for old servers to empty out.
• In Studio, stop and press Play again.
• If the XSF site can't be reached when a server starts, the game runs on its Studio settings and keeps working. Players won't notice anything except that dashboard only changes are missing on that server.

Presets and Studio #

This is the one rule that matters when you use both the website and Studio. Read it once and you'll never be confused about where a value came from.

Which preset a game uses

1. If GameConfig has Preset = "Name", that preset.
2. Otherwise, the preset picked for the game on the Games tab.
3. Otherwise, the preset called Default.
4. If there's no Default either (you skipped the setup and never made one), the game simply uses GameConfig and nothing comes from the website.

return {
	-- this place always uses the "Zombies" preset from the dashboard
	Preset = "Zombies",
	-- ...the rest of GameConfig
}

If no preset has that name, Output says GameConfig asks for the website preset "Zombies", but your account has no preset with that name and the game uses Default. Make a preset with that exact name, or fix the spelling. Names are case sensitive.

Studio always wins, but only for what you changed

XSF carries a copy of its own GameConfig and every weapon Config exactly as this version ships them (in XSF.Shared.Stock, which you shouldn't edit). When a server starts, XSF compares your files with that copy, one value at a time:

• A value you changed in Studio is yours. It beats the dashboard, in that game only.
• A value you never touched follows the dashboard.

Example: your GameConfig sets Movement.WalkSpeed = 16, and your preset on the website sets walk speed 20 and sprint speed 30. That game walks at 16 (your Studio value) and sprints at 30 (from the website, because you never changed sprint speed in Studio). The dashboard shows a STUDIO tag on Walk speed, and the Games tab counts it.

Movement = {
	WalkSpeed = 16, -- changed in Studio: this game always walks at 16
	SprintSpeed = 21, -- still the shipped value: the website decides
},

Handing a value back to the website

Set it back to the value XSF ships with (the defaults are listed in Every GameConfig option). Deleting the line works too, because a missing line falls back to the default, which matches the shipped value for almost everything.

Weapon Configs work the same way, one value at a time. Change Damage.Head on the AK47 in Studio and the website can still set its fire rate.

A few things are a single value even though they look like lists:

• Loadout. Change it in GameConfig and the website loadout is ignored in that game.
• A weapon's Recoil table. Change any recoil value in Studio and the website's recoil multiplier no longer applies to that gun.

Scripts see the final values

Once applied, website values are part of the config like anything else. XSF.Config on the server and every client module read the final numbers, so your own scripts never need to know where a value came from.

A workflow that works

1. Leave GameConfig as it ships.
2. Do all your tuning on the website, testing with Play in Studio.
3. Only edit GameConfig for things the website doesn't have (keybinds, ballistics, the hidden options) or things you want locked so nobody on the website can change them.

GameConfig #

Open ReplicatedStorage.XSF.GameConfig. Every option XSF has is already listed in it with its default value and a comment saying what it does, so you can change things without reading anything else.

• Change a value and press Play to try it. There's no restart or rebuild step.
• Delete a line and XSF uses its built in default for it. That's the same as the shipped value except for three: Loadout falls back to just { "HK416" }, Camera.Style to "Standard" and Audio.Ambience to false.
• Options marked (player) are only the starting value. Players can change those for themselves in the settings menu, and their own value wins for them.
• Anything you change here beats the website dashboard for that setting.
• GameConfig is read on both the server and every client, so never put secrets in it (API keys, webhook URLs). Players can read ReplicatedStorage.

Editing it without breaking it

GameConfig is a Lua table. The rules that trip people up:

• Every line inside a table ends with a comma. A comma after the last line is fine too. A missing comma is the number one typo.
• Text goes in double quotes: "Bodycam", not Bodycam.
• true, false and nil are lowercase and have no quotes.
• Brackets have to match. Every { needs a }.
• Names are case sensitive. walkspeed is not WalkSpeed, and XSF won't see it.

If you do break it, XSF prints There is a typo in GameConfig on line N in Output and doesn't start. Look at that line and the one above it. Studio's script editor also underlines the problem in red.

-- right
Movement = {
	WalkSpeed = 14,
	SprintSpeed = 24,
},

-- wrong: missing comma after 14, and "Fast" isn't a number
Movement = {
	WalkSpeed = 14
	SprintSpeed = "Fast",
},

Changing values while the game runs

You can't. GameConfig is read when XSF starts. XSF.Config is there for reading, and changing it at runtime gives you a mix of old and new values on different machines. For things that change during a round (a player's guns, damage, attachments), use the server API instead.

Choosing the weapons #

Loadout is the list of weapons every player spawns with, in slot order. Use the folder names from XSF.Weapons, spelled exactly the same, capitals included.

Loadout = { "HK416", "USP", "M67" },

It ships with thirteen: HK416, AK47, SCAR, AWM, M249, Deagle, M870, Knife, Karambit, M67, Flashbang, RPG7, C4. That's a showcase, not a real loadout. For a real game you'll usually want two to five.

All 59 weapons

The first column is the name you write in Loadout. Every number for every gun is in Every weapon's stats.

How slots work

• The first Backpack.HotbarSize weapons (5 by default) go on the number keys. The rest wait in the backpack (B). See Hotbar and backpack.
• The player spawns holding the first one.
• Each grenade type takes one slot. The M67 ships with one in hand and one in reserve, so that slot holds two frags.
• A name that doesn't match a folder is skipped, and Output says There is no weapon called "X" in XSF.Weapons. The rest of the loadout still works.

Different weapons for different players

Everyone gets the same Loadout. For classes, teams, a shop or a main menu, give weapons from a script instead with XSF.SetLoadout, which replaces everything the player carries:

local XSF = require(game.ServerScriptService.XSF.Server)

game.Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function()
		task.wait() -- let XSF set up the character first
		if player.Team and player.Team.Name == "Snipers" then
			XSF.SetLoadout(player, { "R700", "USP", "M18" })
		else
			XSF.SetLoadout(player, { "HK416", "USP", "M67" })
		end
	end)
end)

If you give weapons from a script, you probably don't want XSF to also hand out Loadout on spawn. Add GiveLoadout = false to GameConfig. It isn't in the file by default, see Hidden options. The full API is in Server scripts, and there's a class picker in Recipes.

Removing weapons from your game

You don't have to. Weapons that aren't in anyone's loadout cost nothing at runtime. If you want a smaller place file anyway, delete the weapon's folder from XSF.Weapons and its model from XSF.Assets.GunModels. Leave the others alone.

Every GameConfig option #

This is the full list, taken straight from the GameConfig that ships with 2.0. The Default column is the value it ships with. Paths use dots for nesting, so Movement.Slide.Speed means the Speed line inside Slide inside Movement. Anything marked (player) is only the starting value, because players can change it for themselves in the settings menu.

Options that work but aren't written in the file are in More options. Keybinds have their own page, Keys and key names.

Providers

Which version of a system runs. The XSF... names are the built in ones. See Swapping parts out.

Preset and the website

Loadout

Movement

All speeds are studs per second, the same unit as Humanoid.WalkSpeed. Roblox's own default walk speed is 16, so XSF ships a bit slower and heavier. See Movement and stances for how they combine.

Camera

See Camera styles for what the two styles look like and when to use them.

Motion (gun sway)

How much the gun moves in your hands. All four are player settings, and the Comfort motion preset in the settings menu lowers them for people who get motion sick.

FreeAim (gun movement)

Bodycam style aiming: small mouse movements swing the gun first, and the body only turns once the gun nears the edge of a box. Only you can change this, players can't. The full explanation is in Gun movement.

Customization (loadout screen and unlocks)

The loadout screen (N, Y on controller, the KIT button on mobile), where players fit attachments, pick ammo and put skins on each gun or knife. Every change is checked on the server and saved with the player's settings, with three presets per gun. See Loadout screen and Unlocks.

Animations

Malfunctions (jams)

Throwables

How grenades, smokes, flashbangs and C4 fly and land. These are the defaults for every throwable. Any weapon can set the same names inside its own Grenade table, which wins over these (see Grenades).

-- floatier, higher throws that stop rolling quickly
Throwables = { Arc = 0.2, Gravity = 0.7, RollDrag = 3 },

Performance

Stances

Downed

When a player would die they go down first and a teammate can revive them. See Downed and revive.

Backpack (hotbar)

The hotbar along the bottom of the screen and the backpack panel. See Hotbar and backpack.

Damage

Audio

Audio = {
	-- XSF goes through your master group, so your volume slider covers it
	ParentGroup = "Master",
	StepSets = {
		Grass    = { Ids = { 1111111111, 2222222222 }, Volume = 0.7 },
		Metal    = { Ids = { 3333333333 }, Volume = 1.1, Pitch = 1.05 },
		Default  = { 4444444444, 5555555555 }, -- every other floor (your own sound ids)
	},
},

Holster

Empty hands. The Holster key (Y by default), or the number key of the gun in your hands, puts the gun away and takes the same gun back out. Other players see the gun leave your hands too, and nothing is equipped on the server, so shots are refused until a weapon is out again. XSF won't hand a gun back by itself while you're holstered, even when your inventory changes. A new life starts armed as normal.

A grenade being cooked or thrown can't be put away halfway. Games using Providers.Inventory = "RobloxTools" holster the normal Roblox way, by clicking the tool again, and the gun now leaves the character for other players there too.

AimAssist

Controller only. It never moves the aim for the player, it only slows looking down while an enemy is under the barrel. Mouse and touch are never affected.

Rumble

Controls

Ballistics

World scale for bullets. Leave these alone unless your map is built at an unusual scale. See Bullets and walls.

Debug

More options #

Since 2.1 most of these are written in the GameConfig that ships: GiveLoadout, Vault, Pickups, Ragdoll, Damage.Modify and Debug.LogRejects. If your GameConfig is from 2.0 they aren't in your file, but they still work. Add the lines yourself at the top level (next to Loadout and the other sections), with a comma at the end like every other line. Arms and Customization.SaveKey are still only on this page.

-- all of these are optional
GiveLoadout = false, -- no guns on spawn, you hand them out with XSF.SetLoadout

Ragdoll = false, -- characters don't ragdoll when they die

Vault = {
	Enabled = true,    -- false turns off vaulting and climbing
	MaxHeight = 7,     -- tallest ledge you can climb onto, in studs
	VaultHeight = 3.6, -- walls up to this high get vaulted over instead of climbed
	Reach = 3.2,       -- how far in front of you it looks for a wall
},

Pickups = {
	Enabled = true,
	DropOnDeath = true, -- a player's gun drops when they die
	AllowDrop = true,   -- players can drop the gun in their hands
	Lifetime = 90,      -- seconds before a dropped gun disappears
	MaxWeapons = nil,   -- most guns a player can carry, nil = no limit
},

Arms = {
	SleeveColor = nil,     -- a Color3 that every player's sleeves use
	PlayerClothing = true, -- false ignores what players wear
},

-- every player wears green sleeves
Arms = { SleeveColor = Color3.fromRGB(60, 70, 50) },

-- battle royale: three guns at most, guns stay on the floor for five minutes
Pickups = { MaxWeapons = 3, Lifetime = 300 },

Workspace attributes that change XSF behaviour live in Attributes.

Keys and key names #

Default keys live in Keybinds in GameConfig. Every action takes a list, and you can mix keyboard keys, mouse buttons and controller buttons in the same list. Players can rebind every action in the settings menu, and their binds are saved with their settings, so your defaults only matter for new players.

Two keys are fixed because they belong to prompts that pop up in the world: revive (hold F, D-pad down) and drag (H, D-pad up). Roblox draws those prompts, so players see the key on screen.

Writing key names

• Keyboard keys use the Roblox Enum.KeyCode name without the Enum.KeyCode. part: "F", "LeftShift", "LeftControl", "LeftAlt", "Space", "Tab", "CapsLock", "One", "Two".
• Mouse buttons are "MouseButton1" (left), "MouseButton2" (right) and "MouseButton3" (middle).
• Controller buttons are "ButtonA", "ButtonB", "ButtonX", "ButtonY", "ButtonL1", "ButtonR1", "ButtonL2", "ButtonR2", "ButtonL3", "ButtonR3", "DPadUp", "DPadDown", "DPadLeft", "DPadRight", "ButtonSelect", "ButtonStart". These are Xbox names, and PlayStation controllers map to them automatically (Cross is ButtonA, Circle is ButtonB, and so on).
• A misspelled name doesn't break anything. XSF skips it and Output says "X" is not a Roblox key name, with which action lost its key.
• Two actions can share a key. CheckMag and CheckGear both use D-pad left on controller by default.
• Avoid keys Roblox already uses: Escape (menu), the slash key (chat) and F9 (developer console).

Keybinds = {
	Crouch = { "LeftControl", "ButtonB" }, -- crouch on Ctrl instead of C
	Prone  = { "X" },
	Drop   = { "G", "DPadDown" },          -- G, or D-pad down on a controller
	-- actions you leave out keep their default keys
},

You only need to list the actions you change. Everything else keeps its default.

Camera styles #

XSF has two camera looks, picked with Camera.Style. Both are first person, and both use the same arms, recoil and sway. What changes is the lens and the picture.

Bodycam looks best with free aim on, because the gun moving inside the frame is half of what sells the look. Standard with free aim off feels like a normal modern shooter.

-- clean competitive look
Camera = { Style = "Standard", FieldOfView = 85 },
FreeAim = { Enabled = false },

-- heavy bodycam look
Camera = { Style = "Bodycam", BodycamFov = 104 },
FreeAim = { Enabled = true, Yaw = 11, Pitch = 6 },

Only change the lines you care about. These snippets show the important values, keep the rest of each table as it ships.

Camera effects

Four effects run on top of either style. Each is a multiplier: 0 turns it off, 1 is normal, 2 doubles it. They're all player settings too, so players can turn them down for themselves.

• Camera.Tilt leans the view a little into strafes.
• Camera.Bob bobs the view as you walk.
• Camera.RecoilKick kicks the view up when you fire. The gun's own recoil still happens with this at 0, so the gun still climbs.
• Camera.Landing dips the view when you land from a jump or a fall.

Players also get a Lens and grain switch and a Stress effects slider (blur, tunnel vision and ringing when hurt or flashed) in the settings menu. See Player settings.

Looking around

• Mouse speed is Roblox's own feel times Camera.Sensitivity, and times Camera.AimSensitivity while aiming.
• Controller speed is Camera.GamepadSpeed degrees per second at full stick, shaped by Camera.GamepadCurve so small stick movements stay precise.
• Touch speed is Camera.TouchSpeed degrees per pixel dragged on the right side of the screen.

Taking the camera away for a moment

Cutscenes, spectating and menus need the camera. Call SetCameraEnabled(false) from the client API: XSF puts the gun away and hands the camera back to Roblox. SetCameraEnabled(true) takes it back. Don't fight XSF by setting CameraType every frame.

Movement and stances #

XSF takes over WalkSpeed, sprinting, crouch, prone, lean, slide and vault. You set the numbers in Movement and Stances, and XSF picks the right speed every frame.

Which speed applies

XSF works out a base speed first, then the stance changes it:

1. Base speed. Sprinting uses Movement.SprintSpeed (21). If not sprinting, aiming uses Movement.AimSpeed (7.5). If not aiming, reloading uses Movement.ReloadSpeed (10). Otherwise it's Movement.WalkSpeed (12).
2. Stance. Crouching multiplies the base speed by Movement.CrouchMultiplier (0.55). Prone replaces it with Movement.ProneSpeed (3.2). A slide starts at Slide.Speed (30) and eases down to Slide.EndSpeed (7). Downed players crawl at Downed.CrawlSpeed (2.5).
3. Dragging a downed teammate caps the speed at Downed.DragSpeed (6).

Don't set Humanoid.WalkSpeed from your own scripts, XSF will overwrite it on the next frame. For a slow zone, a speed boost or a tactical sprint, add a speed modifier from a LocalScript with AddSpeedModifier. It gets the final speed after all of the steps above and returns your own. See Movement state and speed.

Sprint and stamina

• Sprinting only works while moving forward on the ground and not reloading. The gun drops to a low carry and can't fire while you sprint. With Movement.SprintReload = true players can keep running through a reload: the legs sprint, the hands keep reloading.
• A full bar lasts Movement.Stamina seconds (7).
• The bar starts refilling about 0.8 seconds after you stop sprinting and takes Movement.StaminaRegen seconds (4.5) to fill from empty.
• Run it to zero and you're winded: you can't sprint again until the bar is back to 30%. You'll hear the breathing.
• Players pick hold or toggle sprint in settings. On controller it's always a toggle (click L3).

For an arcade game, raise both: Stamina = 15 and StaminaRegen = 3. To effectively remove stamina, set Stamina = 9999.

Crouch and prone

• Crouch is a toggle by default (Controls.CrouchToggle). Prone has its own key (Z) on keyboard. On controller and touch, tap crouch to crouch and hold it to go prone.
• You can't stand up under something low. XSF checks for headroom first: about 2.6 studs to stand from a crouch, 3.2 from prone. From prone with no room to stand, you go to a crouch instead.
• Jumping while crouched stands you up first, if there's room.
• Other players see you crouch, slide and go prone. On R15 the hips lower and the knees bend. R6 has no knees, so since 2.1 an R6 crouch is shown as a kneel (body down about a stud, one leg forward and one back) and a slide as the body low and leaning back with both legs out in front. The server lowers an R6 player's head, torso and arm hitboxes to match, so shots land where the body is seen. NPCs with XSF_Stance and XSF_Sliding attributes get the same poses.
• Crouching makes recoil steadier (x0.8), prone more so (x0.62), and prone with a bipod fitted the most (x0.42). These are the Stances.Brace numbers.
• Turn any stance off with Stances.Crouch, Stances.Prone or Stances.Lean.

Leaning

Q and E lean the view Stances.LeanAngle degrees (22) and move the head Stances.LeanOffset studs (1.1) to the side. That offset is what lets you peek a corner without stepping out. Other players see you lean. Players choose hold or toggle. Lean isn't bound on controller by default, add a button in Keybinds if you want it there.

Sliding

Press crouch while sprinting. You drop low and slide at Slide.Speed, slowing to Slide.EndSpeed over Slide.Duration seconds, then you can't slide again for Slide.Cooldown seconds. You can shoot during a slide if Slide.CanShoot is on, with recoil times 1.25. Turn sliding off with Movement.Slide.Enabled = false.

Jumping and landing

Jumping uses Roblox's normal jump. XSF adds the landing dip (Camera.Landing) and a vault or climb when you jump at an obstacle you can get over, see Vault and mantle. To change jump height, change StarterPlayer.CharacterJumpPower or CharacterJumpHeight as usual.

Gun movement (FreeAim) #

With FreeAim on, which is how XSF ships, the gun isn't locked to the middle of the screen. Small mouse or stick movements swing the gun inside a box first, and the body only turns once the gun gets near the edge of that box. It's what gives bodycam shooters their heavy, body worn feel. Players can't turn it off, only you can, in GameConfig.

How it moves

• It has weight. The gun doesn't follow the mouse one to one. It swings toward where you point on a spring, so a quick flick eases out and settles instead of jumping.
• The edge is soft. Near the centre the gun takes almost all of the movement. The closer it gets to the edge, the more the body takes over, so there's never a moment where the gun stops dead and the view suddenly starts turning.
• Coming back leads with the gun. Moving back toward the centre, the gun moves first and the body waits, the way you'd re-aim with your arms.
• The body squares up. When you hold still, the body slowly turns in behind the gun until it's centred again. Return sets how fast. 0 turns this off.
• Aiming centres it. Aiming down sights brings the gun smoothly back to the middle, and it stays there while you aim.
• Bullets go where the barrel points, not to the middle of the screen. With FreeAim on, the crosshair setting shows the centre of the view, so learn to read the gun.

Suggested setups

-- tactical, slow and heavy
FreeAim = { Enabled = true, Yaw = 12, Pitch = 7, Return = 0.25 },

-- light touch, close to a normal shooter
FreeAim = { Enabled = true, Yaw = 4, Pitch = 2.5, Return = 1 },

-- off: gun locked to the centre
FreeAim = { Enabled = false },

Should I turn it off?

Turn it off for anything competitive or fast. Hip fire with free aim takes practice, and new players blame the game when they miss. Keep it for tactical, milsim, horror and anything that wants to look like footage. Free aim also doesn't matter much on mobile, where most people aim down sights anyway.

Downed and revive #

With Downed.Enabled on (the default), a hit that would kill a player puts them on the ground instead. A teammate can pick them up before they bleed out. It changes how fights play a lot: trading a kill no longer ends the fight, and pushing to finish someone is a real decision.

What the downed player can do

• Crawl at Downed.CrawlSpeed (2.5 studs per second).
• Shoot, only if Downed.AllowFiring is on.
• Give up: hold crouch (or G) for about two seconds to bleed out on the spot, so they can respawn instead of waiting.
• Their HUD shows YOU ARE DOWN.

Bleeding out and finishing

• A downed player dies after Downed.BleedOutTime seconds (45) if nobody helps.
• They can take Downed.DownedHealth more damage (40) before dying, so shooting a downed player finishes them fast.
• The kill goes to whoever downed them, even if they bleed out later. XSF.Killed fires with that attacker.

Reviving

• Walk up to them and a Revive prompt appears (within 7 studs). Hold F, or D-pad down on controller, for Downed.ReviveTime seconds (5).
• They get up with Downed.ReviveHealth (35).
• With Downed.TeamOnly on, only players on the same Team see the prompt. In a game without teams anyone can revive.

Dragging

With Downed.Drag on, a Drag prompt sits under the revive one. Press H (D-pad up) to start pulling the downed player behind you at Downed.DragSpeed (6), and press it again to let go. Use it to get someone out of a doorway before reviving them.

NPCs

NPCs die straight away by default. Set Downed.NPCs = true and they go down like players. Your own scripts can revive them with XSF.Revive.

From scripts

local XSF = require(game.ServerScriptService.XSF.Server)

XSF.PlayerDowned:Connect(function(humanoid, info)
	print(humanoid.Parent.Name, "went down")
end)

XSF.Revived:Connect(function(humanoid, byPlayer)
	if byPlayer then
		print(byPlayer.Name, "revived", humanoid.Parent.Name)
		-- reward the medic here
	end
end)

XSF.BledOut:Connect(function(humanoid)
	print(humanoid.Parent.Name, "bled out")
end)

-- a medkit that revives instantly
local function useMedkit(target)
	if XSF.IsDowned(target) then
		XSF.Revive(target)
	end
end

Downed characters also carry the XSF_Downed attribute on their Humanoid, so any script (even a LocalScript) can check it with humanoid:GetAttribute("XSF_Downed").

Turning it off

Downed = { Enabled = false } makes every lethal hit kill straight away. That's the right call for deathmatch, gun game and anything with quick respawns.

Common changes #

The quick answers. Everything here is in GameConfig unless it says otherwise.

Controls #

The default controls, as players see them. Everything in Keybinds can be changed by you in GameConfig and by players in the settings menu.

Revive, drag and pick up are prompts that show up in the world next to the person or object, so their keys are fixed and not in Keybinds.

Players can rebind everything in the settings menu, clear a bind with the X next to it, and set aim, sprint and lean to hold or toggle. On controller and touch, tapping crouch crouches and holding it goes prone.

Mobile and console #

XSF switches its controls to whatever the player touched last: keyboard and mouse, controller or touch. Someone on a laptop with a controller plugged in can swap between them mid fight.

Phones and tablets

• The left thumbstick moves, dragging on the right side of the screen looks.
• There are on screen buttons for fire, aim, reload, jump, crouch, sprint, swap weapon, gear (light and laser), lean left and right, fire mode and the loadout screen (KIT). The hotbar stays on screen so players can tap a slot.
• Players can hide buttons they don't use in the MOBILE tab of the settings menu. Most people turn off lean and fire mode.
• Tap crouch to crouch, hold it to go prone.
• Low effects is a good default for phone games: Performance.LowEffects = true. Players can turn it off on better phones.
• The dashboard's phone and tablet platform choice also sets a 4 slot hotbar, which fits small screens better.

Controller (Xbox, PlayStation, PC)

• Look speed and curve come from Camera.GamepadSpeed and Camera.GamepadCurve, and players can change look speed in the menu.
• Aim assist slows looking down a little over an enemy. It never pulls the aim. See AimAssist.
• Guns rumble when they fire (Rumble).
• Sprint is always a toggle on L3.
• Lean isn't bound by default because there aren't enough buttons. Add one in Keybinds if your game needs it.

Testing other devices in Studio

Use Studio's device emulator (Test tab, Device) to try phone layouts, and plug in a controller to test it directly. XSF switches as soon as you touch the stick.

Player settings #

Players open the settings menu with P or D-pad right. Settings save on the XSF site, so a player keeps the same sensitivity, binds and attachment choices in every game that uses XSF. If a game has HTTP requests off, settings save to that game instead. A game can change where they are saved, or turn saving off, with SettingsSave in GameConfig (see Preset and the website).

What's in the menu

RESET ALL SETTINGS at the bottom puts everything back to your game's defaults.

The Comfort preset

Comfort is for players who get motion sick. It cuts camera tilt to 0.15, camera bob to 0.1, recoil view kick to 0.45, landing dip to 0.25, gun bob to 0.5, breathing to 0.4, inertia and lead to 0.7 and stress effects to 0.35. Switching back to Full restores your game's defaults.

Which of your settings players can override

Everything marked (player) in Every GameConfig option: field of view, sensitivities, controller speed, the four camera effects, the four motion values, the toggle settings and crouch hold for prone. Plus low effects and hitmarkers. Your GameConfig value is what a new player starts with.

Things players can never change: camera style, Bodycam FOV, free aim, movement speeds, damage, downed rules and anything about weapons.

Reading and changing settings from code

Your LocalScripts can read and change a player's settings with GetSetting and SetSetting from the client API, for example to build your own settings screen. Changes save like normal.

local XSF = require(game.ReplicatedStorage:WaitForChild("XSF").Client.API)

-- a "streamer mode" button in your own menu
local function streamerMode()
	XSF.SetSetting("LensEffects", false)
	XSF.SetSetting("StressEffects", 0.3)
	XSF.SetSetting("Crosshair", true)
end

XSF.SettingChanged:Connect(function(key, value)
	if key == "*" then
		print("all settings loaded")
	else
		print(key, "is now", value)
	end
end)

Weapon settings #

Each weapon folder in XSF.Weapons has a Config ModuleScript with that weapon's stats. You only write what's different from the defaults. Anything you leave out comes from XSF.Shared.WeaponDefaults, so a working gun Config can be five lines long.

-- HK416, 5.56. Controllable, but it gets lively on full auto.
return {
	Class = "Rifle",
	Fire = { RPM = 800, Modes = { "Auto", "Semi" }, MuzzleVelocity = 880, TracerEvery = 3 },
	Ammo = { Magazine = 30, Reserve = 90, Chamber = true },
	Damage = { Head = 150, Torso = 60, Limb = 38 },
	Handling = { Mass = 3.6, AimTime = 0.3, AimFov = 60 },
	SlideTravel = CFrame.new(0, 0, -0.4),
	Attachments = { Sight = "EOTech", UnderBarrel = "Vertical Grip", Other = "AN PEQ" },
}

Units: distances in studs, angles in degrees, bullet speed in meters per second, time in seconds, mass in kilograms.

Damage, fire rate, magazine size, spare ammo, bullet speed, aim time and overall recoil can also be changed per preset on the dashboard. Everything else is Studio only. A value you edit in a Config beats the website for that one value.

Top level

Fire

Ammo

Damage

Characters have 100 health by default (Roblox's normal MaxHealth), so a Torso value of 34 is a three shot kill and 50 is a two shot kill. Shotgun values are per pellet, so the 870's 28 torso with 8 pellets is 224 if every pellet lands. The whole damage chain is in How damage works.

Handling

Recoil and Sway

These two tables have the most numbers and the most effect on feel, so they have their own page: Recoil and sway.

Inspect keyframes

The inspect animation is a short list of poses the gun moves through. Each keyframe has a rotation (Rot, degrees of pitch, yaw and roll), a move (Pos, studs) and how long to take getting there and holding (Hold, seconds). The last keyframe should always be all zeros, so the gun ends back where it started.

Handling = { Mass = 2.7, AimTime = 0.22, AimFov = 62,
	-- the Vector is short: the support hand holds the front of the frame, behind the muzzle
	LeftHandShift = Vector3.new(0, 0, 0.42),
	-- inspect keyframes: turn (degrees pitch, yaw, roll), move (studs) and hold (seconds)
	Inspect = {
		{ Rot = Vector3.new(-8, 52, 12), Pos = Vector3.new(-0.26, 0.18, -0.42), Hold = 0.9 },
		{ Rot = Vector3.new(8, 36, -6), Pos = Vector3.new(-0.22, 0.26, -0.45), Hold = 0.5 },
		{ Rot = Vector3.new(14, -26, -40), Pos = Vector3.new(-0.12, 0.22, -0.36), Hold = 0.95 },
		{ Rot = Vector3.new(0, 0, 0), Pos = Vector3.new(0, 0, 0), Hold = 0.4 },
	},
},

A good inspect is three or four keyframes: turn the gun to show its side, tilt it the other way, roll it to show the top or the ejection port, then return. Copy one from a gun of similar size and adjust. Longer guns need more negative Z in Pos so they don't clip into the camera.

Sounds

Every gun gets a gunshot from its class, plus generic handling sounds (mag out, mag in, slide, bolt, click when empty). Override any of them in Sounds.

Sounds = {
	Fire = { 9118163044, 9118163100 }, -- two takes, picked at random
	FireSuppressed = 9118164000,
	Pitch = 0.9, Volume = 1.1, Cut = 0.45,
	Tail = false, -- these takes already have their own echo
	MagIn = { Id = 873135562, Volume = 0.8, Pitch = 0.9 },
},

Every gun added in 2.0 already has its own shot. Use sounds you own or free sounds from the Creator Store, otherwise Roblox may block them in your game.

Knife and grenade settings

Knives use Melee (see Knives), grenades and placed explosives use Grenade (see Grenades and Explosives), and launchers use Projectile (see Explosives).

Every weapon's stats #

Every number below is read straight from the Configs that ship with 2.1.0. Use it to balance your game, or to pick guns for a loadout without opening 59 files.

• Body shots to kill assumes 100 health, no armour, FMJ, close range (before falloff) and, for shotguns, every pellet landing.
• Falloff: "150 to 500 (x0.6)" means full damage up to 150 studs, dropping in a straight line to 60% at 500 studs, and 60% beyond that.
• Kg (mass) and aim time decide how heavy the gun feels and how fast it gets on target.
• Ships with is the attachments the gun comes with, which are always free.

Rifles and machine guns

SMGs

Snipers

Shotguns

Pistols

Knives

Every knife does four times damage from behind, so any knife is a one hit kill in the back. See Knives.

Grenades and explosives

Blast damage is the most it does at the centre. It falls off with distance and stops behind cover. See Explosives.

Recoil and sway #

Recoil is what makes guns feel different more than any other setting. XSF's recoil has three separate parts, and once you know which is which, tuning a gun takes minutes instead of hours.

• The gun's kick (Pitch, Yaw, Roll, Back, Rise, Shake): how the gun model jumps in your hands each shot. It looks violent but springs back, so it doesn't move where you're aiming.
• The screen kick (Kick): a quick jolt of the camera that also springs back.
• The climb (Climb, ClimbYaw, Recovery, Pattern): how far your aim actually moves each shot. This is what players have to pull down against, and it's what decides how controllable a gun is.

All three get stronger as the gun heats up during a long burst, and all three are scaled by stance (crouch, prone, bipod) and attachments.

Every recoil setting

Patterns

Every gun climbs in the same pattern every time, so players can learn to pull against it, like in CS. You don't have to make one. If a gun has no Pattern, XSF generates one from the gun's model name: the first three shots go straight up, then a side to side drift grows in over the next few shots and weaves from there. Two guns with different names get different patterns, and the same gun always gets the same one.

To write your own, give a list of { up, sideways } per shot. up multiplies the gun's average climb (1 is normal), sideways is a share of the gun's widest ClimbYaw (1 is all the way right, -1 all the way left). The last entry repeats for longer bursts. Three quarters of the climb follows the pattern and a quarter stays random, so it never feels robotic.

Recoil = {
	Climb = { 0.5, 0.7 },
	ClimbYaw = { -0.3, 0.3 },
	-- up, then pull right, then snake left
	Pattern = {
		{ 1, 0 }, { 1.1, 0 }, { 1.1, 0.2 }, { 1, 0.5 }, { 0.9, 0.8 },
		{ 0.9, 0.4 }, { 0.8, -0.2 }, { 0.8, -0.7 }, { 0.8, -0.9 }, { 0.8, -0.4 },
	},
},

What lowers recoil

They all multiply together. A crouched player with a Muzzle Brake and a Vertical Grip has 0.8 x 0.85 x 0.88, about 60% of the standing climb.

Tuning a gun in five minutes

1. In a Studio playtest, hold the gun and press F4.
2. Fire full auto at a wall from 50 studs and watch where the bullet holes land.
3. Too hard to control? Lower Climb first. Too easy? Raise it. This is 80% of the work.
4. Drifts too much sideways? Narrow ClimbYaw or move YawBias toward 0.
5. Gets out of hand too quickly in long bursts? Lower HeatPerShot or HeatMax.
6. Looks too tame? Raise Pitch, Back and Kick. These change how it looks and feels without changing how hard it is to control.
7. Press PRINT TO OUTPUT and paste the result into the gun's Config.

Sway

Sway is how the gun moves when you turn, walk and breathe, separate from shooting. Players can scale it with the Motion settings, you set the per gun shape here.

Heavy guns (snipers, machine guns) ship with a higher InertiaMax and InertiaGain. If a light gun feels too floaty, lower Handling.Mass first, it affects everything at once.

Adding a gun #

Adding your own gun is mostly a model and a copied folder. XSF fits the hands, the attachments and the animations to it by itself.

What the model needs

Put the model in XSF.Assets.GunModels. Inside it, XSF looks for these by name:

ACS gun models already have Handle, AimPart, Muzzle and Nodes, which is why they drop in so easily.

The steps

1. Put the model in XSF.Assets.GunModels.
2. Copy the weapon folder in XSF.Weapons that's closest to your gun (an SMG for an SMG, a bolt action for a bolt action) and rename it. The folder name is what goes in Loadout.
3. If the model's name is different from the folder name, add Model = "YourModelName" to the Config.
4. Change the Config: damage, fire rate, magazine, mass, recoil. Delete anything you don't need, like the copied Inspect, if it doesn't suit the new shape.
5. Add the folder name to Loadout and press Play. The hands find the grip on their own.
6. Press F6 to run the self test on it. It catches a missing Handle, a missing Anims module and bad Config values.

Model attributes

Set these on the gun model itself (select it, then Attributes at the bottom of Properties) when the defaults don't suit it.

Animations

Every weapon folder needs an Anims ModuleScript next to its Config. When you copy a folder you copy that too. With Animations = "XSF" (the default), magazine guns use XSF's own draw, reload, inspect and jam clearing, built from the gun's real Mag part, so you don't need to animate anything. Use the ACS importer if you have hand made ACS animations you'd rather keep.

Skins on your gun

Skins paint parts by name. Parts called Polymer, Wood or Leather count as furniture, Steel and Bolt as metal, Mag as the magazine, Blade as a knife blade, and BlackSteel, Slide, Stainless and Tan as the body. Anything else counts as body, except glass and neon parts, parts called Rubber and see through parts, which are left alone. See Skins.

Common problems

• The gun points the wrong way or sits sideways. The Handle's front face isn't pointing down the barrel. Rotate the Handle (not the whole model) so its LookVector runs along the barrel, then re-weld.
• Aiming looks off to the side. Move AimPart so it's centred on the sights, or raise it if you're looking at the top of the gun.
• Bullets come out of the wrong place. Move the Muzzle attachment to the end of the barrel.
• Attachments float or sink. Turn on XSF_AttFit, or move the part in Nodes.
• The hand doesn't close on the grip. Set XSF_GripWrap = true.

Importing ACS guns #

If you have an ACS gun with its animations, XSF can convert it into an XSF weapon folder for you, animations included. You need the optional XSF_Tools folder from the download in ServerStorage. Run it in Studio while the game is stopped, not during Play.

1. Put the gun model in XSF.Assets.GunModels.
2. Put its ACS_Animations module anywhere in ServerStorage.
3. Open the command bar (View > Command Bar) and paste this, changing the path and the name:

require(game.ServerStorage.XSF_Tools.ImportACS).weapon(game.ServerStorage.ACS_Animations, "YourGun")

This creates XSF.Weapons.YourGun with the converted animations and a starting Config. Open the Config, set the real stats (damage, RPM, magazine, class) and add it to your loadout.

After importing

• With Animations = "XSF", XSF's own reload is used for magazine guns if the model has a Mag part, and the imported clips are used for everything else. Set Animations = "Imported" to always use the ACS clips.
• ACS guns are often built at a different size. If attachments look too big or small, set XSF_AttScale on the model.
• Delete the ACS scripts that came inside the model (anything that isn't a part, a weld or an attachment). XSF doesn't need them, and old ACS scripts can error.
• You can delete XSF_Tools again when you're done. It never runs in a live game either way.

Attachments #

Guns take one attachment per slot. There are five attachment slots plus skins:

What each one does

Ammo types are in Ammo types.

Effects stack across slots by multiplying. A Muzzle Brake and a Vertical Grip together give 0.85 x 0.88 climb, so about 25% less.

Who gets which attachment

Three things decide whether a player can pick an attachment on a gun:

1. The gun has to take it. It needs a node for that slot.
2. Your rules allow it. Customization.Slots, Allowed and Blocked in GameConfig.
3. The player owns it. With Customization.Ownership on (the default), players only get attachments you give them, plus anything in Customization.Starter, plus whatever the gun comes with in its Config. See Unlocks.

Setting them from a script

Server scripts can fit anything with XSF.SetAttachments, skipping all of the rules above. Good for classes, events and NPCs:

local XSF = require(game.ServerScriptService.XSF.Server)
XSF.SetAttachments(player, "HK416", {
	Sight = "Acog",
	Barrel = "Suppressor",
	UnderBarrel = "Angled Grip",
	Ammo = "Armor Piercing",
})

Slots you leave out of the table are emptied, so include everything you want the gun to keep.

Adding your own attachment

1. Put the model in XSF.Assets.AttModels, named exactly what it'll be called in game. It needs a part called Main.
2. Sights also need AimPos (where the eye goes) and SightMark (the reticle). Muzzle devices need BarrelPos (the new muzzle). Lights need FlashPoint, lasers LaserPoint.
3. Give it a line in the attachment list (the List table at the top of XSF.Shared.Attachments) with its slot and effects, the same way the built in ones are written. That module is protected, so only edit inside the List table and keep a backup. The fields are Slot, AimFov, AimTime, Velocity, Damage, Recoil = { Vertical, Horizontal, Kick }, Suppressed, NoFlash, Bipod, Laser, Light and Grip.
4. It shows up in the loadout screen for every gun with a matching node, and works in SetAttachments and weapon Configs.

Ask in the Discord if you get stuck on step 3, it's the fiddly one.

Loadout screen #

Players press N (Y on controller, KIT on mobile) to open the loadout screen. It shows the gun they're holding, turning slowly, with every attachment that fits it. Hovering an option shows exactly what it changes, as green or red bars against the gun's base: recoil, aim time, damage, bullet speed and wall penetration.

• Apply fits the choice straight away, on the gun in their hands and on everyone else's screen.
• Default goes back to what the gun comes with in its Config.
• Presets: three per gun. Save the current setup into one and load it any time.
• Items the player doesn't own show as LOCKED with "Locked. This game decides how you unlock it.", so players can see what's out there to earn or buy.
• Skins have their own row, with rarity colours: grey Common, green Uncommon, blue Rare, purple Epic, gold Legendary.
• Knives show up here too, for skins. Grenades don't.

Choices and presets are saved with the player's settings, so they follow the player to every server. The server checks every change, so nothing can be fitted that the gun, your rules or the player's unlocks don't allow.

Customization = {
	Enabled = true,
	Slots = { Sight = true, Barrel = true, UnderBarrel = true, Other = true, Ammo = true, Skin = true },
	Allowed = { HK416 = { "Acog", "Suppressor", "Vertical Grip", "Woodland" } }, -- optional, per gun
	Blocked = { "PM II" },                 -- optional, nobody can pick these
	Ownership = { Attachments = true, Skins = true },
	Starter = { "FMJ", "Reflex" },        -- free for everyone
	SaveOwnership = false,
	Access = "Anywhere",
},

Workbenches

With Customization.Access = "Workbench", the screen only opens at a workbench while holding the gun. Copy ReplicatedStorage.XSF.Assets.Workbench into your map, as many as you like, anywhere you like. It's a good fit for milsim and survival games where changing attachments mid fight shouldn't be possible.

Turning it off

Customization.Enabled = false hides the screen and the server refuses all changes, so every gun keeps the attachments in its Config. You can still change attachments from server scripts.

Ammo types #

Ammo is picked per gun in the loadout screen, in the Ammo slot. It changes damage, wall penetration, armour and sound.

The worked examples with armour are in How damage works.

Reloads and feeds #

Different guns reload differently in 2.0, the way the real ones do. You pick the style with Feed and ShellInsert in a Config.

Magazine guns (the default)

• Empty reload: the old magazine drops, a new one goes in, and the slide or bolt is released.
• Tactical reload (rounds still left): the old magazine goes back in the pouch instead of dropping, and with Ammo.Chamber = true the gun keeps one round in the chamber on top of the new magazine.
• With Animations = "XSF", the hand really grabs the gun's Mag part. It works out the motion from where the magazine is on each gun.
• Handling.ReloadSpeed speeds the animation up or slows it down.

Pump and shell by shell (ShellInsert = true)

The 870 and SPAS-12 load one shell at a time. With Modes = { "Pump" } the player pumps after every shot.

Bolt actions (Modes = { "Bolt" })

The right hand comes off the grip, lifts and pulls the bolt, then pushes it home after every shot. Handling.Bolt describes the bolt so the hand finds it:

Handling = {
	-- where the right hand works the bolt (handle space), the bolt's turn and pull
	Bolt = { Knob = Vector3.new(0.19, 0.27, 0.04), Axis = 0.33, Lift = 60, Travel = 0.32 },
	Mass = 6.5, AimTime = 0.5, AimFov = 45,
},

Stripper clips (Feed = "Stripper")

The Kar98k and Mosin open the bolt and push five rounds down from a clip.

Revolver (Feed = "Revolver")

The 686 swings its cylinder out, punches all six cases at once and drops a speedloader in. It's slow on purpose (ReloadSpeed = 0.75), so every shot counts. The model needs a part called Mag for the cylinder.

Break open (Feed = "Breech")

The M320's barrel swings out to the side, the old case comes out and a new round goes in.

Front loaded (Feed = "Muzzle")

The RPG-7 takes a new warhead in the front of the tube. The round shows on the launcher while it's loaded.

Reloading and the server

The server tracks every reload. A reload that finishes faster than it possibly could is rejected (the Rejected event fires with the reason fast reload), so modified clients can't skip reload times.

Jams, sound and effects #

Jams

Off by default. Turn them on with Malfunctions.Enabled = true.

• Every shot has a Malfunctions.Chance of jamming (0.003, about one in 300). Long bursts make it more likely as the gun heats up, and so do suppressors.
• A jammed gun shows JAMMED and RELOAD TO CLEAR, and won't fire.
• Reloading clears it: the player racks the gun if there are rounds left, or swaps the magazine if not.
• Jams are a great fit for milsim, a terrible fit for anything competitive. Leave them off unless your players want them.

Sound

• Distance. Shots get quieter and duller with distance, and far away shots arrive late, the way sound really travels.
• Walls. Every wall between the shot and the listener muffles it more. A firefight in the next building sounds like it.
• Indoors and outdoors sound different, so a shot inside a room doesn't ring out like one in an open field.
• Suppressors and subsonic ammo are quieter for everyone and carry much less far.
• Bullets passing close crack and whiz, and push the suppression effect on the player they passed.
• Footsteps change with the floor material (Audio.Footsteps).
• Ambience (Audio.Ambience): quiet wind and distant traffic outdoors, room tone indoors.

Getting shot

• Players flinch when hit and stagger from heavy hits, which knocks their aim off for a moment.
• Being shot at (rounds landing or passing close) builds suppression: a bit of blur and a tighter view. Players can tone it down with the Stress effects setting.
• Low health brings in a heartbeat. The HUD shows HEALTHY, HURT, WOUNDED, BADLY WOUNDED or CRITICAL instead of a number when players check their gear.

Impacts

Bullet holes and debris match the surface: splinters from wood, sparks and bright dents on metal, shards from glass, dust from concrete and dirt kicked up from the ground. Unanchored parts get pushed by bullets and blasts, so loose crates and barrels react.

Low effects

Players can turn on Low effects in settings. It cuts particles, drops brass and muzzle smoke and keeps fewer bullet holes. Performance.LowEffects sets what new players start with. See Performance.

Knives #

Knives are held in one hand, the way CS2 shows them. Each one has its own draw, idle, inspect and slashes.

• Left click (Fire) slashes. Slashes take turns: forehand, then backhand, then forehand again.
• I (Inspect) shows the knife off. The karambit spins on your finger, the butterfly knife flips open and shut. Attacking cuts the inspect short.
• From behind, a slash does four times the damage. It counts as from behind when the person you hit is facing away from you, within 60 degrees either side of straight away. That's a one hit kill with every knife.
• Knives only make a sound when they're swung, never when drawn or inspected.
• Knives can wear skins, picked in the loadout screen like on guns.

Knife settings

return {
	Class = "Melee",
	Kind = "Melee",
	Melee = { Range = 5.5, Cooldown = 0.65, HitDelay = 0.18 },
	Damage = { Head = 75, Torso = 45, Limb = 32 },
	Handling = { Mass = 0.4 },
	Ammo = { Magazine = 0, Reserve = 0, Chamber = false },
}

All seven knives and their numbers are in Every weapon's stats. Knife damage can also be set per preset on the dashboard.

A knife only round

local XSF = require(game.ServerScriptService.XSF.Server)

local function knifeRound()
	for _, player in game.Players:GetPlayers() do
		XSF.SetLoadout(player, { "Karambit" })
	end
end

Grenades #

Hold fire to get a grenade ready and release to throw it. Hold aim as you release to lob it underhand instead, slower and shorter, for rolling it round a corner or over a low wall.

Each grenade slot starts with two (one in hand, one in reserve). Grenades bounce off walls and roll on slopes.

Grenade settings

return {
	Class = "Grenade",
	Kind = "Grenade",
	Grenade = { Type = "Frag", Fuse = 4.5, Radius = 28, Damage = 180, ThrowSpeed = 95, LobSpeed = 45, Cook = true },
	Ammo = { Magazine = 1, Reserve = 1, Chamber = false },
	Handling = { Mass = 0.4 },
}

Throwing grenades from a script

For traps, airstrikes and scripted events:

local XSF = require(game.ServerScriptService.XSF.Server)

-- name, start position, velocity, fuse seconds, thrower (optional, gets the kill credit)
XSF.SpawnGrenade("M67", Vector3.new(0, 50, 0), Vector3.new(0, -10, 0), 3)

-- a flashbang dropped from the ceiling when a door opens
XSF.SpawnGrenade("Flashbang", ceiling.Position, Vector3.zero, 1.2)

Hotbar and backpack #

Players can carry any number of weapons. The hotbar along the bottom of the screen holds the ones on the number keys, and the backpack holds the rest.

• Number keys 1 to 5 (or up to Backpack.HotbarSize, at most 9) switch to that slot. The mouse wheel and the controller bumpers walk through the hotbar in order.
• B (Select on controller) opens the backpack. Click a weapon to take it out: it shows next to the hotbar with a B while you hold it.
• Drag a weapon onto a numbered slot to put it on the hotbar. Drag a hotbar weapon onto another slot to swap them, or back onto the list to take it off the hotbar. Hovering a weapon and pressing a number key also puts it on that slot.
• On phones and tablets the hotbar is tappable and can be hidden in the player's settings.
• Backpack.Hotbar = "Fade" hides the hotbar until the player switches weapons or holds Check gear, for a cleaner screen.

When a game gives a player new weapons with XSF.SetLoadout or XSF.Give, weapons that are still carried keep their slots, and new weapons fill the free slots in order. A slot the player emptied on purpose stays empty.

Games using Providers.Inventory = "RobloxTools" keep Roblox's own backpack bar instead, and none of this applies. Each weapon becomes a Tool, so other systems that look for Tools in the backpack (like some shop kits) keep working.

Hands and grips #

With the realistic arms (Providers.Arms = "XSFRealistic"), every finger is posed against the real shape of each gun when it's drawn, so the hand closes around the grip and the index finger sits on the trigger. Knives are held in a closed fist. The support hand finds the handguard, or the grip if one is fitted.

• Sleeves take the colour of the player's shirt. Players with no shirt (or only a t-shirt) get bare arms in their own skin colour, with a smooth skin texture. Force one colour for everyone with Arms.SleeveColor, or ignore clothing with Arms.PlayerClothing = false (see Hidden options).
• Gloves never change colour.
• ACS arms (Providers.Arms = "ACSClassic") are the classic blocky arms. They don't pose fingers.

Fixing the grip on your own gun

Most guns need nothing. If the hand looks wrong on a gun you added, these fix it:

To move where the hand sits on the gun itself, move the gun model's parts (not the Handle) relative to the Handle. Moving them back, toward the player, puts the hand further forward on the gun.

How damage works #

Every shot is simulated as a real bullet, first on the shooter's screen and then again on the server, which decides what it hit. The server rewinds other players to where they were when the shot was fired (it keeps one second of history), so hits line up even with lag.

Step by step

1. Body part. The part that was hit picks the zone. Head is Head. UpperTorso, LowerTorso, Torso (R6) and HumanoidRootPart are Torso. Everything else, arms, hands, legs and feet, is Limb.
2. Base damage comes from the gun's Damage table for that zone.
3. Ammo and attachments. Times the ammo's damage (Hollow Point 1.2, Armor Piercing 0.9, Subsonic 0.92) and the suppressor's 0.95 if fitted.
4. Falloff. Up to FalloffStart studs of bullet travel, damage is full. From there it drops in a straight line to MinMultiplier at FalloffEnd, and stays there. With the defaults (150, 600, 0.6), a hit at 375 studs does 80%.
5. Walls. A bullet that went through cover keeps a share of its damage based on how much penetration power it has left, never less than half. See Bullets and walls.
6. Armour. XSF_Armor on the character cuts Torso and Limb damage by that share. XSF_Helmet does the same for the Head. Armor Piercing ignores 60% of the armour, Hollow Point makes it count 1.5 times. Armour never goes above 100%.
7. Your modifier. If GameConfig has a Damage.Modify function, it runs now and can change the number (see below).
8. Downed. With Downed.Enabled, a hit that would kill puts the player down instead. After that they can take DownedHealth more damage before dying, and bleed out after BleedOutTime seconds.

Who can't be hurt

• Teammates, while Damage.FriendlyFire is off. That means two players on the same Team, where the attacker isn't on a Neutral team. Players with no team can always be hurt.
• Anyone with a ForceField. Roblox's spawn ForceField blocks all XSF damage, so spawn protection works the normal way (SpawnLocation.Duration).
• Yourself, from bullets. Your own explosions can hurt you.
• The already dead.

Worked example

An HK416 does 60 to the torso. With Hollow Point that's 72. The target has XSF_Armor = 0.4, and hollow points make armour count 1.5 times, so it stops 60%: the hit does about 29. The same shot with Armor Piercing does 54, and the armour only counts 40% as much, stopping 16%: about 45.

Giving characters armour

-- give every player a vest and a helmet
game.Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function(char)
		char:SetAttribute("XSF_Armor", 0.35)  -- vest: 35% less torso and limb damage
		char:SetAttribute("XSF_Helmet", 0.5)  -- helmet: 50% less head damage
	end)
end)

The attributes go on the character model. Change them any time, for armour pickups or armour that breaks after so many hits.

Changing damage with your own rule

For rules XSF doesn't have (double damage weekends, a boss that takes half damage, headshots only), add a Modify function to the Damage table in GameConfig. It gets the Humanoid being hit, the damage after armour, and a table with attacker, zone, weapon and from (where the damage came from). Return the new amount, or 0 to cancel the hit.

Damage = {
	FriendlyFire = false,
	Hitmarkers = false,
	Modify = function(humanoid, amount, info)
		-- the boss takes half damage
		if humanoid.Parent.Name == "Boss" then
			return amount * 0.5
		end
		-- knives can't hurt anyone wearing the riot shield attribute
		if humanoid.Parent:GetAttribute("RiotShield") and info.weapon == "Knife" then
			return 0
		end
		return amount
	end,
},

Modify only runs on the server. Keep it quick, it runs for every hit.

Kill credit

XSF sets the classic creator ObjectValue on the victim's Humanoid to the attacking player, the same tag most old Roblox leaderboards and kill feeds look for. So older kill scripts usually work as they are. For anything new, use XSF.Killed, which gives you the attacker and the weapon directly.

Bullets and walls #

Bullets in XSF are projectiles that fly at MuzzleVelocity, fall with gravity and can go through things. Here's exactly how.

Flight

• Speed is Fire.MuzzleVelocity in meters per second, converted to studs with Ballistics.StudsPerMeter (one stud is 28 cm). An HK416 bullet at 880 m/s moves about 3,140 studs per second.
• Gravity is Ballistics.Gravity (9.81 m/s²), separate from your map's workspace.Gravity.
• Each shot gets a random spread of Fire.Dispersion degrees (plus PelletSpread for shotgun pellets).
• Bullets live for Ballistics.MaxLife seconds (3) or until they fall below the map.
• Over long range, slower bullets visibly drop and take time to arrive. Lead moving targets and use the zero on snipers.

Going through walls

Every bullet starts with a penetration power that comes from its class, times its ammo:

Armor Piercing multiplies it by 1.9, Hollow Point by 0.45. You can set any gun's power directly with Fire.Penetration.

When a bullet hits something, XSF measures how thick it is along the bullet's path (up to 6 studs) and multiplies that by the material's cost:

If the cost is less than the bullet's remaining power, it goes through, loses that much power and slows down. If not, it stops inside. Parts thicker than 6 studs always stop bullets.

Some quick results with the defaults: a rifle (1.3) goes through about 2 studs of wood but less than half a stud of concrete. A pistol (0.45) gets through 0.75 studs of wood and no real concrete. An AWM (2.4) goes through 4 studs of wood or 0.85 studs of concrete. Glass barely slows anything.

Making a wall bulletproof (or paper thin)

Set the XSF_PenetrationCost attribute (a number) on any part to override its material. 100 makes it bulletproof, 0 makes bullets ignore it entirely. Handy for a glass window that should stop bullets, or a thick prop that should be shoot through.

-- every part in the Bunker model stops bullets
for _, p in workspace.Bunker:GetDescendants() do
	if p:IsA("BasePart") then p:SetAttribute("XSF_PenetrationCost", 100) end
end

Damage after a wall

A bullet that went through something does its damage times its remaining power share, but never less than half. A rifle round that spent most of its power on a wooden wall does about 50 to 60% on the other side. Glass costs so little that it barely matters.

Ricochets

A bullet that hits a hard surface (anything costing 2.4 or more: brick, concrete, metal, rock) at a shallow angle, less than about 13 degrees from the surface, skips off once instead of stopping. It keeps 45% of its speed and 40% of its power. You'll hear the ricochet whine. Each bullet only ricochets once.

Loose parts

Unanchored parts under 1,500 mass get a push when a bullet hits them, so crates, cans and barrels react to being shot. Characters aren't pushed by bullets.

Explosives #

Four weapons blow things up. Add them to Loadout like any other weapon: "RPG7", "M320", "C4" and "Claymore".

How blast damage works

• XSF checks the head and torso parts of everyone in the radius and uses whichever is most exposed.
• Damage falls off with distance on a curve: full at the centre, about two thirds at a quarter of the way out, a bit under 40% halfway out, and nothing at the edge.
• Cover blocks it. If something solid is between the blast and you, you take nothing, unless you're very close (inside a quarter of the radius), where you still take 35%.
• Directional blasts (the claymore) only do full damage inside their cone. Behind is Back times the damage.
• Loose parts in the blast get thrown around.
• Friendly fire rules apply. Your own explosions can always hurt you.

Explosive settings

Class = "Launcher",
Feed = "Muzzle",
Fire = { RPM = 30, Modes = { "Semi" }, MuzzleVelocity = 115, Zero = 150, TracerEvery = 0 },
Ammo = { Magazine = 1, Reserve = 3, Chamber = false },
-- Speed and MaxSpeed in m/s, Arm and Radius in studs. Closer than Arm it
-- does not go off, only the direct hit (Impact) hurts
Projectile = { Speed = 45, MaxSpeed = 110, Ignite = 0.12, Burn = 0.7, Drop = 0.12, Life = 5,
	Arm = 18, Radius = 24, Damage = 260, Impact = 120, Blast = "HE", ShowRound = true },

C4 and claymore use Grenade settings: Radius, Damage, MaxPlaced (how many can be out at once), and for the claymore Cone, Back, Trigger (trip distance), TriggerCone and Arm (seconds).

Your own explosions

From any server script, for barrels, mines, airstrikes or a car blowing up:

local XSF = require(game.ServerScriptService.XSF.Server)

-- position, settings, attacker (optional, gets kill credit), weapon name (optional, for the kill feed)
XSF.Explode(barrel.Position, { Radius = 20, Damage = 200 }, attackerPlayer, "Barrel")

-- a shaped charge that only blasts forward
XSF.Explode(door.Position, { Radius = 15, Damage = 250, Cone = 70, Back = 0.1 })

XSF.Exploded fires for every explosion, with (kind, position, attacker, weaponName). kind is "Frag", "HE" (launchers, C4 and your own calls), "Claymore", "Flash" or "Smoke".

Pickups #

Guns can be dropped and picked up. A dropped gun keeps its attachments, skin and ammo, so picking up someone's gun gives you exactly what they had.

• Drop: X drops the gun in your hands in front of you (Keybinds.Drop, see Hidden options).
• Pick up: walk within 8 studs and a Pick up prompt appears. Press F (Y on controller).
• Already carrying that gun? Picking up another one just takes its ammo into your spare rounds.
• On death the gun in your hands drops where you fell (Pickups.DropOnDeath).
• Clean up: dropped guns disappear after 90 seconds (Pickups.Lifetime).
• Carry limit: with Pickups.MaxWeapons set, a full player swaps the gun in their hands for the one on the floor.
• Downed players can't pick things up.

All of this can be changed with the Pickups table, see Hidden options.

Spawning guns and ammo from a script

local XSF = require(game.ServerScriptService.XSF.Server)

-- a gun with its own ammo and an ACOG on it
XSF.SpawnPickup("AK47", spot.CFrame, { mag = 30, reserve = 60, atts = { Sight = "Acog" } })

-- an ammo box: each gun gets up to 3 magazines, and the box can be used 4 times
XSF.SpawnPickup("Ammo", crate.CFrame, { Mags = 3, Uses = 4 })

-- a box that never runs out (a resupply point)
XSF.SpawnPickup("Ammo", base.CFrame, { Mags = 2, Infinite = true })

The position can be a CFrame or a Vector3. SpawnPickup returns the pickup model if you want to move or delete it later.

An ammo box tops up every gun the player carries (not knives or grenades) by up to Mags magazines, but never past what the gun spawns with. A use only counts if it actually gave someone ammo, so a full player walking past doesn't waste a box.

Events

XSF.PickedUp:Connect(function(player, weaponName, model)
	print(player.Name, "picked up", weaponName) -- weaponName is "Ammo" for ammo boxes
end)

XSF.Dropped:Connect(function(player, weaponName, model)
	-- player is nil for pickups spawned by a script
end)

Zeroing and special optics #

Zeroing

Long guns can be zeroed. Bullets drop, so a sight can only be exactly right at one distance. Zeroing picks that distance. Press ] to raise the zero and [ to lower it (ZeroUp and ZeroDown in Keybinds). The HUD shows ZERO and the current range. Set it to the target's distance and the bullet lands where the reticle is.

Add zero steps to any gun with Fire.ZeroSteps and set where it starts with Fire.Zero. Guns without steps are zeroed at Fire.Zero (100 studs) and can't be changed.

Fire = { RPM = 700, Modes = { "Semi" }, MuzzleVelocity = 850, Zero = 200, ZeroSteps = { 100, 200, 300, 400, 600 } },

Night vision and thermal

Two sights change what you see through them:

• Night Vision: an image intensifier. Dark rooms and night maps turn bright green and readable.
• Thermal: white hot. People and NPCs glow bright through smoke and shadow while the world goes grey.

They aren't given out by default. Give them to players like any other unlock (XSF.GrantAttachment(player, "Thermal")), or put them in Customization.Starter to make them free for everyone. Thermal through smoke is strong, so many games keep it rare or expensive.

Vault and mantle #

Run at a low wall and jump to vault over it. Jump at a ledge you can reach and you climb up onto it. The left hand plants on the edge and the camera dips, so it feels physical. On a thin wall you land on the middle of the top, not the far edge. There's nothing to set up: it works on any part in your map.

• Obstacles up to Vault.VaultHeight (3.6 studs) are vaulted over, and you land on the far side.
• Taller ones, up to Vault.MaxHeight (7 studs), are climbed onto.
• XSF looks for something to vault within Vault.Reach (3.2 studs) in front of you.
• Downed players can't vault.

None of these are in GameConfig by default. Add a Vault table to change them, see Hidden options.

-- parkour game: climb higher
Vault = { MaxHeight = 10 },

-- stop players getting onto roofs
Vault = { MaxHeight = 4.5 },

-- no vaulting at all
Vault = { Enabled = false },

To stop players climbing one specific thing (an invisible wall, the edge of the map), make it taller than MaxHeight. A tall transparent part with CanCollide on does it.

Skins #

XSF ships with 108 skins that work on every gun and knife, including guns you add yourself. Players put them on in the loadout screen, in the Skin row.

Rarities

XSF.Skins on the server is the full list, keyed by name, with each skin's Rarity and Info. Use it to build a shop or a crate preview:

local XSF = require(game.ServerScriptService.XSF.Server)
for name, skin in pairs(XSF.Skins) do
	print(name, skin.Rarity, skin.Info)
end

How skins paint a gun

A skin colours each part of the gun by its role: body, furniture (stocks and grips), metal, magazine and blade. Solid skins set colours and materials. Camo and pattern skins (Woodland, Galaxy, Damascus and so on) add a texture on top, scaled to the size of the gun. Attachments keep their own look. To make your own guns take skins nicely, name the parts the way Adding a gun describes.

Who gets which skin

With Customization.Ownership.Skins on (the default), players only have the skins you give them. Turn it off to give everyone every skin. Skins are given and checked the same way as attachments, see Unlocks.

Crates

XSF.RollSkin picks a random skin by rarity weights. Leave the weights out and it uses 55 Common, 25 Uncommon, 12 Rare, 6 Epic, 2 Legendary. Only rarities you list can come up.

local XSF = require(game.ServerScriptService.XSF.Server)

local function openCrate(player)
	local skin = XSF.RollSkin({ Common = 60, Uncommon = 25, Rare = 10, Epic = 4, Legendary = 1 })
	XSF.GrantSkin(player, skin)
	return skin -- show it in your crate opening UI
end

-- a premium crate that never gives Commons
local function premiumCrate(player)
	local skin = XSF.RollSkin({ Rare = 70, Epic = 25, Legendary = 5 })
	XSF.GrantSkin(player, skin)
	return skin
end

Putting a skin on for the player

-- after a purchase, equip it straight away on the gun they're carrying
XSF.GrantSkin(player, "Galaxy")
XSF.EquipSkin(player, "AK47", "Galaxy")

EquipSkin returns false if the player doesn't own the skin or isn't carrying that weapon. Pass nil as the skin to take it off.

Unlocks #

By default players only get the attachments and skins your game gives them, so you can sell them, put them in crates or tie them to levels. A gun's own default attachments (from its Config) and anything in Customization.Starter are always free.

Turning it on and off

Customization = {
	-- players only get what you give them (the default)
	Ownership = { Attachments = true, Skins = true },

	-- everyone gets every attachment, skins still have to be earned
	-- Ownership = { Attachments = false, Skins = true },

	-- everything free for everyone
	-- Ownership = false,

	Starter = { "FMJ", "Reflex", "Woodland" }, -- free for everyone, on every gun
	-- Starter = { "FMJ", "AK47:Acog" },       -- "Gun:Item" frees one item on one gun
},

Giving and taking

A misspelled name prints [XSF] there is no attachment called "X" (or skin) and does nothing. Granting "*" unlocks every item of that kind.

Saving unlocks

Two choices:

• Let XSF do it. Set Customization.SaveOwnership = true. XSF saves to its own DataStore (named by Customization.SaveKey, "XSF_Ownership" by default) when unlocks change and loads it when the player joins. Change SaveKey to start everyone fresh.
• Do it yourself. Leave it off and save XSF.GetOwned(player) in your own DataStore with the rest of your player data, then XSF.SetOwned when they join. Do this if you already have a data system (ProfileService, ProfileStore, DataStore2), so everything saves and rolls back together.

local DataStoreService = game:GetService("DataStoreService")
local XSF = require(game.ServerScriptService.XSF.Server)
local store = DataStoreService:GetDataStore("PlayerUnlocks")

game.Players.PlayerAdded:Connect(function(player)
	local ok, data = pcall(store.GetAsync, store, "u_" .. player.UserId)
	if ok and data then
		XSF.SetOwned(player, data)
	end
end)

game.Players.PlayerRemoving:Connect(function(player)
	pcall(store.SetAsync, store, "u_" .. player.UserId, XSF.GetOwned(player))
end)

Ideas

• Leveling: grant attachments at certain levels. There's a full example in Recipes.
• Gamepass: check MarketplaceService:UserOwnsGamePassAsync on join and grant a set of skins.
• Developer products: grant a crate roll in ProcessReceipt.
• Kill streaks: grant the Thermal sight for the rest of the round after 5 kills, and revoke it on death.

Unlocks are stored on the player as the XSF_Owned attribute (JSON), so LocalScripts can read what a player owns for your own shop UI. Never trust it for purchases, always grant from the server.

Server scripts #

Your own server Scripts talk to XSF through one module. Require it at the top of any Script in ServerScriptService. Everything here is checked and replicated for you: a weapon you give shows up for the player, and damage you deal counts for downing, armour and kill credit exactly like a bullet.

local XSF = require(game.ServerScriptService.XSF.Server)
print("Running XSF " .. XSF.Version)

Only require it from the server. A LocalScript can't see ServerScriptService. LocalScripts use the client API.

Values

Weapons

XSF.SetLoadout(player, names)

Replaces everything the player is carrying with this list, in slot order, each with its spawn ammo and the player's saved attachments. Call it after the character has spawned.

game.Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function()
		task.wait() -- let XSF set up the character first
		if player.Team and player.Team.Name == "Snipers" then
			XSF.SetLoadout(player, { "R700", "USP", "M18" })
		else
			XSF.SetLoadout(player, { "HK416", "USP", "M67" })
		end
	end)
end)

The task.wait() matters. XSF hands out the normal loadout when the character spawns, and without the wait your loadout can arrive first and get replaced. If you always give weapons yourself, add GiveLoadout = false to GameConfig and you can skip the wait.

XSF.Give(player, name)

Adds one weapon after the player's last slot, with full ammo. Giving a weapon they already carry gives them a second copy, so check first if that matters.

-- a pad that gives each player one shotgun per life
local given = {}
script.Parent.Touched:Connect(function(hit)
	local player = game.Players:GetPlayerFromCharacter(hit.Parent)
	if player and given[player] ~= player.Character then
		given[player] = player.Character
		XSF.Give(player, "M870")
	end
end)

For a pickup that players can see and press, XSF.SpawnPickup is usually nicer, see Pickups.

XSF.Remove(player, name)

Takes one weapon away (the first copy if they have two). If it was in their hands, their hands are left empty.

XSF.AddAmmo(player, name, amount)

Adds spare ammo, not to the magazine.

-- an ammo crate: 60 rounds for whatever they are holding
XSF.AddAmmo(player, nil, 60)

XSF.GetEquipped(player)

Returns the name of the weapon the player is holding, or nil if their hands are empty (including when they holstered).

XSF.GetInventory(player), XSF.GetAmmo(player, weapon), XSF.GetAttachments(player, weapon)

Read what a player carries, as the server sees it. GetInventory returns weapon names in slot order. GetAmmo returns two numbers, the magazine and the spare rounds, or nil if they don't carry that weapon. GetAttachments returns a copy of that gun's kit (slot to name), or nil.

-- a shop that refills whatever runs low
for _, name in ipairs(XSF.GetInventory(player)) do
	local mag, reserve = XSF.GetAmmo(player, name)
	if reserve and reserve < 30 then XSF.AddAmmo(player, name, 60) end
end

XSF.SetAttachments(player, weapon, attachments)

Changes a gun's attachments, ammo and skin. Everyone sees the change, and the gun in their hands updates straight away. This skips the loadout screen rules and unlocks, so you can fit things players can't pick themselves.

Returns: true if the player carries that weapon, false if not.

XSF.SetAttachments(player, "HK416", {
	Sight = "Acog",
	Barrel = "Suppressor",
	UnderBarrel = "Angled Grip",
	Ammo = "Armor Piercing",
	Skin = "Woodland",
})

XSF.SetCustomizeCheck(fn)

Lets your game refuse a loadout change, for example once a round has started or outside a safe zone. fn(player, weapon, kit) runs on the server every time a player applies a change in the loadout screen (or with SetKit from the client API), after XSF's own checks (the attachment fits, it's unlocked, Customization.Required). Return false to refuse it, with a second value as the reason the player sees. Return anything else (or nothing) to allow it.

There is one check at a time; calling it again replaces the old one, and XSF.SetCustomizeCheck(nil) removes it. If your function errors, the change is refused, the player sees "Not allowed right now." and the error is printed as a warning. Don't yield in it for long; the player waits for the answer. It doesn't stop XSF.SetAttachments from your own scripts.

local XSF = require(game.ServerScriptService.XSF.Server)

-- no loadout changes once the round is live, and no thermals in this mode
local roundLive = workspace:GetAttribute("RoundLive")
workspace:GetAttributeChangedSignal("RoundLive"):Connect(function()
	roundLive = workspace:GetAttribute("RoundLive")
end)

XSF.SetCustomizeCheck(function(player, weapon, kit)
	if roundLive then
		return false, "You can change attachments between rounds."
	end
	if kit.Sight == "Thermal" then
		return false, "Thermal sights are off in this mode."
	end
end)

XSF.MountWeapon(model, name, attachments)

Puts a gun in the hands of any character model, for NPCs or display. For NPCs, setting the XSF_Weapon attribute is usually easier (see NPCs with guns).

Damage and downed

XSF.Damage(humanoid, amount, attacker, zone, options)

Hurts a character the same way a bullet would. Armour, downing, hit markers, kill credit, Damage.Modify and the Damaged and Killed events all work.

Returns: the damage actually dealt after armour, or 0 if it was blocked (teammate, ForceField, already dead).

-- a killstreak gunship: the hit comes from the sky and shows in the kill feed
XSF.Damage(hum, 120, owner, "Torso", { from = gunship.Position, weapon = "AC-130" })

-- a lava floor
script.Parent.Touched:Connect(function(hit)
	local hum = hit.Parent:FindFirstChildOfClass("Humanoid")
	if hum then XSF.Damage(hum, 15) end
end)

XSF.IsDowned(humanoid)

Returns true if someone is down and waiting for a revive.

XSF.Revive(humanoid, by)

Gets a downed character back up at Downed.ReviveHealth. by is the optional Player who revived them, passed on to the Revived event.

Grenades, explosions and pickups

XSF.SpawnGrenade(name, position, velocity, fuse, thrower)

XSF.Explode(position, settings, attacker, weapon)

An explosion anywhere. settings takes Radius (default 20), Damage (default 150), and optionally Cone (degrees) and Back (damage share behind the cone) for directional blasts. attacker and weapon are optional, for kill credit and kill feeds. See Explosives.

XSF.SpawnPickup(name, where, options)

Spawns a gun or an ammo box (name = "Ammo") at a CFrame or Vector3. Returns the pickup model. See Pickups for the options.

Unlocks and skins

GrantAttachment, RevokeAttachment, OwnsAttachment, GrantSkin, RevokeSkin, OwnsSkin, EquipSkin, RollSkin, GetOwned and SetOwned are all covered in Unlocks and Skins.

Events

Connect with XSF.EventName:Connect(function(...) end). They all fire on the server.

local XSF = require(game.ServerScriptService.XSF.Server)

-- a simple kill feed and leaderstats
XSF.Killed:Connect(function(victim, attacker, weapon)
	if attacker and attacker:FindFirstChild("leaderstats") then
		attacker.leaderstats.Kills.Value += 1
	end
	print(("%s killed %s with %s"):format(
		attacker and attacker.Name or "the world", victim.Parent.Name, tostring(weapon)))
end)

-- headshot bonus
XSF.Damaged:Connect(function(victim, attacker, amount, zone)
	if attacker and zone == "Head" then
		print(attacker.Name .. " hit a headshot for " .. math.floor(amount))
	end
end)

-- flag players whose shots keep getting rejected
local rejects = {}
XSF.Rejected:Connect(function(player, reason)
	rejects[player] = (rejects[player] or 0) + 1
	if rejects[player] == 50 then
		warn(player.Name .. " has had 50 rejected shots, last reason: " .. reason)
	end
end)

A few rejects for a laggy player are normal. Hundreds in a minute is not.

Client scripts #

For your own LocalScripts: a custom HUD, kill feed, shop, main menu or cutscene. Require it from any LocalScript. Everything here only affects the local player.

local XSF = require(game.ReplicatedStorage:WaitForChild("XSF").Client.API)

Functions

The info table SetGunshotHandler passes:

Signals

local XSF = require(game.ReplicatedStorage:WaitForChild("XSF").Client.API)

-- a tiny ammo counter of your own (set Providers.HUD = "None" to hide XSF's)
local label = script.Parent.AmmoLabel
XSF.WeaponChanged:Connect(function()
	local w = XSF.GetWeapon()
	label.Text = w and (w.mag .. " / " .. w.reserve) or ""
end)

-- a hit sound and a kill sound
XSF.HitConfirmed:Connect(function(zone, killed)
	if killed then
		script.KillSound:Play()
	elseif zone == "Head" then
		script.HeadshotSound:Play()
	end
end)

-- your own gunshot sounds for one gun; every other gun keeps XSF's
XSF.SetGunshotHandler(function(info)
	if info.weapon ~= "Barrett" then return false end
	local s = script.BarrettShot:Clone()
	s.Volume = if info.own then 1 else math.clamp(1 - info.distance / 1500, 0.1, 1)
	local part = Instance.new("Part")
	part.Anchored, part.CanCollide, part.Transparency = true, false, 1
	part.Position = info.position
	part.Parent = workspace
	s.Parent = part
	s:Play()
	game:GetService("Debris"):AddItem(part, 4)
	return true
end)

-- a photo mode that hides the first person arms, even after a weapon switch
local photoMode = false
local currentArms
XSF.ArmsBuilt:Connect(function(arms)
	currentArms = arms
	if photoMode then
		for _, p in ipairs(arms:GetDescendants()) do
			if p:IsA("BasePart") then p.LocalTransparencyModifier = 1 end
		end
	end
end)

-- a shop: free the mouse and stop shooting while it is open
local function openShop()
	XSF.SetMenuOpen(true, "Shop")
	shopGui.Enabled = true
end
local function closeShop()
	shopGui.Enabled = false
	XSF.SetMenuOpen(false, "Shop")
end

Menus and the mouse

In first person XSF locks the mouse to the middle of the screen every frame. It lets go of it in these cases, and while it's free the mouse buttons never fire or aim:

• XSF's own screens (settings, loadout, backpack).
• Your menus opened with XSF.SetMenuOpen(true, name). Input is blocked too, so keys don't move or reload behind the menu. This is the one to use.
• Any visible GuiButton with Modal = true. That's Roblox's own way to free the mouse in first person, so menus built for normal Roblox games work as they are.
• While the player holds the FreeCursor key (Left Alt by default), for quick clicks on your UI without opening a menu.

If your game takes the character away without killing it (a main menu that calls Character:Destroy() or parents it to nil, a "leave match" button), XSF puts the gun away and hides its hotbar and scope overlay until the player spawns again, so nothing of XSF's is left floating on your menu.

Two more rules stop stray shots. If your script frees the cursor itself (setting MouseBehavior every frame), a click that lands on your visible UI still doesn't shoot. And the click that closes a menu, on its close button or the dark area around it, is never counted as a shot.

local XSF = require(game.ReplicatedStorage:WaitForChild("XSF").Client.API)

-- a deploy screen between lives
XSF.SetMenuOpen(true, "Deploy")
deployButton.Activated:Connect(function()
	deployGui.Enabled = false
	XSF.SetMenuOpen(false, "Deploy")
end)

-- hide your own HUD while XSF's settings menu is up
XSF.MenuChanged:Connect(function(name, open)
	if name == "Settings" then myHud.Enabled = not open end
end)

-- a killstreak camera: no XSF HUD while it runs
XSF.SetHUDVisible(false)
task.wait(30)
XSF.SetHUDVisible(true)

Movement state and speed

GetMovementState() returns this table, and OnMovement and AddSpeedModifier pass it to your function as state.

Don't set Humanoid.WalkSpeed yourself, XSF sets it again every frame. A speed modifier is the way to change it: it runs after sprint, aim, stance and dragging are worked out, so you get the final number and return your own. Several modifiers run in the order they were added.

local XSF = require(game.ReplicatedStorage:WaitForChild("XSF").Client.API)

-- a tactical sprint: hold sprint for two seconds and you get a short burst of speed
local heldFor = 0
XSF.OnMovement(function(dt, state)
	heldFor = if state.sprinting then heldFor + dt else 0
end)
XSF.AddSpeedModifier(function(speed, state)
	if state.sprinting and heldFor > 2 and heldFor < 4 then
		return speed * 1.25
	end
	return speed
end)

-- a mud zone: half speed while the player stands in it
local inMud = false
local stopMud = XSF.AddSpeedModifier(function(speed)
	return if inMud then speed * 0.5 else speed
end)
-- call stopMud() to remove it again

-- your own stamina bar
XSF.OnMovement(function(dt, state)
	bar.Size = UDim2.fromScale(state.stamina, 1)
	bar.BackgroundColor3 = if state.exhausted then Color3.fromRGB(200, 60, 60) else Color3.new(1, 1, 1)
end)

Things the client API can't do

It can't give weapons, ammo, damage or unlocks, on purpose. Anything that changes the game has to happen on the server, or exploiters could do it too. For a shop, the LocalScript asks the server with a RemoteEvent, and the server checks the player can afford it and calls the server API. There's a full example in Recipes.

NPCs with guns #

Any model in Workspace with a Humanoid can be shot, takes the same damage by body part as players, ragdolls when it dies and fires the same events. You don't need to register it. XSF finds it when it appears, including NPCs you clone in later.

To give an NPC a gun and pose it, set attributes on its model from a server script. XSF puts the gun in its hands and poses the body on every client.

local npc = workspace.Guard
npc:SetAttribute("XSF_Attachments", "Sight=Aimpoint;Other=Flashlight")
npc:SetAttribute("XSF_Weapon", "MP5")
npc:SetAttribute("XSF_Aim", 1)
npc:SetAttribute("XSF_Armor", 0.3)

Making NPCs shoot

NPC shooting logic is yours to write. XSF handles the gun, the pose, damage and death. The simplest way to make an NPC hurt players is a line of sight check and XSF.Damage:

local XSF = require(game.ServerScriptService.XSF.Server)
local npc = script.Parent
local head = npc:WaitForChild("Head")
local params = RaycastParams.new()
params.FilterDescendantsInstances = { npc }

local function closestPlayer()
	local best, bestDist = nil, 120
	for _, p in game.Players:GetPlayers() do
		local root = p.Character and p.Character:FindFirstChild("HumanoidRootPart")
		local hum = p.Character and p.Character:FindFirstChildOfClass("Humanoid")
		if root and hum and hum.Health > 0 then
			local d = (root.Position - head.Position).Magnitude
			if d < bestDist then best, bestDist = p, d end
		end
	end
	return best
end

while npc.Parent and npc.Humanoid.Health > 0 do
	local target = closestPlayer()
	if target then
		local root = target.Character.HumanoidRootPart
		local dir = root.Position - head.Position
		local hit = workspace:Raycast(head.Position, dir, params)
		if hit and hit.Instance:IsDescendantOf(target.Character) then
			npc:SetAttribute("XSF_Aim", 1)
			npc:SetAttribute("XSF_Pitch", math.asin(dir.Unit.Y))
			npc.HumanoidRootPart.CFrame = CFrame.lookAt(npc.HumanoidRootPart.Position,
				Vector3.new(root.Position.X, npc.HumanoidRootPart.Position.Y, root.Position.Z))
			if math.random() < 0.35 then -- it misses a lot
				XSF.Damage(target.Character.Humanoid, 18, nil, "Torso")
			end
		else
			npc:SetAttribute("XSF_Aim", 0)
		end
	end
	task.wait(0.25)
end

This doesn't fire visible bullets. For a full NPC that also plays shots and tracers, keep this logic and trigger your own sound and effect, or ask in the Discord for the current approach.

Downed NPCs

Set Downed.NPCs = true in GameConfig if NPCs should go down and be revivable instead of dying straight away. Your scripts can revive them with XSF.Revive, so an NPC squadmate that picks the player up (or that the player can pick up) is a few lines.

Test dummies

The test map's dummies are normal models with Humanoids. Copy one anywhere to get a target that takes damage and ragdolls.

Attributes #

XSF reads and sets a handful of attributes. The ones you can set are how you control things without code in XSF's modules. The ones XSF sets are safe to read from your own scripts.

You set these

XSF sets these (read only)

Don't set the read only ones yourself. Setting XSF_Downed by hand won't down anyone, it'll just confuse the HUD.

Swapping parts out #

The Providers section of GameConfig picks which version of a system runs.

Advanced: any of these can also point at your own ModuleScript instead of a name. It has to offer the same functions as the built in one, so this is only worth it for big custom projects. Ask in the Discord before you start, and we'll tell you what it needs.

Building your own HUD

Set Providers.HUD = "None", then build a ScreenGui and fill it from the client API: WeaponChanged and GetWeapon() for ammo, Hurt and the Humanoid's Health for health, StanceChanged for stance, HitConfirmed for hitmarkers.

Recipes #

Copy and paste starting points for things people build on XSF all the time. Each one is complete and works on its own in a fresh place with XSF installed. Change the names and numbers to fit your game.

Server code goes in a Script in ServerScriptService. Client code goes in a LocalScript in StarterPlayerScripts unless it says otherwise. Where a recipe needs a RemoteEvent, the server script creates it, so you don't have to.

Main menu with a Play button

Players spawn with no guns, see a menu, and get their loadout when they press Play. First add GiveLoadout = false to GameConfig.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local XSF = require(game.ServerScriptService.XSF.Server)

local play = Instance.new("RemoteEvent")
play.Name = "PlayPressed"
play.Parent = ReplicatedStorage

local inMatch = {}

play.OnServerEvent:Connect(function(player)
	if inMatch[player] then return end -- ignore spam clicks
	inMatch[player] = true
	XSF.SetLoadout(player, { "M4A1", "G17", "KaBar", "M67" })
end)

-- give guns again after a respawn, as long as they already pressed Play
game.Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function()
		if inMatch[player] then
			task.wait()
			XSF.SetLoadout(player, { "M4A1", "G17", "KaBar", "M67" })
		end
	end)
end)

game.Players.PlayerRemoving:Connect(function(player)
	inMatch[player] = nil
end)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local XSF = require(ReplicatedStorage:WaitForChild("XSF").Client.API)
local gui = script.Parent

-- free the mouse and keys while the menu is open
XSF.SetInputEnabled(false)

gui.Play.Activated:Connect(function()
	gui.Enabled = false
	XSF.SetInputEnabled(true)
	ReplicatedStorage:WaitForChild("PlayPressed"):FireServer()
end)

Set the ScreenGui's ResetOnSpawn to false, or the menu will pop up again every time the player dies.

Class picker

The same idea with a choice. The server owns the list of classes, so a modified client can only pick a class that exists.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local XSF = require(game.ServerScriptService.XSF.Server)

local CLASSES = {
	Assault  = { guns = { "HK416", "G17", "M67" },  atts = { HK416 = { Sight = "EOTech", UnderBarrel = "Vertical Grip" } } },
	Sniper   = { guns = { "R700", "USP", "M18" },   atts = { R700 = { Sight = "PM II", UnderBarrel = "Bipod" } } },
	Breacher = { guns = { "M870", "Deagle", "C4" }, atts = {} },
	Support  = { guns = { "M249", "M1911", "M67" }, atts = {} },
}

local pick = Instance.new("RemoteEvent")
pick.Name = "PickClass"
pick.Parent = ReplicatedStorage

local chosen = {}

local function equip(player)
	local class = CLASSES[chosen[player]]
	if not class then return end
	XSF.SetLoadout(player, class.guns)
	for gun, atts in pairs(class.atts) do
		XSF.SetAttachments(player, gun, atts)
	end
end

pick.OnServerEvent:Connect(function(player, name)
	if type(name) ~= "string" or not CLASSES[name] then return end
	chosen[player] = name
	equip(player)
end)

game.Players.PlayerAdded:Connect(function(player)
	player.CharacterAdded:Connect(function()
		task.wait()
		equip(player)
	end)
end)

game.Players.PlayerRemoving:Connect(function(player)
	chosen[player] = nil
end)

From your menu's buttons, call ReplicatedStorage.PickClass:FireServer("Sniper"). With GiveLoadout = false, players have nothing until they pick.

Leveling that unlocks attachments

Kills give XP, levels unlock attachments. Keep Customization.Ownership on (the default) and set Customization.SaveOwnership = true so unlocks are remembered between visits. XP itself is saved here with a simple DataStore.

local DataStoreService = game:GetService("DataStoreService")
local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

local store = DataStoreService:GetDataStore("XP_v1")
local XP_PER_KILL = 100
local XP_PER_LEVEL = 500

-- what each level unlocks (on every gun)
local REWARDS = {
	[2] = { "Reflex" },
	[3] = { "Compensator", "Angled Grip" },
	[5] = { "Acog", "Suppressor" },
	[8] = { "Hollow Point", "Armor Piercing" },
	[10] = { "PM II", "Thermal" },
}

local function levelOf(xp)
	return math.floor(xp / XP_PER_LEVEL) + 1
end

local function grantUpTo(player, level)
	for lvl = 1, level do
		for _, name in ipairs(REWARDS[lvl] or {}) do
			XSF.GrantAttachment(player, name)
		end
	end
end

Players.PlayerAdded:Connect(function(player)
	local stats = Instance.new("Folder")
	stats.Name = "leaderstats"
	local level = Instance.new("IntValue")
	level.Name = "Level"
	level.Parent = stats
	local xp = Instance.new("IntValue")
	xp.Name = "XP"
	xp.Parent = stats
	stats.Parent = player

	local ok, saved = pcall(store.GetAsync, store, "u_" .. player.UserId)
	xp.Value = (ok and saved) or 0
	level.Value = levelOf(xp.Value)
	grantUpTo(player, level.Value) -- also re-grants anything missed
end)

XSF.Killed:Connect(function(victim, attacker)
	if not attacker or not attacker:FindFirstChild("leaderstats") then return end
	if Players:GetPlayerFromCharacter(victim.Parent) == attacker then return end
	local stats = attacker.leaderstats
	stats.XP.Value += XP_PER_KILL
	local newLevel = levelOf(stats.XP.Value)
	if newLevel > stats.Level.Value then
		stats.Level.Value = newLevel
		grantUpTo(attacker, newLevel)
	end
end)

Players.PlayerRemoving:Connect(function(player)
	local stats = player:FindFirstChild("leaderstats")
	if stats then
		pcall(store.SetAsync, store, "u_" .. player.UserId, stats.XP.Value)
	end
end)

For a per gun progression (unlock the ACOG on the AK by getting kills with the AK), pass the weapon name from Killed to GrantAttachment(attacker, "Acog", weapon).

A skin shop with coins

The client asks, the server checks the price and the balance, then grants. Prices live on the server so nobody can buy for free.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

local PRICE_BY_RARITY = { Common = 100, Uncommon = 250, Rare = 600, Epic = 1500, Legendary = 4000 }

local buy = Instance.new("RemoteFunction")
buy.Name = "BuySkin"
buy.Parent = ReplicatedStorage

Players.PlayerAdded:Connect(function(player)
	local stats = Instance.new("Folder")
	stats.Name = "leaderstats"
	local coins = Instance.new("IntValue")
	coins.Name = "Coins"
	coins.Value = 500
	coins.Parent = stats
	stats.Parent = player
end)

-- 25 coins per kill
XSF.Killed:Connect(function(victim, attacker)
	if attacker and attacker:FindFirstChild("leaderstats") then
		attacker.leaderstats.Coins.Value += 25
	end
end)

buy.OnServerInvoke = function(player, skinName)
	local skin = type(skinName) == "string" and XSF.Skins[skinName]
	if not skin then return false, "No such skin" end
	if XSF.OwnsSkin(player, skinName) then return false, "You already own it" end
	local price = PRICE_BY_RARITY[skin.Rarity] or 100
	local coins = player.leaderstats.Coins
	if coins.Value < price then return false, "Not enough coins" end
	coins.Value -= price
	XSF.GrantSkin(player, skinName)
	return true, "Bought " .. skinName
end

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local ok, message = ReplicatedStorage:WaitForChild("BuySkin"):InvokeServer("Carbon Fiber")
print(message)

Save the coins the same way as the XP in the leveling recipe, and turn on Customization.SaveOwnership so bought skins stay bought.

Gamepass skins

local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

local GOLD_PACK = 000000000 -- your gamepass id
local GOLD_SKINS = { "Gold Plated", "Black Gold", "Rose Gold", "Brushed Gold" }

local function grantPack(player)
	for _, skin in ipairs(GOLD_SKINS) do
		XSF.GrantSkin(player, skin)
	end
end

Players.PlayerAdded:Connect(function(player)
	local ok, owns = pcall(MarketplaceService.UserOwnsGamePassAsync, MarketplaceService, player.UserId, GOLD_PACK)
	if ok and owns then grantPack(player) end
end)

-- bought it in game, no rejoin needed
MarketplaceService.PromptGamePassPurchaseFinished:Connect(function(player, passId, bought)
	if bought and passId == GOLD_PACK then grantPack(player) end
end)

Gamepass grants don't need saving, they're re-granted every time the player joins.

Battle royale loot

Put invisible, anchored, non colliding parts named Loot around your map (inside a folder called LootSpots). This fills them with random guns and ammo boxes. In GameConfig, add GiveLoadout = false and Pickups = { MaxWeapons = 3, Lifetime = 600 }.

local XSF = require(game.ServerScriptService.XSF.Server)

local LOOT = {
	{ name = "G17", weight = 30 }, { name = "MP5", weight = 20 }, { name = "UMP45", weight = 15 },
	{ name = "M870", weight = 12 }, { name = "AK47", weight = 10 }, { name = "HK416", weight = 8 },
	{ name = "SCAR", weight = 4 }, { name = "R700", weight = 3 }, { name = "AWM", weight = 1 },
}
local SIGHTS = { "Reflex", "EOTech", "Aimpoint", "Acog" }

local total = 0
for _, item in ipairs(LOOT) do total += item.weight end

local function roll()
	local r = math.random() * total
	for _, item in ipairs(LOOT) do
		r -= item.weight
		if r <= 0 then return item.name end
	end
	return LOOT[1].name
end

local function fill()
	for _, spot in ipairs(workspace.LootSpots:GetChildren()) do
		if math.random() < 0.25 then
			XSF.SpawnPickup("Ammo", spot.CFrame, { Mags = 2, Uses = 2 })
		else
			local atts = {}
			if math.random() < 0.3 then atts.Sight = SIGHTS[math.random(#SIGHTS)] end
			-- leave mag and reserve out: the gun comes with its normal spawn ammo
			XSF.SpawnPickup(roll(), spot.CFrame + Vector3.new(0, 1, 0), { atts = atts })
		end
	end
end

fill() -- call fill() again at the start of every round

Rounds with a timer

A team deathmatch loop: intermission, a timed round, a winner, repeat. Assumes two Teams called Red and Blue and turns downed off for quick fights (Downed = { Enabled = false }).

local Players = game:GetService("Players")
local Teams = game:GetService("Teams")
local XSF = require(game.ServerScriptService.XSF.Server)

local ROUND_TIME = 300
local INTERMISSION = 15
local score = { Red = 0, Blue = 0 }
local running = false

local status = Instance.new("StringValue")
status.Name = "RoundStatus"
status.Parent = game.ReplicatedStorage -- show this in your own UI

XSF.Killed:Connect(function(victim, attacker)
	if not running or not attacker or not attacker.Team then return end
	local victimPlayer = Players:GetPlayerFromCharacter(victim.Parent)
	if victimPlayer and victimPlayer.Team ~= attacker.Team then
		score[attacker.Team.Name] = (score[attacker.Team.Name] or 0) + 1
	end
end)

while true do
	for t = INTERMISSION, 1, -1 do
		status.Value = "Next round in " .. t
		task.wait(1)
	end

	score.Red, score.Blue = 0, 0
	running = true
	for _, p in ipairs(Players:GetPlayers()) do
		p:LoadCharacter() -- everyone respawns with a fresh loadout
	end

	for t = ROUND_TIME, 1, -1 do
		status.Value = ("Red %d  |  %d:%02d  |  %d Blue"):format(score.Red, t // 60, t % 60, score.Blue)
		task.wait(1)
	end
	running = false

	local winner = score.Red > score.Blue and "Red" or score.Blue > score.Red and "Blue" or "Nobody"
	status.Value = winner .. " wins!"
	task.wait(5)
end

Gun game

Every kill moves you to the next gun. First to finish the list wins.

local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

local LADDER = { "AK47", "HK416", "SCAR", "P90", "MP5", "M870", "AWM", "Deagle", "G17", "KaBar" }
local stage = {}

local function arm(player)
	XSF.SetLoadout(player, { LADDER[stage[player] or 1] })
end

Players.PlayerAdded:Connect(function(player)
	stage[player] = 1
	player.CharacterAdded:Connect(function()
		task.wait()
		arm(player)
	end)
end)

Players.PlayerRemoving:Connect(function(player)
	stage[player] = nil
end)

XSF.Killed:Connect(function(victim, attacker)
	if not attacker or not stage[attacker] then return end
	if Players:GetPlayerFromCharacter(victim.Parent) == attacker then return end
	stage[attacker] += 1
	if stage[attacker] > #LADDER then
		print(attacker.Name .. " wins gun game!")
		for p in pairs(stage) do stage[p] = 1 end
		for _, p in ipairs(Players:GetPlayers()) do p:LoadCharacter() end
	else
		arm(attacker)
	end
end)

Add GiveLoadout = false, Downed = { Enabled = false } and Pickups = { Enabled = false } to GameConfig so nobody skips the ladder by grabbing a dropped gun.

A kill feed on everyone's screen

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

local feed = Instance.new("RemoteEvent")
feed.Name = "KillFeed"
feed.Parent = ReplicatedStorage

local lastZone = {}
XSF.Damaged:Connect(function(victim, attacker, amount, zone)
	lastZone[victim] = zone
end)

XSF.Killed:Connect(function(victim, attacker, weapon)
	local victimPlayer = Players:GetPlayerFromCharacter(victim.Parent)
	feed:FireAllClients(
		attacker and attacker.Name or "",
		victimPlayer and victimPlayer.Name or victim.Parent.Name,
		weapon or "",
		lastZone[victim] == "Head"
	)
	lastZone[victim] = nil
end)

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local feed = script.Parent.Feed

ReplicatedStorage:WaitForChild("KillFeed").OnClientEvent:Connect(function(killer, victim, weapon, headshot)
	local line = Instance.new("TextLabel")
	line.Size = UDim2.new(1, 0, 0, 22)
	line.BackgroundTransparency = 1
	line.TextColor3 = Color3.new(1, 1, 1)
	line.TextXAlignment = Enum.TextXAlignment.Right
	line.Font = Enum.Font.GothamBold
	line.TextSize = 16
	line.Text = (killer ~= "" and killer .. "  [" .. weapon .. "]  " or "") .. victim .. (headshot and "  (headshot)" or "")
	line.Parent = feed
	task.delay(6, function() line:Destroy() end)
end)

Armour pickups

local part = script.Parent
local used = false

part.Touched:Connect(function(hit)
	if used then return end
	local char = hit.Parent
	local player = game.Players:GetPlayerFromCharacter(char)
	if not player then return end
	used = true
	char:SetAttribute("XSF_Armor", 0.4)
	char:SetAttribute("XSF_Helmet", 0.5)
	part.Transparency = 1
	task.wait(30) -- respawns after 30 seconds
	part.Transparency = 0
	used = false
end)

Armour lasts until the character dies, because the attributes are on the character. For armour that breaks, lower XSF_Armor a bit in XSF.Damaged every time the player is hit.

Kill streak rewards

local Players = game:GetService("Players")
local XSF = require(game.ServerScriptService.XSF.Server)

local streak = {}

XSF.Killed:Connect(function(victim, attacker)
	local victimPlayer = Players:GetPlayerFromCharacter(victim.Parent)
	if victimPlayer then
		streak[victimPlayer] = 0
	end
	if not attacker or attacker == victimPlayer then return end
	streak[attacker] = (streak[attacker] or 0) + 1
	if streak[attacker] == 3 then
		XSF.AddAmmo(attacker, nil, 60)
	elseif streak[attacker] == 5 then
		XSF.Give(attacker, "M320")
	elseif streak[attacker] == 10 then
		-- airstrike on the attacker's last victim
		local pos = victim.Parent:GetPivot().Position
		for i = 1, 5 do
			task.delay(i * 0.4, function()
				XSF.Explode(pos + Vector3.new(math.random(-20, 20), 0, math.random(-20, 20)),
					{ Radius = 18, Damage = 180 }, attacker, "Airstrike")
			end)
		end
	end
end)

Headshots only

A hardcore mode where only headshots hurt. This goes in GameConfig, not a script:

Damage = {
	FriendlyFire = false,
	Hitmarkers = false,
	Modify = function(humanoid, amount, info)
		-- explosions and script damage still hurt, so grenades and lava work as normal
		local explosive = { M67 = true, C4 = true, Claymore = true, RPG7 = true, M320 = true }
		if info.weapon and not explosive[info.weapon] and info.zone ~= "Head" then
			return 0 -- body and limb hits from guns and knives do nothing
		end
		return amount
	end,
},

Spawn protection

XSF already respects Roblox's ForceField. Set Duration on your SpawnLocations (3 to 5 seconds is common) and players can't be hurt by XSF until it wears off. That's the whole recipe.

Building maps for XSF #

XSF is realistic enough that the map decides how fights play. Bullets go through some walls and not others, players can vault and climb, and leaning lets them peek corners. A few numbers to build around:

Scale

• One stud is 28 cm (Ballistics.StudsPerMeter). A standard Roblox character is about 5 studs tall, so a 7 to 8 stud doorway and 10 to 12 stud ceilings feel right.
• Default walk speed is 12 studs per second and sprint is 21. A 300 stud long street takes about 15 seconds to sprint, which is longer than most players expect. Size your map for the speeds you picked.

Cover that works the way players expect

Players will learn what stops bullets. Make it consistent:

• Hard cover (Concrete, Brick, Rock, Metal) at 1 stud or thicker stops everything up to a rifle. Use it for walls players are meant to hide behind.
• Soft cover (Wood, Plastic, Fabric) stops vision, not bullets. Rifles go through 2 studs of wood. Use it for fences, crates and interior walls, so shooting through them is a real tactic.
• Glass barely slows a bullet.
• A part that looks like concrete but uses SmoothPlastic is shoot through. Match materials to looks, or set XSF_PenetrationCost where they don't match.
• Thicker than 6 studs always stops bullets, whatever the material.

The full table is in Bullets and walls.

Heights

These follow Vault.VaultHeight, Vault.MaxHeight and the stance headroom checks. Change the Vault values and these change with them.

Corners and leaning

Leaning moves the head 1.1 studs sideways (Stances.LeanOffset). A doorway with walls thinner than that lets players peek without exposing their body, which is good. Pillars thinner than about 2 studs let players lean around both sides.

Sight lines

Match your longest sight lines to the guns you give out. Rifle damage starts falling at 150 studs by default and reaches its lowest at 600. Snipers keep full damage out to 500 to 1000 studs. A map with 800 stud sight lines and only SMGs is just frustrating. The range of every gun is in Every weapon's stats.

Lighting

If you plan to give out Night Vision or Thermal, make some areas really dark. Night vision is only worth picking when the map has places you can't see without it. Thermal shines in smoke and shadow.

Props

• Anchor anything that doesn't need to move. Loose parts get pushed by every bullet and blast, which costs performance in a big fight.
• A few loose barrels or crates near where fights happen look great when they get blown around.
• Keep invisible walls tall (over 7 studs) so players can't climb them.

Placing XSF things

• Workbenches (with Customization.Access = "Workbench") belong at spawns and safe spots, not in the middle of fights.
• Ammo boxes (XSF.SpawnPickup("Ammo", ...)) on routes between fights, so players are tempted to move.
• Loot spots for a battle royale: more and better loot in riskier places.

Balancing guns #

XSF's guns ship balanced against each other for a realistic game with 100 health. If you change health, add armour or only use a few guns, you'll want to adjust. Here's how to think about it.

Time to kill

The number that matters most is how long it takes to kill someone. Work it out like this:

1. Shots to kill = 100 health divided by damage per shot, rounded up.
2. Time to kill = (shots to kill minus 1) times 60 divided by RPM.

An HK416 does 60 to the body: 2 shots. At 800 RPM that's one gap of 0.075 seconds. An MP5 does 34: 3 shots, two gaps at 800 RPM, 0.15 seconds. A G17 does 28: 4 shots, three gaps at 480 RPM, 0.375 seconds. That ignores misses, travel time and falloff, but it's the right starting point.

With downed on, add Downed.DownedHealth (40) to finish someone, so the HK416 needs one more shot to actually kill.

Roles, not just numbers

Two guns with the same time to kill still feel different because of everything else. Give each gun a reason to pick it:

Headshots

Most rifles do about 2.5 times body damage to the head, so any headshot is a kill at 100 health. If you raise health to 150 or add helmets, headshots stop being one shot for most guns. Decide if you want that.

Armour changes everything

XSF_Armor = 0.4 makes every body shot do 60%. An HK416 goes from 2 shots to 3, an MP5 from 3 to 5. Armour piercing ammo cuts that armour to 0.16. If you add armour, test the weak guns first. Pistols and SMGs suffer the most.

Shotguns

Shotgun damage is per pellet, 8 pellets per shot. The 870's 28 per pellet is 224 if every pellet hits, which is a kill even through armour up close. To make shotguns weaker at range without touching close range, shorten FalloffEnd or widen PelletSpread.