Installation

Requirements

• OptimalLibrary - required. A separate, free plugin that provides the shared runtime (text and MiniMessage, menus, prompts, storage, scheduling). OptimalTeams will not enable without it.
• Paper / Folia (or a Paper fork). Spigot is not supported. Supported versions are 1.21.11, 26.1.1, 26.1.2, 26.2 and 26.3.
• Java 21 on 1.21.11, Java 25 on the 26.x servers. Check with java -version.

Optional soft dependencies:

• PlaceholderAPI - registers the %optimalteams_...% placeholders and resolves %...% from other plugins inside messages and menus. See Placeholders.
• OptimalKoth - when installed, a KOTH capture earns the capturer’s team points (Point-Sources.Koth-Capture). Without it, nothing is hooked and kills are the only automatic point source.

Steps

1. Confirm java -version reports the right version for your server.
2. Stop the server.
3. Drop OptimalLibrary.jar and OptimalTeams.jar into plugins/.
4. (Optional) Add PlaceholderAPI.jar and/or OptimalKoth.jar.
5. Start the server. The plugin generates its files and prints a startup banner with the number of teams and members it loaded. With OptimalKoth present, the console also logs Hooked OptimalKoth.
6. Run /plugins - OptimalLibrary and OptimalTeams should both be green.

OptimalLibrary downloads sqlite-jdbc, mysql-connector-j, HikariCP and XSeries through Paper’s library loader on first startup, so the first launch needs internet access and may take a few extra seconds.

Generated files

plugins/OptimalTeams/
├─ config.yml               # settings, point sources, roles, team format, sounds
├─ messages.yml             # every message and title
├─ guis/
│  ├─ team-menu.yml         # /team for a player in a team
│  ├─ hub-menu.yml          # /team for a player without a team
│  ├─ invites-menu.yml      # pending invites
│  ├─ members-menu.yml      # roster, promote, demote, kick
│  ├─ settings-menu.yml     # rename, friendly fire, open joining, set home
│  ├─ top-menu.yml          # team leaderboard
│  ├─ team-info-menu.yml    # read-only view of any team
│  └─ confirm-menu.yml      # disband, leave, kick and transfer confirmation
└─ data/
   └─ data.db               # SQLite team data (do not edit by hand)

data/data.db is only created with the default SQLite storage. Every GUI file is required; a missing one is extracted again on the next start.

Storage

Teams and members are stored in two tables, optimalteams_teams and optimalteams_members, in SQLite (data/data.db, the default) or MySQL. Switch with Settings.Storage in config.yml.

Everything is loaded into memory when the server starts. Every change (a new team, a join, a point change, a toggle) is queued for the database right away and written on a background thread, in order, so there is no save interval to configure. Creating, transferring and disbanding a team are single transactions. Pending writes are flushed when the server shuts down.

Storage changes need a restart

/teamadmin reload does not reconnect the database. After changing Settings.Storage, restart the server.

Do not edit the tables by hand

On startup the plugin refuses to load inconsistent data (a member whose team is missing, a team without exactly one leader, a player in two teams, two teams with the same name) and fails with the offending row named in console. Use the in-game and admin commands instead.

Continue to Creating a Team, or read the Information overview first.