hakowork/rojo
3
0
Fork 0
mirror of https://github.com/rojo-rbx/rojo.git synced 2026-10-25 13:31:37 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

rules

Browse source
This commit is contained in:
Joe 2026-02-02 12:08:47 -06:00
parent a9b4f8e83b
commit e6efc04756
8494 changed files with 495610 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

156
.cursor/rules/roblox/resources/battle-royale/building-system.md Normal file
View file

@ -0,0 +1,156 @@
---
title: Building system
comments:
description: Explains the process of creating a building system in the Battle Royale kit.
prev: /resources/battle-royale/pickup-system
next: /resources/battle-royale/minimap-system
---
Roblox Battle Royale features a building system that lets users build their own structures to reach higher ground for a better shooting angle, or to provide cover during battle. Using a menu, the user can select from a number of different tile types and place them in the world.
<img
alt="Building Example"
src="../../assets/resources/battle-royale/building-system/Battle-Royale-Building-View.jpeg"
width="100%" />
To maintain an orderly and structured system:
- Each tile must connect to another existing tile or to the ground.
- Place all building tiles within a grid coordinated with the 3D world so that tiles connect properly and do not overlap.
## Tile composition
In order for users to build new tiles quickly and easily, the building system needs to understand which tiles are connected to each other and where new tiles can be placed on the grid.
Tiles use 3 components: the [visual asset](#asset) that is used as the tile object, information about the [space the tile occupies](#occupancy) in reference to other world objects, and the [connection points](#connectivity) of a tile which allow additional tiles to connect to available edges.
### Asset
An asset is a `Class.BasePart` (`Class.Part`, `Class.MeshPart`, etc.) placed in `ReplicatedStorage/BuildingSystem/Assets` representing what the tile looks like in the 3D world. This `Class.BasePart` must have two children:
- **ObjectType** — A `Class.StringValue` with a `Value` of the tile type name.
- **StartingRotation** — A `Class.NumberValue` with a `Value` of the tile's starting rotation when a user places it in the world.
### Occupancy
Ensuring that a tile occupies the correct location in a grid system is important and can be done using a bitmask. A bitmask represents the physical space the tile type takes up within a basic section of world space, or cell. Each building system tile/object can occupy any number of faces of a grid cell (front, left, back, right, top, and bottom) and any number of octants in a grid cell. A user can only place a building system object in a cell if all the faces and octants that the object occupies are available in that cell. Occupancy for a building system object is defined as follows:
<table>
<thead>
<tr>
<th>Bit index</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td>0</td>
<td>Bottom face of cell</td>
</tr>
<tr>
<td>1</td>
<td>Top face of cell</td>
</tr>
<tr>
<td>2</td>
<td>Right face of cell</td>
</tr>
<tr>
<td>3</td>
<td>Back face of cell</td>
</tr>
<tr>
<td>4</td>
<td>Left face of cell</td>
</tr>
<tr>
<td>5</td>
<td>Front face of cell</td>
</tr>
<tr>
<td>6</td>
<td>**+X, –Y, +Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>7</td>
<td>**+X, +Y, +Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>8</td>
<td>**–X, –Y, +Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>9</td>
<td>**–X, +Y, +Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>10</td>
<td>**–X, –Y, –Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>11</td>
<td>**–X, +Y, –Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>12</td>
<td>**+X, –Y, –Z** octant of cell with origin at center of cell</td>
</tr>
<tr>
<td>13</td>
<td>**+X, +Y, –Z** octant of cell with origin at center of cell</td>
</tr>
</tbody>
</table>
### Connectivity
Tiles need to connect to each other to create a structure. You can use a bitmask which represents what portions of the cell's faces/edges the tile type touches. A building system tile/object's connectivity is represented by a series of connection points, bits, on the surface of a cell. They arrange in the following way on the faces of the cell:
<img
alt="Octant Cube Diagram"
src="../../assets/resources/battle-royale/building-system/Octant-Cube.png"
width="75%" />
A building system object is considered connected to another building system object in the grid if they share at least 2 connectivity points on the surface of a cell.
## Create new tile types
To create a new tile type:
1. Place the asset in `ReplicatedStorage/BuildingSystem/Assets`. Remember that it must contain `ObjectType` and `StartingRotation` children as defined above.
<img
alt="Battle Royale Weapon Example"
src="../../assets/resources/battle-royale/building-system/Battle-Royale-New-Tile-1.png"
width="320" />
2. Define the [Occupancy](#occupancy) and [Connectivity](#connectivity) for your new tile type in `ReplicatedStorage/BuildingSystem/Libraries/Grid/ObjectTypeConfigurations`:
<img
alt="Battle Royale Weapon Example"
src="../../assets/resources/battle-royale/building-system/Battle-Royale-New-Tile-2.png"
width="320" />
For example, the **Wall** tile type is expressed as follows:
```lua
ObjectTypeConfigurations.Wall = {
ASSET_OFFSET_FROM_CENTER = Vector3.new(0, 0, -CELL_DIMENSIONS.Z / 2),
CONNECTIVITY = 0xFF8000, -- 0b 111 111 111 000 000 000 000 000
OCCUPANCY = 0x20, -- 0b 00 00 00 00 1 0 0 0 0 0
}
```
## Work with terrain
If you would like to create a map with free-form [terrain](../../parts/terrain.md) that lines up perfectly with the building system, we recommend that you use the **heightmap import** system as outlined in [Environmental Terrain](../../parts/terrain.md) and that you observe the following details:
- Terrain in Roblox is represented by a three dimensional array of voxels, each of which occupies a cube of 4×4×4 studs in the world. Because of this, Roblox Battle Royale uses a grid cell size of 20×16×20 studs, with wall tiles that are 20×16×1 studs and floor/ceiling tiles that are 20×1×20 studs in size. This allows building tiles and terrain to line up properly.
- Each pixel in your heightmap image should represent one terrain voxel in the **X/Z** plane, so a 5×5 area in pixels represents one building system grid cell that occupies a 20×20 stud area.
- In your heightmap image, make sure the red channel or grey channel value for each pixel is divisible by the height of your building system grid cell so that the floor tiles sit nicely on top of the terrain.
- When you import your heightmap, set:
```lua
Position (X, Y, Z) = 0, 0, 0
Size (X, Y, Z) = heightmap_width × 4, 256, heightmap_length × 4
```

35
.cursor/rules/roblox/resources/battle-royale/core-scripts.md Normal file
View file

@ -0,0 +1,35 @@
---
title: Core scripts
comments:
description: Explains the two scripts responsible for the Battle Royale gameplay loop.
prev: /resources/battle-royale/run-the-game
next: /resources/battle-royale/pickup-system
---
The core game loop in Roblox Battle Royale is generally handled by two scripts, specifically `ServerScriptService/Server` on the server and `StarterPlayer/StarterPlayerScripts/Client` on the client.
## Initial setup
The `ReplicatedFirst/InitialSetup` script configures a few engine-level systems — built-in UI, chat, etc. — and ensures that the client loads the assets referenced in `ReplicatedFirst/Configurations/AssetPreloads` before proceeding.
## Game stages
The initialization and updating of specific systems is done differently depending on the current stage of the experience. Most of these cases are handled by `ServerScriptService/Core/GameStageHandler` on the server and `ReplicatedStorage/Core/StageManager` on the client. When a stage is requested, a module of the same name is required and various setup functions called on it. If there is already a module handling the current stage, shutdown functions are called on it prior to the new stage handler being initialized.
## Places/server roles
Within `ReplicatedFirst/Configurations/MainConfiguration`, different gameplay modes are organized into lists of stages to be executed.
```lua
local _roleStages = {
Lobby = {"Lobby"},
Queue = {"Queue"},
Gameplay = {"Waiting", "Gameplay", "EndGame"},
}
```
There are 3 different roles that a place can have:
- **Lobby** — Initial place where options like game mode are selected.
- **Queue** — Where a cohort of players gather for a particular game mode, building and fighting while waiting for the configured number of minimum players. Once the minimum numbers of players have arrived, a countdown will start, currently configured for 3:00 minutes, at the end of which gameplay will be initiated.
- **Gameplay** — The place where skydiving takes place and the game is played until completion.

39
.cursor/rules/roblox/resources/battle-royale/index.md Normal file
View file

@ -0,0 +1,39 @@
---
title: Battle Royale
comments:
description: Battle Royale is an example game-kit with instructions on specific gameplay implementations.
next: /resources/battle-royale/installation-and-setup
---
<Alert severity="warning">
Processes and features may have changed since the writing of this documentation. Refer to the appropriate feature documentation for up-to-date information on any features and workflows.
The content of this project and documentation can be used under Roblox's [Limited Use License](../../resources/limited-use-license.md).
</Alert>
**Roblox Battle Royale** is a game kit built by internal Roblox developers consisting of multiplayer battles on a large island with destructible buildings, a variety of vehicles and weapons, and interesting areas to explore. The default game loop is simple: join a match, skydive onto the island, stay out of the storm, and survive until you are the last person standing. Players can also build their own structures by laying down building tiles. This project is [available to join](https://www.roblox.com/games/5158731546/Roblox-Battle-Royale) as a public experience.
<img
alt="Drop onto a region in a classic battle royale experience."
src="../../assets/resources/battle-royale/introduction/Battle-Royale-Slide-B.jpeg"
width="80%" />
## Features
At a high level, Roblox Battle Royale contains the following:
- Code for 3rd-person cameras.
- A robust and customizable ranged [weapon system](../../resources/weapons-kit.md), including 9 different weapons preconfigured.
- A building system.
- A destruction system.
All of these systems are supported on a wide range of hardware, screen sizes, and game controllers, from mobile phones to Xbox to high-end desktop PCs. The code is designed to be performant and easy to read so anyone can learn how to build a game like this.
## Play modes
There are 4 play modes included in this project:
- **Last One Standing** — Traditional battle royale; players who are eliminated are removed from the match and the last person to survive wins.
- **Solo Deathmatch** — Players will respawn after dying; the player with the highest kill count wins.
- **Team Deathmatch** — Two teams of players attempt to eliminate the other team; the team with players still alive at the end wins.
- **Free Play** — Players can enter the game and play around with the building system, weapons, and vehicles.

313
.cursor/rules/roblox/resources/battle-royale/installation-and-setup.md Normal file
View file

@ -0,0 +1,313 @@
---
title: Installation and setup
description: Explains the installation and setup details for the Battle Royale game kit.
prev: /resources/battle-royale
next: /resources/battle-royale/run-the-game
---
To setup the Battle Royale experience, you must download [Studio](../../studio/setup.md) and the project [reference files](#reference-files).
Additional configuration of the [place IDs](#copy-and-paste-place-ids), [server](#adjust-server-fill), and [publishing](#publish-additional-places) settings are also required before continuing on to [running the game](../../resources/battle-royale/run-the-game.md).
## Reference files
[RobloxBattleRoyale.zip](../../assets/resources/battle-royale/installation-and-setup/RobloxBattleRoyale.zip) consists of easily accessible `.rbxl` files which you can open in Roblox Studio and experiment with immediately.
<table>
<thead>
<tr>
<th>Name</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>Lobby.rbxl</td>
<td>Entrance lobby where players choose the game mode.</td>
</tr>
<tr>
<td>Gameplay.rbxl</td>
<td>Where the battle match takes place.</td>
</tr>
<tr>
<td>Queue.rbxl</td>
<td>Queue place where players gather before being teleported to battle map.</td>
</tr>
</tbody>
</table>
## Create a new game
Roblox Battle Royale must be structured as a game with six unique places. To begin:
1. Open `Lobby.rbxl` in Roblox Studio.
<img
alt="Lobby View."
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Lobby-View.jpeg"
width="80%" />
2. Select **File** → **Publish As…** to open the publishing window.
3. Near the bottom of the window, click **Create new experience**.
4. Type in **Lobby** for the place name.
<img
alt="Set Lobby Name"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Lobby-Set-Name.png"
width="80%" />
5. For the **Creator** field, select "Me" to publish the place to your personal account, or select a group.
6. When ready, click the **Create** button.
## Add additional places
Once the lobby place is published, you'll need to add **five additional places** to the game:
1. If it's not already visible, open the **Asset Manager** window.
2. Double-click the **Places** folder.
<img
alt="Select Places"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-AM-Select-Places-1.png"
width="80%" />
3. Right-click in any empty region of the window (not over a place name/tile) and select **Add New Place**. Repeat this a total of five times so that you have six places.
4. Right-click each of the **new** places, select **Rename**, and name them as follows:
<img
alt="Battle royale Place Names"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Place-Names.png"
width="80%" />
5. Publish the game again (**File** → **Publish to Roblox**).
## Copy and paste place IDs
Each place must be cross-associated so that players can teleport from the lobby to various play mode queues and vice-versa. To achieve this, you'll need to gather the place IDs of the places you created above.
1. In the **Asset Manager** window, right-click **Lobby** and select **Copy ID to Clipboard**.
<img
alt="Copy Lobby ID"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Lobby-Copy-ID.png"
width="80%" />
2. If it's not already visible, open the **Explorer** window.
3. Open the **MainConfiguration** script within **ReplicatedFirst** → **Configurations**.
<img
alt="MainConfiguration Script"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Place-MainConfiguration.png"
width="80%" />
4. Locate the `_places` table and paste the copied ID from step #1 as the value of the `lobby` key.
```lua title="Lobby-MainConfiguration"
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local RunService = game:GetService("RunService")
local Players = game:GetService("Players")
local isServer = RunService:IsServer()
local ConfigEvent = nil
local _placeOverrides = {}
local _overrides = {}
---
-- List of named places in the game
local _places = {
lobby = 0123456789,
gameplay_development = 0,
queue_default = 0,
queue_deathmatch = 0,
queue_teamDeathmatch = 0,
queue_freePlay = 0
}
---
```
5. Repeat the **Copy ID to Clipboard** process for the other five places and paste them into the associated `_places` table key value.
<table>
<thead>
<tr>
<th>Place</th>
<th>Table key</th>
</tr>
</thead>
<tbody>
<tr>
<td>Lobby</td>
<td>lobby</td>
</tr>
<tr>
<td>Gameplay</td>
<td>gameplay_development</td>
</tr>
<tr>
<td>Queue (Default)</td>
<td>queue_default</td>
</tr>
<tr>
<td>Queue (Deathmatch)</td>
<td>queue_deathmatch</td>
</tr>
<tr>
<td>Queue (Team Deathmatch)</td>
<td>queue_teamDeathmatch</td>
</tr>
<tr>
<td>Queue (Free Play)</td>
<td>queue_freePlay</td>
</tr>
</tbody>
</table>
```lua
-- List of named places in the game
local _places = {
lobby = 0123456789,
gameplay_development = 0987654321,
queue_default = 0123459876,
queue_deathmatch = 0987651234,
queue_teamDeathmatch = 0132457689,
queue_freePlay = 0678912345
}
```
6. Publish the game again (**File** → **Publish to Roblox**).
## Adjust server fill
By default, Roblox balances players/servers for an optimal social gameplay experience, but a battle royale should allow for bigger and more intense battles. To achieve this:
1. Open Studio's **File** ⟩ **Experience Settings** window.
2. Select the **Places** tab.
3. For each of the six places, click the button and select **Edit**.
<img
alt="Edit Place Settings"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Edit-Place.png"
width="80%" />
4. For **Server Fill**, select **Maximum**.
<img
alt="Set Server Fill to Maximum."
src="../../assets/resources/battle-royale/installation-and-setup/Place-Server-Fill-Maximum.png"
width="80%" />
5. Click **Save** at the bottom of the window.
## Publish additional places
Now you'll need to open the remaining `.rbxl` files from the downloaded bundle, modify their `_places` tables, and publish them.
### Copy places table
1. Refer to the `_places` table in the lobby's **MainConfiguration** script:
```lua
--------------------------------------
-- List of named places in the game
local _places = {
lobby = 0123456789,
gameplay_development = 0987654321,
queue_default = 0123459876,
queue_deathmatch = 0987651234,
queue_teamDeathmatch = 0132457689,
queue_freePlay = 0678912345
}
--------------------------------------
```
1. Select the **entire table** and copy it to the clipboard with <kbd>Ctrl</kbd><kbd>C</kbd> (<kbd>⌘</kbd><kbd>C</kbd> on Mac).
2. Close the lobby place by clicking the X in its tab.
<img
alt="Close Lobby Tab."
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Lobby-Close.png"
width="80%" />
### Replace tables
1. Open the `Gameplay.rbxl` file.
2. Open its **MainConfiguration** script within **ReplicatedFirst** → **Configurations**.
<img
alt="MainConfiguration Script"
src="../../assets/resources/battle-royale/installation-and-setup//Battle-Royale-Place-MainConfiguration.png"
width="80%" />
3. Paste the `_places` table you copied above over the existing `_places` table (<kbd>Ctrl</kbd><kbd>V</kbd>; <kbd>⌘</kbd><kbd>V</kbd>) so that each place's tables are identical.
```lua
--------------------------------------
-- List of named places in the game
local _places = {
lobby = 0123456789,
gameplay_development = 0987654321,
queue_default = 0123459876,
queue_deathmatch = 0987651234,
queue_teamDeathmatch = 0132457689,
queue_freePlay = 0678912345
}
--------------------------------------
```
4. Select **File** → **Publish As…** to open the publishing window.
5. Near the bottom of the window, click **Update existing experience…**.
6. Locate and click the **Lobby** place that you published earlier.
7. On the next screen, you should see a list of the places you added earlier. From the list, select the **Gameplay** place and click the **Overwrite** button.
<img
alt="Overwrite Existing Place"
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Place-Overwrite.png"
width="80%" />
8. Once the place is published, close it by clicking the X in its tab.
<img
alt="Close the place tab."
src="../../assets/resources/battle-royale/installation-and-setup/Battle-Royale-Gameplay-Close.png"
width="80%" />
9. Open the `Queue.rbxl` file and repeat this process, using **File** → **Publish As…** to publish it to all four queue places. Essentially, `Queue.rbxl` should be published to the **Queue (Default)**, **Queue (Deathmatch)**, **Queue (Team Deathmatch)**, and **Queue (Free Play)** slots.
<table>
<thead>
<tr>
<th>File</th>
<th>Publish Slot</th>
</tr>
</thead>
<tbody>
<tr>
<td>Lobby.rbxl</td>
<td>Lobby</td>
</tr>
<tr>
<td>Gameplay.rbxl</td>
<td>Gameplay</td>
</tr>
<tr>
<td>Queue.rbxl</td>
<td>Queue (Default)</td>
</tr>
<tr>
<td>Queue.rbxl</td>
<td>Queue (Deathmatch)</td>
</tr>
<tr>
<td>Queue.rbxl</td>
<td>Queue (Team Deathmatch)</td>
</tr>
<tr>
<td>Queue.rbxl</td>
<td>Queue (Free Play)</td>
</tr>
</tbody>
</table>

92
.cursor/rules/roblox/resources/battle-royale/minimap-system.md Normal file
View file

@ -0,0 +1,92 @@
---
title: Minimap system
comments:
description: Explains the minimap implementation details for the Battle Royale game kit.
prev: /resources/battle-royale/building-system
next: /resources/battle-royale/the-storm
---
The minimap shows a subset of the world map at the top-right corner of the player's screen. It also displays an indicator to show where you are, where the delivery vehicle is, and where your teammates are when playing in team mode. Lastly, it shows the current state of the [storm](../../resources/battle-royale/the-storm.md) and where the storm will be next so players know how to avoid it.
<img
alt="Minimap example"
src="../../assets/resources/battle-royale/minimap-system/Battle-Royale-Minimap.jpeg"
width="100%" />
Players can toggle between the minimap and world map by pressing <kbd>M</kbd> on a keyboard, pressing up on a gamepad's DPad, or by touching the minimap on touchscreens.
## Structure
The minimap is simply an `Class.ImageLabel` that displays a previously-generated image and uses `Class.CollectionService` to show the position of objects with specific tags. All of the UI objects used for the minimap are inside of the minimap screen GUI located in `ReplicatedStorage/Assets/GuiObjects`.
<img
alt="Minimap Objects"
src="../../assets/resources/battle-royale/minimap-system/Battle-Royale-Minimap-Objects.png"
width="320" />
## Add indicators
To add new indicators that show up on the minimap, complete these steps:
1. Through the [Tags](../../studio/properties.md#instance-tags) section of its properties, apply a custom tag to the workspace object that you want to show up on the minimap.
2. Add the `Class.ImageLabel` you want to represent the object as a child of `ReplicatedStorage/Assets/GuiObjects/minimap/mapframe` and give it a unique name.
3. Inside of `ReplicatedStorage/Libraries/Guis/MinimapGui`, locate the `MinimapGui.start()` function. Inside it, register the tag as shown below, where tag is the tag you registered in step #1 and `indicatorLabel` is the name of the `Class.ImageLabel` you added in step #2.
```lua
function MinimapGui.start(teamDividingAngle)
while not _setupFinished do
task.wait()
end
MinimapGui.addMapTag("DeliveryVehicle", "Bus")
MinimapGui.addMapTag(Util._clientFocusTag, "LocalPlayerLocation")
MinimapGui.addMapTag("Player")
MinimapGui.addMapTag("Vehicle", "VehicleLocation")
MinimapGui.addMapTag(tag, indicatorLabel)
```
## Customize the minimap
To customize the minimap or use the minimap system with your own map and minimap image, you can change these values in `ReplicatedFirst/Configurations/MainConfiguration`:
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`map_size`</td>
<td>The size of one edge of your map in studs. Note the minimap assumes your map is square and that the map center is located at this world point: `Vector3.new(map_size, 0, map_size`).</td>
</tr>
<tr>
<td>`minimap_width`</td>
<td>Width in `Datatype.UDim` scale of the minimap on the player's screen.</td>
</tr>
<tr>
<td>`minimap_height`</td>
<td>Height in `Datatype.UDim` scale of the minimap on the player's screen.</td>
</tr>
<tr>
<td>`minimap_zoom`</td>
<td>Amount the minimap is zoomed in on the world map.</td>
</tr>
<tr>
<td>`worldmap_width`</td>
<td>Width in `Datatype.UDim` scale of the world map on the player's screen.</td>
</tr>
<tr>
<td>`worldmap_height`</td>
<td>Width in `Datatype.UDim` scale of the world map on the player's screen.</td>
</tr>
<tr>
<td>`worldmap_zoom`</td>
<td>Amount the world map is zoomed in on the worldmap.</td>
</tr>
</tbody>
</table>

127
.cursor/rules/roblox/resources/battle-royale/pickup-system.md Normal file
View file

@ -0,0 +1,127 @@
---
title: Pickup system
comments:
description: Explains the pickup system for the Battle Royale game kit.
prev: /resources/battle-royale/core-scripts
next: /resources/battle-royale/building-system
---
The Roblox Battle Royale **pickup system** lets players pick up different kinds of objects, although it's currently only used for weapon pickups. In game, weapons are spawned around the game map and — when players get close enough — an on-screen key/action/button prompt appears along with the weapon name and description.
<img
alt="Battle Royale Weapon Example"
src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Weapon-Pickup.jpg"
width="100%" />
<Alert severity="info">
Roblox Battle Royale uses the [Weapons Kit](../../resources/weapons-kit.md), so please consult its documentation for details and customization options.
</Alert>
## Structure
There are several important folders related to the pickup system. Make sure that these folders are set up correctly in your project:
- `Workspace/PickupSpawners` — Contains pickup spawner `Class.Part|Parts` which tell the system where to place visual pickup `Class.Model|Models` (see the next point). Note that these spawners are **not required** to be in this folder since the system looks for parts tagged with the **PickupSpawner** tag instead of the folder path.
<img
alt="Pickup Spawners"
src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-PickupSpawners.png"
width="320" />
<Alert severity="info">
Pickup spawners can be placed at any physical location in the game, but they will choose a weapon **randomly** from `ReplicatedStorage/Assets/Weapons` and use the name-matched pickup model as a visual representation.
</Alert>
- `ReplicatedStorage/Assets/Weapons` — Contains the weapons (functional `Class.Tool|Tools`) that the pickup system grants when a weapon pickup is activated.
<img
alt="Battle Royale Items"
src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Weapons.png"
width="320" />
- `ReplicatedStorage/Assets/Pickups` — Contains the pickup `Class.Model|Models` that the system will place at pickup spawners in the game world. **These should be visual models only**, not functional weapon Tools.
<img
alt="Battle Royale Pickups"
src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Pickups.png"
width="320" />
## Add new pickups
As noted above, pickups require both a functional `Class.Tool` and a visual `Class.Model` that will be spawned in the game world.
### Tool
1. Create a `Class.Tool` and give it a unique name. You can create new weapons based upon those in the [Weapons Kit](../../resources/weapons-kit.md) or take tools from the [Toolbox](../../projects/assets/toolbox.md).
2. Place the `Class.Tool` in `ReplicatedStorage/Assets/Weapons`.
<img
alt="Battle Royale New Weapon"
src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-New-Weapon.png"
width="320" />
### Model
1. Create a `Class.Model` for the visual pickup and give it the **same name** as you gave the `Class.Tool`.
2. Through the [Tags](../../studio/properties.md#instance-tags) section of its properties, apply the following tags to the model:
- **Action**
- **Pickup**
- **WeaponPickup**
- **WeaponSystemIgnore**
- One of the rarity tags as outlined in [Rarity](#rarity).
3. Place the model in `ReplicatedStorage/Assets/Pickups`.
<img
alt="Battle Royale New Pickup"
src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-New-Pickup.png"
width="320" />
### Rarity
Pickup rarity is not defined by any mathematical formula, but you can associate an on-screen GUI like those pictured below to suggest an item's rarity.
1. Open the `ReplicatedFirst/Configurations/RarityConfiguration` script. This script contains tables for each rarity category, each of which includes a color value (`Color`) for the pickup's particle effect and an asset ID (`Image`) for the on-screen GUI background. For each GUI:
- The item name will appear as the model/weapon name.
- The description will appear as the rarity name (such as **Epic**) plus **Item**.
The default rarities are as follows, but feel free to define your own.
<table>
<thead>
<tr>
<th>Rarity</th>
<th>GUI</th>
</tr>
</thead>
<tbody>
<tr>
<td>Common</td>
<td><img src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Item-Common.png" width="45%" /></td>
</tr>
<tr>
<td>Uncommon</td>
<td><img src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Item-Uncommon.png" width="45%" /></td>
</tr>
<tr>
<td>Rare</td>
<td><img src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Item-Rare.png" width="45%" /></td>
</tr>
<tr>
<td>Epic</td>
<td><img src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Item-Epic.png" width="45%" /></td>
</tr>
<tr>
<td>Legendary</td>
<td><img src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Item-Legendary.png" width="45%" /></td>
</tr>
<tr>
<td>Special</td>
<td><img src="../../assets/resources/battle-royale/pickup-system/Battle-Royale-Item-Special.png" width="45%" /></td>
</tr>
</tbody>
</table>
2. For the pickup `Class.Model` you created previously (located in `ReplicatedStorage/Assets/Pickups`), assign one of the tags you've defined in the `RarityConfiguration` script.

273
.cursor/rules/roblox/resources/battle-royale/run-the-game.md Normal file
View file

@ -0,0 +1,273 @@
---
title: Run the game
comments:
description: Explains the playtest instructions for the Battle Royale game kit.
prev: /resources/battle-royale/installation-and-setup
next: /resources/battle-royale/core-scripts
---
Once all six places are published, you're ready to playtest.
1. If you have any places currently open in Studio, close them.
2. Make sure the Recent button is selected in the left column.
<img
alt="Lobby View."
src="../../assets/resources/battle-royale/running-the-game/Studio-Recent-Games.png"
width="151" />
3. Hover your mouse over the Lobby icon, click the button, and select Open place page from the context menu.
<GridContainer numColumns="2">
<img src="../../assets/resources/battle-royale/running-the-game/Battle-Royale-Lobby-Open-Place-1.png" width="80%" />
<img src="../../assets/resources/battle-royale/running-the-game/Battle-Royale-Lobby-Open-Place-2.png" width="80%" />
</GridContainer>
4. From the target page, click the large play button to test your experience.
## Game controls
The following are the various keyboard and mouse, mobile, and gamepad controls set for this project. See [Inputs](../../input/index.md) for more information on customizing your own controls.
### General controls
<table>
<thead>
<tr>
<th>Action</th>
<th>Keyboard and mouse controls</th>
<th>Mobile controls</th>
<th>Controller controls</th>
</tr>
</thead>
<tbody>
<tr>
<td>Move forward</td>
<td><kbd>W</kbd> or <kbd>↑</kbd></td>
<td>Move thumbstick forward</td>
<td>Move left analog stick forward</td>
</tr>
<tr>
<td>Move backward</td>
<td><kbd>S</kbd> or <kbd>↓</kbd></td>
<td>Move thumbstick back</td>
<td>Move left analog stick back</td>
</tr>
<tr>
<td>Move (strafe) left</td>
<td><kbd>A</kbd> or <kbd>←</kbd></td>
<td>Move thumbstick left</td>
<td>Move left analog stick left</td>
</tr>
<tr>
<td>Move (strafe) right</td>
<td><kbd>D</kbd> or <kbd>→</kbd></td>
<td>Move thumbstick right</td>
<td>Move left analog stick right</td>
</tr>
<tr>
<td>Look up</td>
<td>Move mouse forward</td>
<td>Drag up on main screen area</td>
<td>Move right analog stick forward</td>
</tr>
<tr>
<td>Look down</td>
<td>Move mouse backward</td>
<td>Drag down on main screen area</td>
<td>Move right analog stick back</td>
</tr>
<tr>
<td>Turn left</td>
<td>Move mouse left</td>
<td>Drag left on main screen area</td>
<td>Move right analog stick left</td>
</tr>
<tr>
<td>Turn right</td>
<td>Move mouse right</td>
<td>Drag right on main screen area</td>
<td>Move right analog stick right</td>
</tr>
<tr>
<td>Jump</td>
<td><kbd>Spacebar</kbd></td>
<td>Tap on-screen jump button</td>
<td><kbd>A</kbd></td>
</tr>
<tr>
<td>Run</td>
<td><kbd>Shift</kbd></td>
<td>Push thumbstick fully in desired direction</td>
<td>Push left analog stick fully in desired direction</td>
</tr>
<tr>
<td>Shoot</td>
<td>Click left mouse button</td>
<td>Tap on-screen fire button or main screen area</td>
<td>Right trigger</td>
</tr>
<tr>
<td>Shoot full auto</td>
<td>Hold left mouse button</td>
<td>Double-tap main screen area</td>
<td>Hold right trigger</td>
</tr>
<tr>
<td>Aim</td>
<td>Hold right mouse button</td>
<td>Tap on-screen aim button</td>
<td>Left trigger</td>
</tr>
<tr>
<td>Select weapon</td>
<td><kbd>1</kbd>–<kbd>9</kbd></td>
<td>Tap on-screen weapon button</td>
<td>Left or right bumper</td>
</tr>
<tr>
<td>Skydive</td>
<td><kbd>Spacebar</kbd></td>
<td>Tap main screen area</td>
<td><kbd>A</kbd></td>
</tr>
<tr>
<td>Take item</td>
<td><kbd>E</kbd></td>
<td>Tap on item</td>
<td><kbd>X</kbd></td>
</tr>
<tr>
<td>Open door</td>
<td><kbd>E</kbd></td>
<td>Tap on-screen door button</td>
<td><kbd>X</kbd></td>
</tr>
<tr>
<td>Toggle minimap</td>
<td><kbd>M</kbd></td>
<td>Tap on-screen minimap display</td>
<td>Press up on DPad</td>
</tr>
<tr>
<td>Show/hide leaderboard</td>
<td><kbd>Tab</kbd></td>
<td>Tap on-screen player count display</td>
<td>Press down on DPad</td>
</tr>
</tbody>
</table>
### Building controls
<table>
<thead>
<tr>
<th>Action</th>
<th>Keyboard and mouse controls</th>
<th>Mobile controls</th>
<th>Controller controls</th>
</tr>
</thead>
<tbody>
<tr>
<td>Toggle build mode</td>
<td><kbd>Q</kbd></td>
<td>Tap on-screen toggle button</td>
<td><kbd>B</kbd></td>
</tr>
<tr>
<td>Select building tile</td>
<td><kbd>1</kbd>–<kbd>9</kbd></td>
<td>Tap on-screen tile button</td>
<td></td>
</tr>
<tr>
<td>Place building yile</td>
<td>Click left mouse button</td>
<td>Tap main screen area</td>
<td>Right trigger</td>
</tr>
<tr>
<td>Rotate building tile</td>
<td><kbd>R</kbd></td>
<td>Tap on-screen rotate button</td>
<td>Click right analog stick</td>
</tr>
<tr>
<td>Previous/next building tile</td>
<td>Click right mouse button</td>
<td>Tap on-screen previous/next arrow buttons</td>
<td>Left or right bumper</td>
</tr>
<tr>
<td>Wall tile</td>
<td><kbd>Z</kbd></td>
<td>Tap on-screen tile button</td>
<td></td>
</tr>
<tr>
<td>Floor tile</td>
<td><kbd>X</kbd></td>
<td>Tap on-screen tile button</td>
<td></td>
</tr>
<tr>
<td>Ramp tile</td>
<td><kbd>C</kbd></td>
<td>Tap on-screen tile button</td>
<td></td>
</tr>
</tbody>
</table>
### Ground vehicle controls
<table>
<thead>
<tr>
<th>Action</th>
<th>Keyboard and mouse controls</th>
<th>Mobile controls</th>
<th>Controller controls</th>
</tr>
</thead>
<tbody>
<tr>
<td>Accelerate / forward</td>
<td><kbd>W</kbd> or <kbd>↑</kbd></td>
<td>Jump button (changes visually)</td>
<td>Right trigger</td>
</tr>
<tr>
<td>Brake / reverse</td>
<td><kbd>S</kbd> or <kbd>↓</kbd></td>
<td>Smaller button to left of accelerate button</td>
<td>Left trigger</td>
</tr>
<tr>
<td>Turn left</td>
<td><kbd>A</kbd> or <kbd>←</kbd></td>
<td>Move thumbstick</td>
<td>Move left analog stick left</td>
</tr>
<tr>
<td>Turn right</td>
<td><kbd>D</kbd> or <kbd>→</kbd></td>
<td>Occurs at maximum turn</td>
<td>Move left analog stick right</td>
</tr>
<tr>
<td>E-Brake / drift</td>
<td><kbd>Spacebar</kbd></td>
<td>Button prompt above vehicle</td>
<td><kbd>X</kbd></td>
</tr>
<tr>
<td>Enter / exit / flip</td>
<td><kbd>E</kbd></td>
<td>Smaller button above accelerate button</td>
<td><kbd>Y</kbd></td>
</tr>
</tbody>
</table>

88
.cursor/rules/roblox/resources/battle-royale/the-storm.md Normal file
View file

@ -0,0 +1,88 @@
---
title: The storm
comments:
prev: /resources/battle-royale/minimap-system
description: Explains the implementation details for the storm feature in the Battle Royale game kit.
---
The **storm** is essentially a large cylindrical barrier that starts big and slowly gets smaller as the match goes on. Players will take damage when outside of the barrier's boundary — this forces them to get closer and closer to each other and helps matches end in a reasonable time.
<img
alt="The Storm Example"
src="../../assets/resources/battle-royale/the-storm/Battle-Royale-Storm.jpeg"
width="100%" />
## Structure
Due to the part size limit, it's not possible to make the storm one huge cylinder. Instead, the storm consists of many thin rectangular parts arranged around the barrier's edge, making it appear cylindrical. These parts dynamically resize based on the proximity of players, splitting or combining with neighboring parts to maintain a smooth appearance. This behavior is handled by:
- `ServerScriptService/Core/ShrinkingBarrier`
- `ReplicatedStorage/Core/ShrinkingBarrierVisualization`
## Customize the storm
Within `ReplicatedFirst/Configurations/MainConfiguration`, the following variables can be adjusted to customize the storm:
### Map offset
The default center of the storm is the center of the map, but you can change the `map_offset` value to force players toward another point as the storm boundary shrinks.
```lua
map_size = 2450 * 4,
map_offset = Vector3.new(4900, 0, 4900),
```
### Storm options
Lower down, the `storm` table contains configuration values which determine how the storm behaves during matches, such as its radius, timing, and how much it shrinks.
```lua
storm = {
radius = 6000,
time_before_start = 120,
debug_time_scale = 1,
number_of_stages = 10,
-- stage 0 (show starting circle with no transition)
{ transition_length = 0,
wait_length = 150,
damage = 1,
move_scale = 0,
shrinkage_factor = 0 },
```
<table>
<thead>
<tr>
<th>Variable</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`radius`</td>
<td>Starting radius of the storm.</td>
</tr>
<tr>
<td>`time_before_start`</td>
<td>Time before the storm first appears.</td>
</tr>
<tr>
<td>`debug_time_scale`</td>
<td>Debugging time scale, helpful for tuning the stages. Change this to something higher than 1 to carry out the storm's stages faster.</td>
</tr>
<tr>
<td>`number_of_stages`</td>
<td>Number of stages the storm has.</td>
</tr>
<tr>
<td>(stage tables)</td>
<td>Series of tables (one for each stage as defined by number_of_stages) containing these variables:<br /><br />
<ul /> - `transition_length` — Time in seconds for the storm to transition from its previous stage to this stage.<br /><br />
<ul /> - `wait_length` — Time in seconds for the storm to wait before transitioning to the next stage.<br /><br />
<ul /> - `damage` — Damage per second that players will take when they are outside of the storm barrier during this stage.<br /><br />
<ul /> - `move_scale` — Multiplier that allows the storm center to move more when transitioning to this stage. A value of 0 means the storm center will only move such that the entire storm in this stage will stay within the bounds of the storm of the previous stage.<br /><br />
<ul /> - `shrinkage_factor` — Fraction of the previous radius that is subtracted from the radius. For example, the radius at the end of stage 2 is 1000 and `shrinkage_factor` for stage 3 is 0.25, so the radius at the end of stage 3 will be 750 (`1000-(0.25*1000)`).</td>
</tr>
</tbody>
</table>