Prerequisites

• Server: Spigot/Paper 1.21+
• Java: 21 recommended
• Optional: MySQL/MariaDB if you enable database storage

Install / First Run

1. Place the EasyGG jar into plugins.
2. Start the server once to generate config files.
3. Open plugins/EasyGG/config.yml and adjust the basics (messages, killstreaks, chat format, combat tag, powerups, leaderboard, etc.).
4. Proceed with the Quick Setup below.

Quick Setup (recommended order) ⚡

1. Go to your GG world and set the spawn: /gg setspawn
2. Create your first kit from your inventory: /gg kit create <name> <level>
3. (Optional) Define a safe zone (see section below).
4. (Optional) Not using rotation? Set the default active world: /gg activemap <world>
5. (Optional) Enable Map Rotation (see section below).
6. (Optional) Create a powerup spawn (look at a plate): /gg powerup create <id> [cooldownSeconds]

Maps & Safe Zones

• World spawn
  Use /gg setspawn in each world where you run GG. Players can use /spawn; a countdown prevents abuse (configurable).
  
• Safe zone setup (two corners)
  • Stand at corner 1 and run: /gg zone set
  • Stand at the opposite corner and run: /gg zone set again
  • Done - the region is protected, with titles on enter/leave
  If you make a mistake: /gg zone del cancels the setup.
  Safe zones are saved per-world and auto-loaded on server start.
  
• Active map when rotation is OFF
  If you are not using Map Rotation, the world set under ActiveWorldName in config.yml is considered the active GG world. On join, players are teleported to this world automatically. For best results, ensure the world has a safe zone and a valid spawn.
  
  Use /gg activemap <world> to update ActiveWorldName. Executing this command also teleports all online players to the newly set world immediately.
  
  If Map Rotation is disabled and ActiveWorldName is not set/used, players will join a random/default world defined by the server. This fallback is not controlled by EasyGG.

Kits Management

• Create from inventory: equip items/armor, then run /gg kit create <name> <level>
• List kits: /gg kit list
• Delete kit: /gg kit delete <name>
  Players joining that world will receive the assigned map kit automatically.

Map Rotation

• Start: /gg mapchange start
• Stop: /gg mapchange stop
• Status: /gg mapchange state
  Rotation broadcasts countdowns and teleports players when switching. If GG.UseMapchange is enabled and at least two maps are configured/available, rotation can auto-start on boot.

Note: When Map Rotation is enabled, ActiveWorldName is ignored. Players always join the current rotating map.


Stats, Levels & Killstreaks

• View stats: /stats
• Levels: Level up/down on kills/deaths. Displayed in scoreboard/tablist.
• Configuration: adjust killstreak broadcasts under GG.Killstreaks.
• Reset stats (admin): /gg resetstats <stats|killstreaks|level|all>
  Use categories to target specific subsets or all.

Leaderboard

• Command: /gg leaderbord
• Usage: /gg leaderbord — opens the leaderboard GUI (top 3)
• Formatting: configure GG.Leaderboard.Header and GG.Leaderboard.LineFormat (placeholders: %pos%, %name%, %level%, %hs%, %kd%)

Powerups ⚡

• What they are: Temporary effects or actions granted via world spawners (e.g., speed, jump, strength, invisibility, instant heal, freeze grenade, etc.).
• Create/Remove: Look at a pressure/weight plate and use /gg powerup create <id> [cooldownSeconds] or /gg powerup remove <id>
• Config path: GG.Powerups — toggle, cooldown, display, actionbar/title texts, and definitions.
• Messages: Action bar messages configurable at GG.Powerups.ActionBar. Title on use at GG.Powerups.UsageTitle.
• Events: Listen for PowerupActivateEvent to react to activations.

DeathBlocks ☠️

• What it does: Instantly kills players who touch/stand on configured blocks/liquids (e.g., WATER, LAVA).
• Toggle: /gg deathblocks <on|off> — broadcasts a message to all players.
• Config path: GG.KillPlayerOnBlockTouch (boolean) and GG.DeathBlockList (list of Bukkit Material names).
• Messages: Broadcast texts under GG.Messages.DeathBlocks.*. Per-death message uses GG.Messages.Death.DeathBlock.

Combat Logging Control ⚔️
Tag players in combat and punish logout during tag time.

• Config path: GG.CombatLogging
• Key options:
  • TagDurationSeconds - duration after last hit
  • Punishments.CommandsEnabled + Punishments.Commands - console cmds (e.g., warn/kick)
  • Punishments.ResetAllStatsEnabled - reset offender stats
  • Punishments.DeductLevelsEnabled + DeductLevels - remove levels

Chat Styling (optional)
Enable EasyGG chat formatting to standardize PvP chat style.

• Config path: GG.Chat
• Keys: Enabled, Format, DefaultPrefix
• Example Format: "%PREFIX% [Lv %LEVEL%] %PLAYER%&7: %MESSAGE%"

Scoreboard & Tablist

• Scoreboard: configure visibility/lines under GG.Scoreboard
• Tablist: format and level display (example format provided in description)

Note: EasyGG targets network setups. The scoreboard, join/leave handling, and related messages/mechanics are always active. ℹ️


Subscribing to EasyGG Events
Integrate with EasyGG by subscribing to custom events. This allows you to easily integrate your own money/currency systems.

• KillstreakStartEvent - Triggered when a player's killstreak starts.
• KillstreakChangeEvent - Triggered when a player's killstreak changes.
• KillstreakEndEvent - Triggered when a player's killstreak ends.
• EasyGGKillEvent - Triggered when a player kills another player.
• EasyGGDeathEvent - Triggered when a player dies from a non-PvP cause.
• LevelChangeEvent - Triggered when a player's level changes (up or down). Includes previous and current level values.
• PowerupActivateEvent - Triggered when a player activates a powerup.

For a practical example, see the [GitHub Gist]( https://gist.github.com/liebki/e0aad00ce7e6db7ba710b072675bd74b) with a ready-to-use plugin main file.

Note: All events are fired on the main server thread. Keep your event handlers lightweight.


Admin Utilities ️

• Build Mode: /gg build — toggle admin build mode
• Clear Chat: /gg cc (self), /gg ccg (global)
• Teleport World: /gg tp <world>
• Active Map: /gg activemap <world> — set ActiveWorldName and teleport all players to it
• Spawn: /gg spawn (teleport), /gg setspawn (set)
• DeathBlocks: /gg deathblocks <on|off> — toggle instakill blocks/liquids
• Powerups: /gg powerup create <id> [cooldown], /gg powerup remove <id>
• Main Help: /gg

Storage

• Flatfile (Default): kits.yml, stats.yml, levels.yml, killstreaks.yml
• MySQL (Optional): enable in GG.MySQL. Stats/levels/killstreaks can be stored in MySQL; other data may remain YAML.

MySQL Quick Example

Permissions (Summary)

• easygg.* — everything
• easygg.gg — use /gg (default: true)
• easygg.world.tp — world teleport
• easygg.kit — use kits (default: true)
• easygg.admin.kit — manage kits
• easygg.admin.setspawn — set spawn
• easygg.admin.cc — clear chat
• easygg.admin.zone — manage safe zones
• easygg.admin.resetstats — reset stats
• easygg.admin.build — toggle build mode
• easygg.admin.mapchange — change maps
• easygg.admin.activemap — use /gg activemap
• easygg.admin.chatclear — used by /gg cc and /gg ccg
• easygg.admin.deathblocks — toggle instakill blocks/liquids
• easygg.admin.powerup — create/remove powerup spawns

Troubleshooting ❗

• Map rotation won’t start: ensure GG.UseMapchange is true and at least 2 maps are available.
• Spawn not set: use /gg setspawn in the target world.
• Stats not saving to MySQL: verify credentials in GG.MySQL and check console for connection logs.
• Players keep items/durability changes: review QoL toggles in config (prevent drops/durability/breaking).
• Combat tag not punishing: enable punishments and configure commands/values under GG.CombatLogging.Punishments.
• Powerup command not working: ensure you are looking at a pressure/weight plate; use a valid powerup id from the config; check permissions.
• DeathBlocks not working: toggle with /gg deathblocks on and ensure GG.KillPlayerOnBlockTouch is true and GG.DeathBlockList contains your blocks.