Nexal Spawn

A powerful, free spawn management plugin for single servers and networks. Supports per-world spawn points, first-join handling, death respawn at spawn, cross-server routing via BungeeCord/Velocity, Redis, or SQL, and a polished spawn selection GUI.

Features

1. Per-World Spawn Points: Define separate spawn points for each world. Players teleport to the correct spawn based on their current world.
2. Global Spawn Fallback: A global spawn point is used for any world without a dedicated spawn.
3. First-Join Spawn: Automatically teleport new players to a configurable first-join spawn on their very first login.
4. Respawn at Spawn: Players respawn at the world's spawn point instead of their bed or default spawn on death (configurable).
5. Join Teleport: Optionally teleport every player to spawn each time they log in.
6. Cross-Server Spawn Routing: Configure /spawn to send players to another server's spawn. Supports three messaging adapters: BungeeCord plugin messaging, Redis pub/sub, and SQL table polling.
7. Three Messaging Adapters: Choose the best fit for your infrastructure: BungeeCord (no extra dependencies), Redis (fast, real-time), or SQL (works with your existing database).
8. Teleport Warmup: Configurable warmup with an action bar countdown, cancel-on-move, cancel-on-damage (each with its own message), and 8 particle effect styles (Circle, Helix, Rings, Flame Pillar, Sparkle, Portal Swirl, Enchant, Dust Orbit) configurable per spawn.
9. Cooldowns: Per-player cooldown between spawn teleports, with bypass permission and tiered cooldown permissions (nexalspawn.cooldown.\<seconds>) for rank-based cooldowns.
10. Economy Cost: Require players to pay a Vault currency fee to teleport to spawn. Supports tiered cost permissions (nexalspawn.cost.\<amount>) for rank-based pricing. The fee is taken when the warmup completes; a failed payment cancels the teleport, and a cross-server teleport that has not connected within 10 seconds is refunded.
11. Rank-Based Default Spawns: Assign different default spawns per rank using nexalspawn.default.\<spawnname> permissions with configurable priority.
12. Per-Spawn Access Permissions: Restrict access to specific spawns with nexalspawn.spawn.\<name> permissions (see Restricting spawns).
13. Arrival Particle Effects: 7 arrival effect styles (Burst, Firework, Pillar, Ring Expand, Dust Cloud, Helix Up, Ground Runes), or None, played when landing at spawn, configurable per spawn.
14. Per-Spawn Arrival Sound: 10 sound options configurable per spawn, played on arrival alongside effects.
15. Effect Preview: Right-click any effect in the selector GUI to preview it on your player before selecting.
16. Default Spawn Indicator: The spawn selection GUI highlights which spawn the player would land at by default with an enchant glow.
17. Per-Spawn Settings GUI: Edit warmup/arrival effects, sound and priority, teleport to the spawn, or delete it (with a confirmation screen).
18. Spawn Protection Zone: Configurable protection radius around spawn points blocking PvP, block breaking, and block placing.
19. Spawn Selection GUI: When multiple spawns exist, a clickable GUI lets players pick their destination (filtered by permissions).
20. Admin Hub GUI: Full in-game admin panel (/spawn admin) with spawn management, configuration, and plugin stats.
21. Configuration GUI: The hub's Configuration button edits the plugin's settings in-game: spawn behavior, the selection GUI, warmup (time, cancel on move or damage, particles, default effect), cooldown, cost, arrival effect, and the protection zone with its PvP, block and op rules.
22. Admin Spawn Management GUI: Manage all spawn points in-game (/spawn admin spawns): open a spawn's settings, or delete it after confirming.
23. PlaceholderAPI Integration: Placeholders for cooldown, spawn coordinates, server name, and spawn count.
24. Dual Storage (JSON + SQL): All data stored in JSON by default; switch to MySQL/MariaDB with one config change.
25. Export / Import Commands: Migrate between storage types or back up data with /spawn admin export and /spawn admin import.
26. Full Message Customization: Every message uses MiniMessage format with gradient support, configurable sounds, and titles.

Technologies

• Paper API 1.20.1+: Minecraft server API
• Utilizer: Configuration, messages, items, tasks, GUIs
• ACF: Command framework
• nexal-core: SQL persistence (MariaDB/MySQL)
• Jedis: Redis client (shaded, optional)
• PlaceholderAPI: Placeholder integration (optional)
• Vault: Economy integration (optional)

Commands

Player Commands

Command	Description	Permission
/spawn	Teleport to spawn (or open GUI if multiple)	nexalspawn.use
/spawn \<name>	Teleport to a specific named spawn	nexalspawn.use
/spawn list	List all spawn points	nexalspawn.use
/spawn help	Show help menu	None

Admin Commands

Command	Description	Permission
/spawn admin	Open admin panel (GUI for players, help for console)	nexalspawn.admin
/spawn admin help	Show admin help text	nexalspawn.admin
/spawn admin spawns	Open spawn management GUI	nexalspawn.admin
/spawn admin info \<name>	Show detailed spawn info	nexalspawn.admin
/spawn admin setspawn [name]	Set spawn at your location (default: world name)	nexalspawn.admin
/setspawn [name]	Shortcut for /spawn admin setspawn	nexalspawn.admin
/spawn admin delete \<name>	Delete a spawn point	nexalspawn.admin
/spawn admin setpriority \<name> <#>	Set rank-spawn priority	nexalspawn.admin
/spawn admin setfirstjoin	Set the first-join spawn at your location	nexalspawn.admin
/spawn admin reload	Reload configuration	nexalspawn.admin
/spawn admin export	Export data to JSON	nexalspawn.admin
/spawn admin import	Import data from JSON	nexalspawn.admin

Permissions

Permission	Description	Default
nexalspawn.use	Use /spawn command	true
nexalspawn.gui	Open spawn selection GUI	true
nexalspawn.bypass.cooldown	Bypass cooldown	op
nexalspawn.bypass.cost	Bypass economy cost	op
nexalspawn.bypass.warmup	Bypass warmup timer	op
nexalspawn.cooldown.\<seconds>	Set custom cooldown (lowest wins)	None
nexalspawn.cost.\<amount>	Set custom teleport cost (lowest wins)	None
nexalspawn.default.\<name>	Set default spawn for rank (highest priority wins)	None
nexalspawn.spawn.*	Access all spawn points	true
nexalspawn.spawn.\<name>	Access a specific spawn point (only matters once nexalspawn.spawn.* is negated)	None
nexalspawn.onjoin	Teleport on join (when enabled)	true
nexalspawn.admin	All admin commands	op

Restricting spawns

Everyone has nexalspawn.spawn.* by default, so every spawn is open to every player and a nexalspawn.spawn.\<name> permission on its own restricts nothing. To lock spawns, negate the wildcard for the group (for example nexalspawn.spawn.*: false in LuckPerms), then grant nexalspawn.spawn.\<name> for each spawn the group may use. Admins (nexalspawn.admin) can always use every spawn.

Placeholders

Requires PlaceholderAPI.

Placeholder	Description
%nexalspawn_cooldown%	Remaining cooldown in seconds, using the player's tiered cooldown permission (0 if not on cooldown or with nexalspawn.bypass.cooldown)
%nexalspawn_spawn_world%	World name of the spawn for the player's current world
%nexalspawn_spawn_x%	X coordinate of the relevant spawn
%nexalspawn_spawn_y%	Y coordinate of the relevant spawn
%nexalspawn_spawn_z%	Z coordinate of the relevant spawn
%nexalspawn_server%	This server's configured name (server.name in config)
%nexalspawn_spawn_count%	Total number of configured spawn points

Configuration

config.yml

# Server identity for cross-server routing
server:
  name: "default"

# "this" = local spawn, or a server name like "hub" for cross-server routing
spawn-server: "this"

# Cross-server messaging adapter (bungee, redis, or sql)
cross-server:
  enabled: false
  adapter: bungee
  redis:
    host: localhost
    port: 6379
    password: ""
    channel: nexalspawn
    timeout: 2000  # connection timeout in milliseconds
  sql:
    poll-interval: 20
    table: nexalspawn_messages
    cleanup-age: 60

# Spawn behavior
first-join:
  enabled: true
respawn-at-spawn: true
teleport-on-join: false
per-world-spawn: true

# Warmup before teleporting
warmup:
  enabled: true
  seconds: 3
  cancel-on-move: true
  cancel-on-damage: true
  particles: true
  default-effect: CIRCLE  # CIRCLE, HELIX, RINGS, FLAME_PILLAR, SPARKLE, PORTAL_SWIRL, ENCHANT, DUST_ORBIT

# Arrival effect on landing
arrival:
  enabled: true
  default-effect: BURST  # NONE, BURST, FIREWORK, PILLAR, RING_EXPAND, DUST_CLOUD, HELIX_UP, GROUND_RUNES

# Cooldown between teleports
cooldown:
  enabled: true
  seconds: 30

# Economy cost (requires Vault)
economy:
  enabled: false
  cost: 0.0

# Spawn protection zone
protection:
  enabled: false
  radius: 10
  no-pvp: true
  no-block-break: true
  no-block-place: true
  ops-bypass: true

# Spawn selection GUI
gui:
  enabled: true
  title: "&b&lSpawn Selection"

# Storage
storage:
  type: json
  sql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

messages.yml

All messages use MiniMessage format with gradient support. See messages.yml for the complete list of customizable messages with sounds and titles.

Messages added in an update work without editing your file: any value missing from your messages.yml (a whole message, or one of its lines such as sound) falls back to the built-in default, in memory only. Your file is never rewritten; copy a key into it to customize it.

Cross-Server Setup

How It Works

1. Each server has a server.name in config (e.g., hub, smp1, smp2)
2. Set spawn-server to the name of the server whose spawn /spawn should use
3. When spawn-server is not "this", the plugin:
   • Sends a spawn request to the target server via the configured adapter
   • Connects the player to the target server via BungeeCord
   • The target server adds the player to a "pending spawn" list
   • When the player arrives, they are immediately teleported to spawn

Example: SMP2 → Hub Spawn

Hub server (config.yml):

server:
  name: "hub"
spawn-server: "this"
cross-server:
  enabled: true
  adapter: bungee

SMP2 server (config.yml):

server:
  name: "smp2"
spawn-server: "hub"
cross-server:
  enabled: true
  adapter: bungee

Now when players type /spawn on SMP2, they are sent to the hub's spawn point.

BungeeCord Adapter

• No extra dependencies
• Enable cross-server.enabled: true and set adapter: bungee
• Requires BungeeCord or Velocity with plugin messaging enabled

Redis Adapter

• Requires a Redis server
• Set adapter: redis and configure cross-server.redis.*
• More responsive than SQL polling

SQL Adapter

• Uses the same database as storage.sql
• Requires storage.type: sql
• Set adapter: sql; a nexalspawn_messages table is created automatically

Storage Migration

To migrate from JSON to SQL:

1. Run /spawn admin export (exports to plugins/NexalSpawn/export/)
2. Change storage.type to sql in config.yml and configure SQL credentials
3. Restart the server (the storage backend is only chosen at startup; /spawn admin reload does not switch it)
4. Run /spawn admin import (spawns replace any existing spawn with the same name)

If the storage cannot be started (for example the SQL server is unreachable), the plugin logs the error and disables itself instead of running without data.

Database Schema

When using SQL storage (storage.type: sql), the plugin creates:

nexalspawn_spawns

Column	Type	Description
id	VARCHAR(36)	PK, unique spawn ID
name	VARCHAR(64)	Spawn name (world name, "global", or custom)
world	VARCHAR(64)	World name
x	DOUBLE	X coordinate
y	DOUBLE	Y coordinate
z	DOUBLE	Z coordinate
yaw	FLOAT	Player yaw (horizontal rotation)
pitch	FLOAT	Player pitch (vertical rotation)
server_name	VARCHAR(64)	Server that owns this spawn
priority	INT	Rank-spawn priority (higher = preferred)
warmup_effect	VARCHAR(32)	Per-spawn warmup effect (null = default)
arrival_effect	VARCHAR(32)	Per-spawn arrival effect (null = default)
arrival_sound	VARCHAR(64)	Per-spawn arrival sound (null = none)
created_at	BIGINT	Creation timestamp (epoch ms)

nexalspawn_users

Column	Type	Description
id	VARCHAR(36)	PK, player UUID
first_join_handled	BOOLEAN	Whether first-join teleport was done
last_teleport_time	BIGINT	Timestamp of last spawn teleport (epoch ms)

nexalspawn_messages (SQL adapter only)

Column	Type	Description
id	BIGINT	PK, auto-increment
sender_server	VARCHAR(64)	Source server name
target_server	VARCHAR(64)	Destination server name
player_uuid	VARCHAR(36)	Player UUID
player_name	VARCHAR(64)	Player display name
message_type	VARCHAR(32)	Message type (e.g. SPAWN_REQUEST)
processed	BOOLEAN	Whether this message has been handled
created_at	BIGINT	Timestamp (epoch ms)

Installation

1. Download the NexalSpawn jar
2. Place it in your server's /plugins folder
3. Start/restart the server
4. Configure plugins/NexalSpawn/config.yml
5. In-game: /spawn admin setspawn to set your first spawn
6. For cross-server networks: enable cross-server in config on all servers