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.3 #

2.3 is about three things: a server that's harder to cheat on and cheaper to run, screens you can restyle without code, and much better phones and controllers. Nothing you set up changes except one default (everything is unlocked, see below). To update from 2.2, see Updating from 2.2 to 2.3.

Anti-cheat and a faster server

• Every request a player sends is rate limited and type checked, and anything that looks like cheating adds points to a suspicion score you can read from your scripts. XSF still never kicks or bans on its own. Movement is checked too: speed, teleports and flying, report only. See Anti-cheat and suspicion.
• Knives can't hit through walls, and every shot, swing and throw starts from where the player really is.
• Big servers: shots are sent to players in batches, poses take a fraction of the data, and hit checks are about three times cheaper. Before 2.3, servers with more than about 20 players could lose pose updates.

Screens you can edit

• Every XSF screen is a ScreenGui in ReplicatedStorage.XSF.UI. Edit it in Properties like any GUI; XSF finds what it needs by name. A Theme module switches the whole look (Tactical, Arcade, Military, Minimal). The UI code is open source. See Editing XSF's screens.
• A crosshair players can tune (style, colour, size, gap, thickness, opacity, outline), hit marker styles, a low ammo warning and real stat bars in the loadout screen. See Crosshair, hit markers and ammo warning.
• Menus open and close with a short motion, and an XSF settings button sits in Roblox's top bar.

Phones and controllers

• Players move, resize, turn and hide every phone button, saved per player. Optional auto fire, gyro aim, swipe the weapon bar, tap ammo to reload. See Phone button layout.
• Hold RB for a weapon wheel, real controller button pictures in menus, a focus ring, and aim assist that can gently pull toward a target. See Controllers and the weapon wheel.

More

• Ping markers on middle mouse, for your team, with thumbs up. See Ping markers.
• Graphics modes Full, Balanced and Performance, picked automatically from each player's frame rate. See Graphics modes.
• Look and scoped sensitivity. The aim sensitivity slider is now called Scoped sensitivity, and it actually works (before 2.3 it did nothing).
• Everything unlocked by default. Customization.Ownership now ships as { Attachments = false, Skins = false }, so every player can use every attachment and skin until you lock them. See Unlocks.
• Performance reports. Servers send a small anonymous summary to the XSF site every 5 minutes so lag can be found and fixed. PerformanceReports = false turns it off. See Performance reports.

Fixes

• During a reload the old magazine could pop back into the gun while the hand went to the pouch empty, and during a magazine check (T) it jumped between the hand and the gun. The hand now holds it the whole way.
• The Scoped sensitivity slider did nothing.
• Grenades showed no picture in the backpack.
• The settings menu left a listener behind every time a tab with sliders was opened.
• The gun in your hands looked blurred on maps with depth of field, and the Bodycam grain was heavy. See Grain and blur.
• A hit marker switched on in GameConfig couldn't be turned off by players.
• Values like NaN sent to the server could break a knife swing or a shot.

New in 2.2 #

2.2 is a beta. It may be unstable, and a newer version will be released soon. If you'd rather wait, 2.1.0 is still on your account page in the version box under the download button. Please report anything odd in the Discord or on the support page.

2.2 fixes the launcher and scope reports from the community and adds two things developers asked for when bringing their own guns. Nothing you set up changes. To update from 2.1, see Updates; it's the same steps as 2.0 to 2.1.

Scope zoom

Variable scopes now zoom while you aim: mouse wheel up to zoom in, down to zoom out. The PM II goes from 5.8x to 8.8x and 14x, the M82's own scope from 2.3x to 3.5x and 5.4x, and the scope readout shows the magnification. Bind ZoomIn and ZoomOut for controllers. Your own scopes get steps with Zoom. See Scope zoom.

Skins on your own guns

Guns with their own textures can keep them under a skin (XSF_SkinKeep): the skin tints them and patterns lie on top. You can also choose exactly which parts a skin paints, and as what, with XSF_SkinRole and XSF_SkinOnlyTagged. See Skins on your gun.

Iron sights fold away

Fit a sight and the gun's iron sights get out of the way. On the HK416, MP5 and HK33 they disappear; on your own guns tag them with XSF_IronSight, and add XSF_Fold to have them flip down flat. Customization.FoldIronSights = false keeps them up.

Licensing

The license check is more patient and clearer. It retries with growing gaps when the site doesn't answer, treats an outage differently from a real refusal, and never stops a running server because the site is down. A new server that passed a check in the last 3 days still starts during an outage (live servers only, Studio always asks the site). If the site does refuse the license while a server is running (the license or game was revoked), XSF's weapons, explosives and damage stop on that server: new shots and actions are refused. Nothing is deleted, nobody is kicked, and your own scripts keep running. Every download is also traceable to the account it was made for.

Fixes

• A rocket could keep flying through walls on your screen after it had already hit something on the server. This happened with lag, on maps where the wall hadn't streamed in, or when it hit a moving player. Your copy now ends where the server's did.
• The RPG-7 and M320 now go off at point blank (Arm = 0), so firing at your own feet hurts you like it should. Before, anything closer than 18 studs (RPG) or 14 studs (M320) was a dud.
• The license server no longer refuses real keys from busy games. Roblox servers share a few outgoing addresses, so games with many servers could get "Too many license checks" and switch XSF off, sometimes in the middle of a match. Only wrong keys are limited now. This fix is on the website, so 2.1 games already have it.

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.3.0.rbxmx (older versions are in the version box under the download button). 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 every player can use every attachment and skin. If you plan to sell or unlock them later, set Customization.Ownership = { Attachments = true, Skins = true } and players only get what your game gives them. 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.com/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, mouse and touch are never affected. Looking slows down while an enemy is near the barrel, and while the player moves the stick the view eases gently toward them. It never snaps or locks on, and does nothing while the stick is still. Players scale all of it with Controller aim assist in the CAMERA tab (0 turns it off for them).

Rumble

Controls

Ballistics

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

Debug

UI

The look of every screen is in ReplicatedStorage.XSF.UI, not in GameConfig. See Editing XSF's screens.

Ping

Graphics

Mobile

PerformanceReports

Security

See Anti-cheat and suspicion.

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), ping, lean left and right, fire mode, settings, the loadout screen (KIT), drop and inspect. The hotbar stays on screen so players can tap a slot or swipe along it.
• Players can move, resize, turn and hide every button (MOBILE tab, Move, resize and hide buttons), and turn on auto fire and gyro aim. See Phone button layout.
• Tap crouch to crouch, hold it to go prone.
• Graphics modes pick Full, Balanced or Performance for each phone by itself. See Graphics modes.
• 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 near an enemy and eases the view toward them while the stick moves. It never snaps or locks on. See AimAssist.
• Hold RB for the weapon wheel, tap it for the next weapon. Menus show real controller button pictures. See Controllers and the weapon wheel.
• 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

The settings menu also opens from the round XSF button in Roblox's top bar.

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 the graphics mode, hit markers, the crosshair (unless UI.Crosshair.Allowed = false), the low ammo warning and the phone extras. 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.

Sensitivity

There are two: Look sensitivity for normal looking and Scoped sensitivity while aiming down the sights, on every scope and red dot (one value for all of them, not per scope). Your defaults are Camera.Sensitivity and Camera.AimSensitivity. Phones use Look sensitivity for dragging. In 2.2 and older the aim slider did nothing; since 2.3 it works.

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("CrosshairStyle", "Dot")
end

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

Editing XSF's screens #

Since 2.3 every XSF screen is a normal ScreenGui you can open and edit in Studio, and all the code that draws them is open source. You don't need to write any code to restyle the HUD, hotbar, backpack, settings menu, loadout screen or death screen: select an element, change it in Properties, play.

Where they are

UI
  Theme          ModuleScript: colours, fonts, animation speed, presets
  XSF_HUD        ammo, health, stance, crosshair, hit marker, damage markers, scope readout, downed panel
  XSF_Hotbar     the weapon bar at the bottom
  XSF_Backpack   the backpack panel (B)
  XSF_Settings   the settings menu (P)
  XSF_Loadout    the loadout screen (N)
  XSF_Death      the fade when you die

When a screen starts, XSF clones its template into the player's PlayerGui and looks up every element it needs by name. That is the only rule: keep the names. Move things, resize them, recolour them, change fonts, add your own frames, images, gradients and strokes. XSF fills the elements it knows and leaves everything else alone.

How to edit

1. Open ReplicatedStorage.XSF.UI in Explorer and select a ScreenGui, for example XSF_HUD.
2. To see it while you work, drag a copy into StarterGui, edit it there, then drag it back into XSF.UI (replacing the old one) and delete the copy. Templates inside ReplicatedStorage don't draw on your Studio screen.
3. Change any property you like. Text that XSF fills (ammo count, weapon name) is replaced while playing, so its Text in the template is only a placeholder.
4. Play. Your version is what players see.

The Theme

XSF.UI.Theme sets colours, fonts and animation speed for every screen at once.

-- "Tactical" | "Arcade" | "Military" | "Minimal"
Theme.Preset = "Tactical"

-- single changes on top of the preset
Theme.Overrides = {
	Colors = { Amber = Color3.fromRGB(255, 200, 40) },
	Fonts = { Display = Font.new("rbxasset://fonts/families/Bangers.json") },
}

-- 1 is normal, 0.5 twice as fast, 0 turns XSF's UI animations off
Theme.AnimationSpeed = 1

The colour names and what they're used for:

Fonts: Display (titles and weapon names), DisplayBold (big numbers), Mono (small labels and readouts), Body (longer text in menus).

How the Theme and your edits work together: an element whose colour or font you never touched follows the Theme. As soon as you change one in Properties, your value stays, whatever the Theme says. So you can switch to Arcade and still keep the red health bar you picked by hand. A preset name that doesn't exist prints one warning in Studio and falls back to Tactical.

Repeating items (examples)

Lists that grow (hotbar slots, backpack tiles, settings rows, loadout tabs) use one hidden example inside the list. XSF copies it for every item, so restyle the example and every item follows. Examples carry the attribute XSF_Proto = true and stay hidden.

Every element XSF looks for

Screens without a template

A few screens are built from code because they are small or appear rarely: XSF_Wheel (weapon wheel), XSF_Touch (phone buttons), XSF_Topbar (the settings button in Roblox's top bar), XSF_Pings (ping markers), XSF_Notice (the graphics notice) and XSF_TouchEditorBar. You can still restyle them the same way: press Play, find the screen in Players.YourName.PlayerGui, copy it, stop the game, paste it into ReplicatedStorage.XSF.UI and edit it. XSF uses your copy from then on. The pieces each one looks for:

Fail safes

• A missing element never breaks XSF. If you delete or rename something XSF needs, that piece simply doesn't show, and Output says once which element is missing, where it should be and how to bring it back, for example: XSF_HUD.WeaponPanel.Weapon.Ammo is missing (the ammo count). XSF keeps working without it. To bring it back, add a TextLabel named Ammo inside XSF_HUD.WeaponPanel.Weapon, or copy it from the stock template in the XSF download.
• The wrong kind of element (a Frame where XSF needs a TextLabel) is left alone and Output says what it needs to be.
• A missing example (say you deleted Tile) gives a warning and XSF uses the stock look for those items.
• No template at all: delete a whole ScreenGui from XSF.UI and XSF builds the stock screen from code, exactly as it looks out of the box.
• On screen in Studio: problems that matter (a missing element, a broken setting, a server warning) also appear in a small panel at the top of your screen while you test in Studio, so you don't have to watch Output. Players in live games never see it.

From your scripts

The client API has XSF.UI:

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

-- add your own bits to an XSF screen once it is built (and again if it is rebuilt)
XSF.UI.OnBuilt("XSF_HUD", function(hud)
	local tag = Instance.new("TextLabel")
	tag.Text = "SEASON 1"
	tag.FontFace = XSF.UI.Fonts.Display
	tag.TextColor3 = XSF.UI.Colors.Amber
	tag.BackgroundTransparency = 1
	tag.Size = UDim2.fromOffset(200, 24)
	tag.Position = UDim2.new(0, 34, 0, 20)
	tag.Parent = hud
end)

-- hide the hotbar during a cutscene, whatever XSF wants to do with it
XSF.UI.SetVisible("XSF_Hotbar", false)
task.wait(5)
XSF.UI.SetVisible("XSF_Hotbar", true)

-- the live ScreenGui, or nil if it hasn't been built yet
local settingsGui = XSF.UI.Get("XSF_Settings")

Animations

The settings menu, loadout screen and backpack rise a little and grow into place while the dimmed background fades in, and do the reverse when they close. The weapon wheel pops in. Only position, scale and transparency move, so they stay smooth at any frame rate. Theme.AnimationSpeed = 0 turns them off.

Controller focus

When a controller selects a button in an XSF menu it gets one shared focus ring instead of Roblox's default box. To use your own, put a Frame called FocusRing directly in ReplicatedStorage.XSF.UI; XSF uses it on every menu. Controller button pictures (A, B, X, Y, LB, RB, triggers) come from Roblox itself, so players see the right glyphs for their own controller.

Updating later

When you update XSF, keep your edited templates: copy them out before deleting the old XSF and put them back into the new XSF.UI. New versions may add elements; anything your old template doesn't have is listed once in Output, and you can copy just those pieces from the new stock template.

Crosshair, hit markers and ammo warning #

Players tune all of this in Settings > HUD, with a live preview at the top of the tab that shows the crosshair over a light and a dark background (so they can check colour and outline) and opens and closes it in a loop when "opens up" is on.

The crosshair

It shows while you hip fire with a weapon out, and hides when you aim down the sights, when you have nothing in your hands, and when the HUD is off.

XSF bullets come out of the barrel, so the crosshair is a guide to where the barrel points, not a cone of fire. With free aim on (Bodycam style) the gun can drift a little from the centre; that's why the default is Off for realistic games.

For you: UI.Crosshair = { Default = "Off", Allowed = true } in GameConfig. Default is the style new players start with ("Off", "Dot", "Cross", "Cross + dot", "Circle" or "T"). Allowed = false removes the crosshair from your game completely: the crosshair rows disappear from the menu and nothing shows whatever players had saved. Players who had the 2.2 "Centre dot" switch on get the Dot style.

Your own crosshair: the Crosshair frame in XSF_HUD holds Top, Bottom, Left, Right, Dot and Ring, which XSF sizes from the player's settings. To draw your own instead (an image, a chevron), give Crosshair the attribute Custom = true and put whatever you like inside. XSF then only shows and hides it at the right moments and never touches what's inside.

Hit markers

A small mark at the centre when your shot lands on someone. It pops out and fades in about a third of a second. Players turn it on in Settings > HUD > Hit markers; Damage.Hitmarkers in GameConfig is what new players start with.

Colour tells you what happened: red for a kill (it also pops bigger), amber for a head shot, bone (off white) for any other hit. The colours follow the Theme. To draw your own, give Hitmarker in XSF_HUD the attribute Custom = true: XSF then shows it as you made it and only recolours it.

Low ammo warning

A word under the crosshair when it matters, pulsing gently:

It only shows for guns, not while jammed (the HUD says JAMMED instead) and not with the HUD off. Players turn it off in Settings > HUD > Low ammo warning; you turn it off for everyone with UI.LowAmmoWarning = false. Restyle it with the LowAmmo label in XSF_HUD.

Damage direction

When you're hit, a red mark around the centre points to where the shot came from and fades over about a second. DamageRing in XSF_HUD has a Radius attribute (pixels from the centre, 120 by default) and a hidden Marker example: restyle Marker (an image works too) and every hit uses your look.

Graphics modes #

Three modes, picked for each player's device so phones stay smooth and good PCs get everything. They only change what that one player sees. Your map is untouched for everyone else, and nothing is sent to the server.

Auto

Every player starts on Auto. Five seconds after they first spawn (so the map has streamed in), XSF measures their frame rate for six seconds and picks a mode: 75 fps or more gets Full, 45 or more gets Balanced, anything lower gets Performance. It uses the middle value of those frames, so a single hitch can't drag a good PC down.

If the game then stays under 35 fps for 6 seconds in a row while they're alive (a big fight, a heavy part of the map), Auto drops one mode and shows a short note at the top of the screen: Graphics set to BALANCED to keep the game smooth. Change it in Settings. It waits at least 30 seconds before dropping again, and never steps back up on its own in the same session, so it can't flicker between modes.

Players

Settings > EFFECTS > Graphics: Auto, Full, Balanced or Performance. A mode they pick stays picked and Auto never changes it. Players who had the old Low effects switch on are moved to Performance.

You

Grain and blur

If your game looks soft, it's usually the map's own DepthOfField in Lighting, which blurs anything past a set distance, plus the Bodycam grain. Since 2.3 XSF keeps the gun in your hands sharp in first person by turning the map's near blur off while you're alive (it goes back to your value when you die, and the far blur is never touched). Turn that off with Camera.SharpWeapon = false. The grain is lighter, redraws less often and only shows in Full. To lose the far blur too, lower FarIntensity on your DepthOfField or delete it, and players can turn off Lens and grain in EFFECTS.

Frame rate cap

XSF itself never caps the frame rate. Players set their own cap in Roblox's menu (Escape, Settings, Maximum Frame Rate), up to 240. Everything in XSF is timed by real time, so recoil, sway and animations play the same at 30, 60, 144 or 240 fps.

Ping markers #

Press middle mouse (the Ping key) to mark what you're looking at for your team, like in Fortnite or Apex. On phones it's the PING button.

Each player has one marker at a time; a new ping replaces the old one. Markers show who placed them and how far away they are, stay for 12 seconds, and stay on screen through walls.

GameConfig

Ping = {
	Enabled       = true,
	TeamOnly      = true,  -- only teammates see them (in a game without teams, only you)
	RemoveOnDeath = true,  -- your marker goes away when you die
	Lifetime      = 12,    -- seconds a marker stays
	MaxDistance   = 1000,  -- how far you can ping, in studs
},

The client only says where the player looked. The server checks the spot is real and within MaxDistance of the player, limits pings to about 3 a second, and decides who sees it. When a player changes team their marker is removed for everyone. A rebind is like any other key: Keybinds.Ping = { "MouseButton3" }, and players can change it in CONTROLS.

From your scripts

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

-- kind is "Spot" or "Enemy"
XSF.Pinged:Connect(function(player, position, kind)
	print(player.Name, "pinged", kind, "at", position)
end)

-- clear everyone's markers at the end of a round
for _, p in ipairs(game.Players:GetPlayers()) do
	XSF.ClearPing(p)
end

Restyle the marker with an XSF_Pings template, see Editing XSF's screens.

Phone button layout #

Players on phones and tablets can rearrange every on screen button, like the HUD editors in PUBG Mobile and Fortnite. Open Settings > MOBILE > Move, resize and hide buttons. It also works with a mouse in Studio, so you can try it without a phone.

• Drag a button to move it. It snaps to half a percent of the screen so rows line up.
• Tap a button to select it, then use the bar at the top: SMALLER and BIGGER (50% to 250%), TURN LEFT and TURN RIGHT (15 degrees at a time), HIDE or SHOW, and RESET (that button back to where XSF puts it).
• Pinch with two fingers to resize the selected button.
• RESET ALL puts every button back. CANCEL leaves without keeping anything. SAVE keeps it.

The layout is saved with the player's settings, so it follows them to every server and every XSF game. It's applied once when it changes, never every frame, so it costs nothing while playing. A button nobody moved stays exactly where XSF puts it, so a new XSF version can still improve the default layout for those.

The buttons: FIRE (also looks while held), AIM, + and - (range, on guns with zero steps), RELOAD, JUMP (vaults in front of a ledge), CROUCH (hold for prone), SPRINT, SWAP, GEAR, PING, L and R (lean), MODE (fire mode), MENU (settings), KIT (loadout), DROP and LOOK (inspect). The hotbar stays on screen too. Each one can also be hidden with its own switch further down the MOBILE tab.

Phone extras

For you: Mobile.AutoFire = false or Mobile.Gyro = false in GameConfig takes those options away (competitive games often turn auto fire off). The HUD and buttons stay clear of notches and rounded corners (Roblox safe areas).

Restyle the buttons with an XSF_Touch template holding a hidden Button, see Editing XSF's screens.

Controllers and the weapon wheel #

Weapon wheel

Tap RB to switch to the next weapon on your hotbar, as before. Hold RB for a moment (0.28 seconds) and a wheel opens with everything you carry, hotbar and backpack. Point at a weapon with the right stick and let go of RB to take it out. Let go without pointing anywhere new and you keep what you had. On keyboard and mouse you can bind it too (Keybinds.WeaponWheel) and point with the mouse.

Your weapon stays in your hands while the wheel is open but you can't shoot, and the wheel won't open while you're downed, in a menu, or carrying fewer than two weapons. With many weapons the ring grows so the pictures never overlap.

Button pictures and menus

• The CONTROLS tab and the hints in XSF's menus show the real button pictures for the player's controller (Xbox or PlayStation), not text.
• In menus the selected button gets a clear focus ring. LB and RB change tabs in the settings menu and slots in the loadout screen. B steps back, and closes from the tab list.
• D-pad left and right change the value of the selected row (switches, choices, sliders).

Aim assist

Two parts, both controller only. Mouse and touch are never affected. Slowdown: looking slows while an enemy is close to the barrel. Pull: while you move the stick, the view eases gently toward that enemy. It never snaps or locks on, and it does nothing if you don't touch the stick. Players scale both with Settings > CAMERA > Controller aim assist (0 turns it off for them). You tune it with AimAssist in GameConfig, see AimAssist.

Settings in the top bar

On every device there's a round XSF button in Roblox's top bar, right after Roblox's own buttons, that opens the settings menu. It never covers the Roblox menu or chat buttons and moves when they do. On PC in first person, hold Left Alt to free the cursor first, same as for Roblox's own buttons. UI.TopbarButton = false removes it.

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.3.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.

And on single parts of the gun:

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.

If your parts have other names, give them an XSF_SkinRole attribute instead of renaming them. To paint only some parts (a gun where the sights, rails or a scope should never change colour), set XSF_SkinOnlyTagged = true on the model and tag just the parts that should take the skin.

Normally a skin replaces a part's look completely: its TextureID is cleared and any SurfaceAppearance is removed, so XSF's plain colours and patterns come out clean. If your gun has its own textures you want to keep (wear, engraving, a PBR finish), set XSF_SkinKeep = true on the model. Then:

• A part with a SurfaceAppearance keeps it, and the skin's colour tints it (its Color is set). The material stays as you made it.
• A MeshPart with a TextureID keeps it, and the skin colour shows only where the texture is see through.
• Pattern skins (camo and so on) lie on top as textures, over your own.
• Parts with no texture of their own are painted as normal.

local gun = game.Selection:Get()[1]
gun:SetAttribute("XSF_SkinKeep", true)        -- keep its textures under skins
gun:SetAttribute("XSF_SkinOnlyTagged", true)  -- only paint the parts tagged below
gun.Receiver:SetAttribute("XSF_SkinRole", "Body")
gun.Stock:SetAttribute("XSF_SkinRole", "Furniture")
gun.Magazine:SetAttribute("XSF_SkinRole", "Mag")
gun.RearSight:SetAttribute("XSF_IronSight", true)
gun.RearSight:SetAttribute("XSF_Fold", 90)     -- flips down flat under an optic

Use the part names of your own model. Attributes save with the model, so set them once.

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 turned on (it is off by default since 2.3), 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. The STATS bars show the gun's real numbers measured against every gun in your game (damage, fire rate, range, bullet speed, recoil control, stability and aim speed), so players can compare guns at a glance. Hovering an option shows exactly what it changes: the part it adds turns green, the part it takes away red, and the number turns into the change in percent. Zoom, suppression, subsonic ammo, wall penetration and armour effects are listed under the bars.

• 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.

Graphics modes

The Balanced and Performance graphics modes cut particles, and Performance also drops brass and muzzle smoke and keeps fewer bullet holes. Auto picks the mode for each player's device. See Graphics modes.

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. Arm is how far it
-- flies before it can go off (closer, only the direct hit hurts). 0 means it
-- goes off on anything, so firing at your own feet hurts you
Projectile = { Speed = 45, MaxSpeed = 110, Ignite = 0.12, Burn = 0.7, Drop = 0.12, Life = 5,
	Arm = 0, 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 } },

Scope zoom

Variable scopes zoom in and out while you aim: mouse wheel up zooms in and wheel down zooms out. There are no keys by default; bind ZoomIn and ZoomOut in Keybinds or the settings menu, for controllers too. The scope readout shows the magnification next to ZERO and RANGE. Aiming sensitivity follows the zoom like it does for every sight. When you aren't aiming, the wheel changes weapon as before.

The scope picture keeps the same size on screen at every step: your eye moves along the tube as you zoom, like a real second focal plane scope. Give your own scopes steps with Zoom, a list of fields of view from wide to narrow. On a sight attachment it goes in its entry in Shared.Attachments; on a gun with its own scope it's Handling.Zoom in the Config. Aiming starts at the step closest to AimFov. Only add steps narrower than AimFov. A wider step would need your eye closer to the sight than it can go, so the scope picture shrinks and the tube shows around it.

Handling = { AimFov = 30, Zoom = { 30, 20, 13 }, Scoped = true, ScopeFill = 0.82 },

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. Your own guns can keep their own textures under a skin and choose which parts are painted, see Skins on your gun. 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

By default (since 2.3) every player has every skin. Turn Customization.Ownership.Skins on and players only have the skins you give them. 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 every player can use every attachment and skin. Turn ownership on when you want players to only get what 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 = {
	-- everything free for everyone (the default)
	Ownership = { Attachments = false, Skins = false },

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

	-- players only get what you give them
	-- Ownership = { Attachments = true, Skins = true },

	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.