---

Table of Contents

1. Hero
2. Why NewGen Team?
3. Feature Overview
4. Configuration System
5. GUI System
6. Theme System
7. Language System
8. Database
9. Performance
10. PlaceholderAPI
11. Plugin Integrations
12. Developer API
13. Commands
14. Permissions
15. Installation
16. Migration Guide
17. Configuration Examples
18. FAQ
19. Roadmap
20. Compatibility
21. Screenshots
22. Support
23. License

---

2. Why NewGen Team?

Most team plugins on the market were designed years ago, for a server landscape that no longer exists. They assume a single database, a single language, a fixed GUI, and a fixed color scheme. Every server that wants something different is forced into workarounds, resource pack hacks, or forks that fall out of date within a season.

NewGen Team starts from a different premise: the plugin should adapt to the server, not the other way around.

That premise shapes every architectural decision:

• Configuration over code. Every visual element — menu layout, item placement, color palette, wording — lives in a YAML file, not in the jar. Updating the plugin will never overwrite or erase your custom designs.
• Async by default. Every database operation and heavy computation runs off the main thread. On Folia, this is not an afterthought bolted on top of a legacy Bukkit codebase — the plugin was built against Folia's region-threading model from day one.
• One core, many backends. Whether a server runs a 20-player SQLite survival world or a 5,000-player network on PostgreSQL, the exact same codebase, feature set, and configuration schema apply. Switching backends is a config change, not a database migration project.
• Native Dialogs & Protocol Routing. Supports Paper's modern native Dialog API for client versions 1.21.6+, while automatically falling back to virtual signs for legacy clients.
• Theming as a first-class feature. Colors are tokens, not hardcoded strings. MiniMessage powers every message, title, and GUI label, enabling clean gradients, hover text, and click actions anywhere text appears.
• Two languages out of the box. English and Vietnamese ship as complete, professionally structured translations with automatic fallback and safe key-merging on update.

---

3. Feature Overview

Native Dialog API & Protocol Routing

What it is: A modern user input service utilizing Paper's native Dialog API (io.papermc.paper.dialog.Dialog) for text input (team naming, tag changes, balance management, search), paired with protocol detection.

Benefits: Eliminates clumsy sign interfaces and packet hacks on modern clients. Players can type directly into clean native dialog boxes with custom icons and themed confirm buttons without losing inventory focus.

Technical explanation: PacketEvents reads each player's true client version. Clients running >= 1.21.6 receive native Paper dialogs. Clients running < 1.21.6 (such as 1.20 clients connecting via ViaVersion) seamlessly fall back to virtual signs. Input methods can also be forced via gui.input-method (AUTO, DIALOG, SIGN).

---

Async Storage Engine

What it is: A non-blocking storage layer ensuring no team query, bank transaction, or leaderboard calculation ever stalls the server main thread or a Folia region thread.

Benefits: Rock-solid 20.0 TPS even under heavy load, no lag spikes during team creation bursts, and resilient behavior during temporary database connection latency.

Technical explanation: All queries dispatch through an asynchronous connection-pooled executor. Results return safely to the calling thread only upon resolution. Frequent reads are served from an in-memory cache with configurable TTLs.

---

HikariCP-Backed Database Layer

What it is: Universal SQL backend support — SQLite, MySQL, MariaDB, PostgreSQL — backed by HikariCP enterprise connection pooling.

Benefits: Instant connection acquisition, automatic reconnection on network drops, and zero manual driver installations (all JDBC drivers are shaded inside the jar).

---

GUI Layout & Role Permissions

What it is: Fully configurable menus with declarative slot mapping, item lore, custom model data, and granular per-role permissions.

Benefits: Complete freedom to redesign interfaces or map textures to custom resource packs without touching Java code. Over 20 granular permissions can be toggled per role directly within the in-game GUI.

---

Multi-Page Team Chest

What it is: A shared virtual container per team that expands across multiple pages based on team tier progression.

Benefits: Safe item sharing with transactional auto-flush, preventing inventory desync and item loss across server restarts.

---

Team Bank & Economy

What it is: Shared currency pool integrated with Vault, supporting deposits, withdrawals, and full transaction auditing.

---

Team Home & Warmup Fast-Path

What it is: Central team teleportation point with configurable cooldowns, warmup countdowns, and movement cancelation checks.

---

Daily Audit Logging

What it is: Categorized, rotating log files (daily/, errors/, transactions/, admin/) stored in plugins/NewGenTeam/logs/.

---

4. Configuration System

NewGen Team organizes its settings into modular YAML files:

File	Purpose
config.yml	Language selection (en_US, vi_VN)
settings.yml	Core gameplay settings, input methods (AUTO/DIALOG/SIGN)
database.yml	Backend engine (SQLite, MySQL, MariaDB, PostgreSQL) and pool size
theme.yml	Central color tokens referenced across menus and messages
hooks.yml	Third-party integrations (Vault, PlayerPoints, PlaceholderAPI, PacketEvents)
menus/*.yml	Per-menu layout, slots, custom model data, and materials
lang/*.yml	Comprehensive language files with automatic key merging
levels.yml	Tier levels, member capacities, upgrade costs, and perks
homes.yml	Team home teleport rules, warmups, and cooldowns
logs.yml	File logging categories and debug toggles
chest.yml	Team chest pages, sizing, and periodic flush intervals

---

5. GUI System

Menus under menus/ follow a declarative layout:

title: "<primary>Team Menu"
rows: 6
items:
  bank:
    slot: 31
    material: GOLD_BLOCK
    glow: true
    custom-model-data: 1234
    enabled: true
  home:
    slot: 29
    material: RED_BED
    glow: false
    enabled: true
  members:
    slot: 33
    material: PLAYER_HEAD
    glow: false
    enabled: true

Text, lore, and titles resolve through MiniMessage against theme.yml and the active language file, separating design from localization.

---

6. Theme System

Semantic color tokens defined in theme.yml:

colors:
  primary:   "#5865F2"
  secondary: "#8A2BE2"
  accent:    "#FFD700"
  muted:     "#808080"
  danger:    "#E74C3C"
  success:   "#2ECC71"
  warning:   "#F1C40F"
  info:      "#3498DB"

Referenced directly inside messages and menus:

messages:
  team-created: "<success>Your team <primary><team_name></primary> has been created!</success>"

---

7. Language System

Ships with complete English (en_US) and Vietnamese (vi_VN) translations. Missing keys automatically fall back to en_US. Plugin updates merge new keys safely without overwriting administrator modifications.

---

8. Database

Backend	Setup Required	Recommended For
SQLite	None (Default)	Single-server survival, SMP
MySQL	External MySQL Server	Multi-server proxies sharing team data
MariaDB	External MariaDB Server	High-performance multi-server setups
PostgreSQL	External PostgreSQL Server	Large networks with existing Postgres clusters

All drivers are shaded inside the jar. If an external database is temporarily unreachable at boot, the plugin falls back to SQLite to keep gameplay uninterrupted.

---

9. Performance & Scalability (500+ Players)

• Batched Kill/Death Persistence: Kill and death statistics increment in-memory and flush to disk in 30-second cycles, eliminating database write bottlenecks during large team fights.
• O(1) Warmup Fast-Path: PlayerMoveEvent evaluates hasAnyWarmup() in O(1) time. When no player is warming up a home teleport, all per-block map traversals are skipped.
• 5-Second TTL Leaderboard Cache: Rank calculations and PlaceholderAPI queries read from memoized snapshots, preventing O(n log n) sorting overhead on hot paths.
• Async Resource Metrics: Resource usage commands walk disk structures asynchronously to guarantee zero tick drops on the server thread.

---

10. PlaceholderAPI

Identifier: newgenteam (All placeholders read directly from in-memory cache):

Placeholder	Description
%newgenteam_name%	Team name (empty if not in a team)
%newgenteam_name_display%	Team name or configurable fallback text
%newgenteam_tag%	Team tag / prefix
%newgenteam_role%	Player role (Owner, Officer, Member, Recruit)
%newgenteam_owner%	Name of the team owner
%newgenteam_members%	Current member count
%newgenteam_members_max%	Maximum member limit for current tier
%newgenteam_online%	Count of online team members
%newgenteam_level%	Team level / tier
%newgenteam_bank%	Team bank balance
%newgenteam_kills%	Total team kill count
%newgenteam_deaths%	Total team death count
%newgenteam_kdr%	Team kill/death ratio
%newgenteam_rank%	Leaderboard rank position

---

11. Plugin Integrations

Plugin	Purpose	Required
PacketEvents	Powers client version detection and virtual input routing	Yes
Vault	Connects team bank to server economy	No
PlayerPoints	Alternative currency for team tier upgrades	No
PlaceholderAPI	Exposes %newgenteam_*% placeholders	No

---

12. Developer API

Package: me.newgen.team.api.event — Cancellable Bukkit events for custom integration:

Event	Fired When
TeamCreateEvent	A team is created
TeamDeleteEvent	A team is disbanded
TeamJoinEvent	A player joins a team
TeamLeaveEvent	A player leaves a team
TeamKickEvent	A player is removed from a team
TeamLevelUpEvent	A team upgrades its tier
BankDepositEvent	Funds are deposited into team bank
BankWithdrawEvent	Funds are withdrawn from team bank

---

13. Commands

Player Commands (/team, /t, /f, /guild)

Command	Description
/team	Open the main team dashboard
/team create <name>	Create a new team
/team invite <player>	Invite a player to your team
/team join <team>	Request to join an open team
/team leave	Leave current team
/team home	Teleport to team home
/team chat	Toggle private team chat channel

Administrative Commands (/newgenteam, /newgen)

Command	Permission	Description
/newgen status	newgenteam.status	Real-time diagnostic monitor (JVM CPU/RAM, plugin disk, active objects, task cost)
/newgen info	None	Public summary of server teams, total members, and averages
/team admin	newgenteam.admin	Open administrative team management GUI
/team reload	newgenteam.reload	Hot-reload all configurations, themes, menus, and languages

---

14. Permissions

Permission	Description
newgenteam.use	Access to player team commands
newgenteam.status	Access to /newgen status diagnostic command
newgenteam.admin	Access to admin panel and forced team actions
newgenteam.reload	Access to /team reload

---

15. Installation

Requirements:

• Paper or Folia: 1.21.x – 26.3+
• Java 25+
• PacketEvents (Required dependency, load order BEFORE)

Setup:

1. Place PacketEvents into your plugins/ directory.
2. Place NewGenTeam-1.2.0.jar into your plugins/ directory.
3. Start the server to generate configuration files in plugins/NewGenTeam/.
4. Adjust settings as desired and run /team reload.

---

16. Migration Guide

Switching between database types (SQLite, MySQL, MariaDB, PostgreSQL) is handled via database.yml. Drivers are pre-bundled. Backup your data before switching storage engines.

---

17. Configuration Examples

# settings.yml
gui:
  # Input method: AUTO (Recommended) | DIALOG | SIGN
  input-method: AUTO

team:
  max-name-length: 16
  min-name-length: 3
  disband-on-owner-leave: false

# database.yml
type: MYSQL
host: 127.0.0.1
port: 3306
database: newgenteam
username: root
password: "password"
pool-size: 10
connection-timeout: 5000

---

18. FAQ

1. Does NewGen Team support Paper 26.3 and Java 25? Yes. The plugin is built with Java 25 toolchains and native Paper 26.3 libraries.

2. Does it run on Folia? Yes. All task scheduling and teleports run through Folia-safe regional schedulers.

3. What is the difference between AUTO, DIALOG, and SIGN input? AUTO dynamically routes Paper Dialogs to Minecraft 1.21.6+ clients and virtual signs to older clients. DIALOG forces dialog boxes, and SIGN forces sign input.

4. Can players pay for tier upgrades using PlayerPoints? Yes. Set the payment currency in levels.yml and enable PlayerPoints in hooks.yml.

5. How do I change colors? Edit color tokens in theme.yml. Changes propagate across all messages and menus instantly after /team reload.

---

19. Roadmap

• Cross-server synchronization over Redis / RabbitMQ
• Claiming / Territory protection hook integrations
• Web dashboard companion

---

20. Compatibility

Platform	Supported Version	Notes
Paper	1.21 – 26.3+	Fully supported
Folia	Supported	Region-safe scheduling
Purpur	Supported	Compatible Paper fork
Java	Java 25+	Required for modern Paper

---

21. Screenshots

Main Team Dashboard (/team)

Central navigation dashboard displaying members, bank, chest, homes, settings, and team progression.

---

Granular Role Permissions

Over 20 customizable permissions per role, including bank management, invitations, chest access, and home teleports.

---

Tier Upgrades & Package Perks

Interactive progression tree detailing chest expansion, member caps, and home limits per tier.

---

Multi-Page Team Chest

Paginated virtual chest system with automatic transaction flushing and inventory protection.

---

Real-Time Resource Diagnostic (/newgen status)

Deep inspection tool reporting JVM CPU, RAM, disk footprint, active objects, and internal task duration.

---

Team Statistics & Performance

Track team kill/death ratios, creation dates, and balance in one centralized view.

---

Team Settings & Access Control

Toggle open invitations, friendly fire, and public joining direct from the GUI.

---

Server-Wide Team Statistics (/newgen info)

Public summary showing total active teams, total members, online counts, and averages.

---

22. Support

• Discord: discord.gg/P3NSwtJ2aw
• Bug Reports: Open an issue with your Paper/Folia build, Java version, and server logs.

---

23. License

All Rights Reserved.

Copyright © NewGen Team. This software and its associated documentation may not be copied, modified, redistributed, or sold without prior written permission from the copyright holder.

---