SkyWarsCore documentation

Setup guide

From an empty server to players in a game, in about a minute. Every step can also be done from the admin panel (/sw).

1. Install

Put SkyWarsCore-1.0.0.jar in plugins/.
Start the server. SkyWarsCore writes its files to plugins/SkyWarsCore/ and uses SQLite, so no database is needed.
Paste your licence key (from the BuiltByBit purchase message) into licence-key in plugins/SkyWarsCore/config.yml, then restart.

2. Quickstart

Join as an operator. You get a clickable [RUN /SW QUICKSTART] message (or type /sw quickstart). The menu has three choices:

Starter server: sets the lobby where you stand, generates starter maps one after another, and places mode NPCs and leaderboards. Pick a preset when it finishes and the server is playable.
Use my maps: opens the map wizard for maps you already have (step 3).
Network: writes network.yml for a lobby or game server and lists what to do next (step 6).

Presets set countdowns, rules and modes in one click:

Preset	What it does
Classic	The standard game
Competitive	Short countdowns, no fall protection, a shared middle
Casual	Longer countdowns and the calm event timeline
Ranked	No requeue or spectating, a shared middle

Run /sw doctor at any time. It lists anything that still needs attention, with the fix for each.

3. Maps

Install the starter maps

The download has six ready-made maps in starter-maps/. Copy the files to plugins/SkyWarsCore/exports/ and run /sw map import <file> for each one. Each map is on and ready straight away.

Generate maps

/sw > Generate a Map, or:

/sw map generate [theme] [islands | islandsxteam | clash] [name]

Examples: /sw map generate frost 12, /sw map generate classic 8x2 duos-frost (8 teams of 2), /sw map generate desert clash. Islands come with chests already tagged by tier. Generation runs off the server thread, so players keep playing while it builds.

Use your own maps

Load the map world (any world manager works) and stand in it.
Run /sw map create <name>. The world is copied to an edit copy and the setup hotbar appears.
Islands are found automatically. Spawns come from cages, beacons or island tops, and chests are tagged by distance from the centre. Each island glows in its own colour, and a checklist shows what was found.
Fix anything with the chest tool kit:

Slot	Tool	Use
1	Island Chest	Place or retag island chests. Shift places one on every island
2	Middle Chest	Place or retag middle chests. Shift retags every chest in the middle
3	Centre Chest	The best loot
4	Custom Tier	Any tier from the picker
5	Spawn	Add or remove spawns

Test game puts you in a one-player game on the map with a fast timeline.
/sw map save [note] saves the map. Every save is a version: /sw map versions <map> and /sw map rollback <map> <version> take you back.

Downloaded maps with glass cages built in are handled: the cages are removed at the drop and your cosmetic cages are used instead.

/sw map export <map> writes one file to plugins/SkyWarsCore/exports/. /sw map import <file> installs it on any server.

4. The lobby

Stand where players should appear and run /sw lobby set.
Run /sw designer (or /sw > Lobby) to place:
- Mode NPCs with live player counts (/sw designer npc <type> [mode]). Each NPC's skin and gear can be changed in the designer.
- Leaderboards, the top-three podium and trophy cases.
- A parkour course and the practice hub.
The lobby hotbar (Play, kits, cosmetics, profile and more) is set in hotbar.yml.

5. Make it yours

Modes: modes.yml. Add a mode with any team size; set islands, minimum players, loot tables, kits, perks, combat profile, votes and twists.
Loot: /sw loot opens the loot editor. Change items and weights in a menu, run the simulator to see what players will get, and share tables with share codes.
Kits: /kits admin builds a kit from your inventory, with icon, rarity, price and modes.
Events and twists: events.yml for the timeline (refills, Supply Drops, Final Showdown, Sky Collapse), twists.yml for the 22 twists.
Look: /sw appearance switches the menu theme, previews chest skins and rebuilds the resource pack. Menus can use item models, custom model data, ItemsAdder, Nexo or Oraxen items and font-image titles.
Text: every message is in lang/en_US.yml, every menu in menus/. Hex colours work on 1.16 and newer, and older clients get the nearest colour.

/sw reload applies changes without a restart.

6. Networks

SkyWarsCore runs on the lobby and on every game server; the proxy plugin routes players.

Point every server at one MySQL, MariaDB, PostgreSQL or MongoDB database with the same table-prefix (storage in config.yml).
Put SkyWarsCore-Proxy-Velocity or SkyWarsCore-Proxy-Bungee on the proxy.
In network.yml on each server set mode: network, a unique server-id and the role (lobby or game). Copy the same secret to every server and the proxy.
Optional: add Redis for instant server status across the network.
Restart. /sw doctor on each server says what is still missing.

Parties, queues, stats and cosmetics follow players across servers. /sw drain stops new games on a server so it can restart without cutting games short.

7. Bedrock players

Install Geyser and Floodgate. Bedrock players get forms instead of chest menus, and textures through Geyser mappings. Ranked can be cross-play or Java-only (competitive/ranked.yml).

8. Performance tips

Paper or one of its forks (Purpur, Leaf, Folia) is recommended over Spigot.
/sw perf shows what SkyWarsCore costs per feature, and warns staff when a tick goes over budget.
Install Advanced Slime Paper's world loader to load game worlds from memory. SkyWarsCore uses it automatically.
Game worlds are reset in place and kept loaded for the next game. warm: auto in game.yml sets how many are kept ready per map.

Troubleshooting

Problem	Fix
"No map can host this mode"	Generate or import a map, or turn the map on in `/sw` > Maps. `/sw doctor` lists maps it could not read
The plugin disables at start-up	The console says why. Usually the licence key is missing or for another product
Players can't join from the lobby on a network	The `secret` must be the same on every server and the proxy, and each `server-id` must be unique
Menus look plain on a resource-pack theme	The player declined the pack. `/sw appearance` > Pack shows who has it

Still stuck? Ask in our Discord: https://discord.gg/n3G52gTKHj

SkyWars for every server version from 1.7.10 to 26.3, in one jar. Fair loot, fast games, real progression, and a setup that takes about a minute.

Versions: 1.7.10, 1.8.8, 1.9 to 1.21.11, 26.x
Server software: Spigot, Paper, PaperSpigot, Purpur, Folia, Leaf
Java: 8 or newer, whatever your server version needs
Networks: standalone, or lobbies and game servers behind Velocity or BungeeCord
Support and updates: https://discord.gg/n3G52gTKHj

The setup guide walks through the first start, maps, the lobby and networks.

Requirements

What	Needed
Server	Spigot, Paper, Purpur, Folia or Leaf, 1.7.10 to 26.x
Java	The version your server already runs on (8+)
Database	Nothing for one server (SQLite is built in). For a network: MySQL, MariaDB, PostgreSQL or MongoDB
Other plugins	None required. See Integrations for what is picked up automatically

What's in the download

File	What it is
`SkyWarsCore-1.0.0.jar`	The plugin. Put it in `plugins/` on every lobby and game server.
`SkyWarsCore-Proxy-Velocity-1.0.0.jar`	Network routing for Velocity (networks only).
`SkyWarsCore-Proxy-Bungee-1.0.0.jar`	Network routing for BungeeCord and Waterfall (networks only).
`starter-maps/`	Six ready-made maps. Copy them to `plugins/SkyWarsCore/exports/` and run `/sw map import <file>`.

Game modes

Mode	Teams	Notes
Solo	1 player	12 islands by default
Duos, Trios, Quads	2, 3 or 4 players	Team cages, team colours, team chat, party auto-teaming
Any size	Any team size	Add a mode in `modes.yml` with any `team-size`
Clash	Teams fighting over a walled fortress in the middle	Generated fortress maps in six themes
Ranked	Solo, seasons	Placement games, divisions, loss protection, leaver and dodge penalties
Duels	1v1, best-of-3, party 2v2	Request menu with rules, rematch, spectating
Private games	Hosted with `/host`	Invite-only or open, any map and rules
Tournaments	Brackets	Created and run in game

Every mode is a block in modes.yml: team size, islands, minimum players, loot tables, kits, perks, combat profile, vote options and twists.

Gameplay

Cage voting: health, time of day, projectiles, the event timeline and the twist.
Loot: island, middle, centre and supply tiers with fair-loot guarantees. Every player gets a weapon, armour and blocks from their own island. Tables are edited in game with /sw loot, which has a simulator and share codes.
Event timelines: chest refills, Supply Drops, Final Showdown border, Sky Collapse, Bounty, Sky Relic and your own events, set in events.yml.
22 twists: Swap Storm, Rising Void, Hot Potato, Low Gravity, Glass Cannon, One Shot, Vampire, Mirror Loot, Supply Rush, Elytra Drop, Mystery Kits, Bridges Built, Hunted, Meteor Shower, TNT Madness, Speed Demons, Crumbling Blocks, Lucky Islands, Fog of War, Pearl Party, Armed Drop and Chaos Clock. A featured twist mode rotates one into the Play menu.
Combat profiles: 1.8 knockback with no attack cooldown, or modern combat, sword blocking and golden heads. Set per mode.
10 custom enchantments, including Lifesteal, Shockwave and Venom. Ranked can turn them off. AdvancedEnchantments, EcoEnchants and ExcellentEnchants are supported too.
Kits with rarities, coin prices, previews and saved hotbar layouts. Build them from your inventory with the in-game kit creator.
Smart loot sort: shift-clicked chest loot goes to the slots each player picked.
Spectating with a teleporter, the death recap card and a game summary card for everyone.

Progression

Levels with 12 prestiges, coins, XP and shards
Perks with levels, three slots
Daily and weekly quests, challenges and achievements
A 50-tier season pass with a free track and a cosmetic premium track
Login streaks, a profile menu, match history and leaderboards for every stat
Trophies and a trophy case in the lobby

Nothing sold for money gives an advantage in a game: the premium pass and boosters give cosmetics and shards only.

Cosmetics

Cages, kill effects, trails, victory dances, death cries, kill messages, sprays, balloons and rarity chest skins with opening animations. Players unlock them from progression or the Loot Altar (shards for random cosmetics) and browse them in the collection book.

Lobby

Mode NPCs with live player counts, each with its own skin and gear
Podium statues of the top three, leaderboard holograms and trophy cases
Parkour with timers and a practice hub for bridging and PvP drills
Lobby hotbar, double jump, flight and join messages for ranks

Everything is placed with /sw designer or from the admin panel. Holograms are packet-based, so nothing is spawned in your worlds. DecentHolograms, FancyHolograms, Citizens and FancyNpcs are used when installed.

Staff tools

Staff mode with vanish, a staff hotbar, silent spectating, follow and a teleporter
Player lookup: stats, rating, matches, reports, punishments, notes and alts
Report queue with claiming, a punishment template menu, freeze, inventory inspection
Live game list, match timelines, slow mode, staff chat and an audit log
Anticheat alerts from Grim, Polar, Vulcan, Spartan, Matrix, Intave and NoCheatPlus, and ranked anti-boost alerts. LiteBans and AdvancedBan punishments are used when installed.

For server owners

/sw quickstart: a lobby, starter maps, NPCs and leaderboards in about a minute
/sw opens the admin panel: maps, modes, kits, loot, lobby, appearance, network and settings
Map generator: hand-built-looking islands in several themes, solo, team and Clash layouts
Map wizard: stand in any map and run /sw map create <name>. Islands, spawns and chests are detected, a chest tool kit tags tiers in a click, and every save is a version you can roll back
/sw doctor checks the setup and says exactly what to fix
/sw perf shows what SkyWarsCore costs the server, per feature
Presets: Classic, Competitive, Casual and Ranked
Every message, menu, item and sound is configurable. Menus can be reskinned with item models, custom model data, ItemsAdder, Nexo and Oraxen items and font-image titles. A built-in resource pack host serves the Modern theme.

Bedrock

Geyser and Floodgate players get Bedrock forms for every menu, textures through Geyser mappings, and the same gameplay. Ranked can be cross-play or Java-only.

Performance

Game worlds are reset in place and reused, so joining a game takes milliseconds and no world is copied while players play
The map generator writes region files off the server thread
No database or file work on the server thread
Scoreboards, nametags and the tab list send only what changed
Advanced Slime Paper worlds are used automatically when available
/sw perf times SkyWarsCore's own work and warns staff when a tick goes over budget

Commands

Command	What it does	Permission
`/play [mode]`	Open the Play menu or join a queue	`skywars.play`
`/leave`	Leave your game	`skywars.play`
`/kits`	Kit selector	`skywars.kits`
`/perks`	Perks	`skywars.perks`
`/vote`	Cage vote menu	`skywars.vote`
`/settings`	Gameplay settings	`skywars.settings`
`/profile [player]`	Profile and stats	`skywars.profile`
`/quests`, `/achievements`, `/pass`	Progression menus	`skywars.quests`, `skywars.achievements`, `skywars.pass`
`/leaderboards`	Leaderboards	`skywars.leaderboards`
`/cosmetics`, `/collection`, `/altar`	Cosmetics, collection book, Loot Altar	`skywars.cosmetics`, `skywars.collection`, `skywars.altar`
`/party`	Parties	`skywars.party`
`/ranked`	Ranked	`skywars.ranked`
`/duel <player>`	Duels	`skywars.duel`
`/tournament`	Tournaments	`skywars.tournament`
`/host`	Private games	`skywars.host`
`/practice`, `/parkour`	Practice hub and parkour	`skywars.practice`, `skywars.parkour`
`/spray`, `/trophies`	Sprays and trophy case	`skywars.spray`, `skywars.trophies`
`/report <player>`	Report a player	`skywars.report`
`/staff`, `/sc`	Staff panel and staff chat	`skywars.staff.panel`, `skywars.staff.chat`
`/sw`	Admin panel	`skywars.admin`
`/sw quickstart`	Set up a playable server	`skywars.admin.setup`
`/sw map ...`	Generate, create, edit, save, roll back, export and import maps	`skywars.admin.setup`
`/sw preset <preset>`	Apply a preset	`skywars.admin.setup`
`/sw lobby set`	Set the lobby	`skywars.admin.setup`
`/sw designer`	Place NPCs, leaderboards, podiums, parkour and trophy cases	`skywars.admin.lobby`
`/sw loot`	Loot editor and simulator	`skywars.admin.loot`
`/sw game start\\|end [game]`	Control a game	`skywars.staff.manage`
`/sw doctor`	Check the setup	`skywars.admin.doctor`
`/sw perf`	Performance report	`skywars.admin.perf`
`/sw reload`	Reload every file	`skywars.admin.reload`

Every command can be renamed, given aliases or turned off in commands.yml.

Permissions

Player permissions default to everyone. The groups are:

Permission	Gives
`skywars.admin.*`	Every admin and staff permission
`skywars.staff.*`	Every staff permission
`skywars.pass.premium`	The premium season pass track (cosmetics and shards only)
`skywars.booster.vip`, `skywars.booster.mvp`	x1.25 and x1.5 shards from games
`skywars.vote.weight.2` to `.5`	Cage votes count 2 to 5 times
`skywars.lobby.fly`, `skywars.lobby.doublejump`	Lobby flight and double jump
`skywars.lobby.join.vip`, `skywars.lobby.join.mvp`	Rank join messages
`skywars.host.join-any`	Join any private game without an invite
`skywars.report.exempt`	Cannot be reported

The full list, with a line for each, is in plugin.yml inside the jar.

Placeholders

With PlaceholderAPI installed, %skywars_<key>% gives:

Placeholder	Value
`%skywars_wins%`, `_kills%`, `_deaths%`, `_games%`	Lifetime stats
`%skywars_coins%`, `_xp%`, `_level%`	Progression
`%skywars_kdr%`, `%skywars_wlr%`	Kill/death and win/loss ratios
`%skywars_players_<mode>%`	Players in a mode, e.g. `players_solo`
`%skywars_game_<key>%`	Any scoreboard value of the player's game: `game_map`, `game_alive`, `game_kills`, `game_event`

Integrations

Picked up automatically when installed, and each can be turned off in config.yml:

Kind	Plugins
Placeholders, economy, ranks	PlaceholderAPI, Vault, LuckPerms
Clients	Lunar Client (Apollo): rich presence, nametags, waypoints, staff x-ray
Bedrock	Geyser, Floodgate
Holograms and NPCs	DecentHolograms, FancyHolograms, Citizens, FancyNpcs
Custom items	ItemsAdder, Nexo, Oraxen, MMOItems, EcoItems
Enchantments	AdvancedEnchantments, EcoEnchants, ExcellentEnchants
Punishments	LiteBans, AdvancedBan
Anticheats	Grim, Polar, Vulcan, Spartan, Matrix, Intave, NoCheatPlus
Other	Essentials, CMI, Multiverse-Core, ReplayCore, ViaVersion

Configuration files

File	What's in it
`config.yml`	Licence key, modules, storage, lobby, map generator, integrations
`game.yml`	Countdowns, rewards, rules for every game
`modes.yml`	Game modes and their queues
`events.yml`	Event timelines
`twists.yml`	Twists and their settings
`kits.yml`, `votes.yml`, `cosmetics.yml`, `enchants.yml`	Kits, cage votes, cosmetics, enchantments
`lobby.yml`, `hotbar.yml`, `practice.yml`	The lobby, its hotbar and the practice hub
`scoreboard.yml`, `tablist.yml`, `appearance.yml`	Boards, tab list, menu theme and resource pack
`network.yml`	Network mode, server role and the shared secret
`commands.yml`	Command names, aliases and rate limits
`menus/`	Every menu's layout, items and text
`lang/en_US.yml`	Every message

Updates add new settings to your files and keep your edits. /sw reload applies most changes without a restart.

Storage

SQLite needs no setup and suits a single server. For a network, point every server at the same MySQL, MariaDB, PostgreSQL or MongoDB database with the same table-prefix (storage in config.yml). Writes are atomic increments, so servers saving at the same moment never overwrite each other.

Licence

Paste the key from your BuiltByBit purchase message into licence-key in config.yml. The key is checked at start-up and every few hours. If the licence server can't be reached, SkyWarsCore keeps running for up to a week on its last successful check.