ResidenceBridge

Cross-server Residence bridge for sharing Residence data, teleport requests, and global limits across a Velocity / BungeeCord network.

Features

• Globally unique residence names for /res create and /res rename.
• Cross-server /res tp <name> with automatic server switching and final Residence teleport on the target server.
• Cross-server tab completion for global residence names in /res tp, /res remove, /res rename, and similar commands.
• Global /res list showing residences owned by the player on every sub-server, plus /res list <player> for admins.
• Global residence count limits, configurable by permission group and compatible with LuckPerms permission assignments.
• Permission-based teleport wait time, with movement and damage cancellation; admins or a configured permission can skip the wait.
• Cross-server common actions: /res rename, /res give, /res remove, and /res delete switch to the owning server and execute the original command there.
• Scheduled MySQL sync for all local Residence data, suitable for installing on an already running network.
• PlaceholderAPI placeholders: %reslink_ressize%, %reslink_reslist_1%, %reslink_reslist_2%, and so on.
• Custom messages with legacy & colors and &#RRGGBB RGB colors.
• Folia-aware scheduling for player tasks.

Requirements

Component	Requirement
Sub-server	Paper / Spigot / Folia 1.16+
Residence	Installed on every sub-server
Velocity	Velocity 3.x
Database	MySQL 5.7+ or MariaDB 10.4+
PlaceholderAPI	Optional, only required for placeholders

Configuration Checklist

1. Sub-server IDs

Use the same names as Velocity servers:

# velocity.toml
[servers]
s1 = "127.0.0.1:25566"
s2 = "127.0.0.1:25567"

# s1/plugins/ResidenceBridge/config.yml
server-id: "s1"

# s2/plugins/ResidenceBridge/config.yml
server-id: "s2"

If server-id does not match a Velocity server name, database sync can still work, but cross-server switching will fail.

2. MySQL

All sub-servers must use the same database. Tables are created automatically.

mysql:
  host: "127.0.0.1"
  port: 3306
  database: "minecraft"
  username: "root"
  password: "password"

The database user needs CREATE TABLE, ALTER TABLE, SELECT, INSERT, UPDATE, and DELETE permissions.

3. Proxy Channel

The Velocity-side plugin currently has no separate config file. Keep this on the sub-server side:

velocity:
  channel: "residencebridge:main"
  fallback-bungee-channel: true

For pure Velocity networks, fallback-bungee-channel may be set to false; keeping the default is fine when unsure.

4. First Sync and Debugging

After installing on an existing network, run this from every sub-server console:

rb sync

Check what ResidenceBridge can read:

rb debug

Important debug fields:

Field	Meaning
Residence instance	Whether the Residence plugin instance is available
Residence names / Residence values	Whether Residence API data is readable
Residence file snapshots	Whether saved Residence files were found
Snapshots	Final data that will be synced to MySQL

If Snapshots is not 0, rb sync should write data to MySQL.

Commands and Permissions

Command	Permission	Default	Type	Description
/res tp <name>	Residence original permission	Player	Player	Cross-server teleport to a residence. ResidenceBridge will switch the player to the target server and continue the Residence teleport there.
/res list	Residence original permission	Player	Player	Lists the player's global residences across all linked sub-servers.
/res remove <name>	Residence original permission	Player	Player	Removes a residence. If the residence is on another server, ResidenceBridge switches the player to the owning server and executes the action there.
/res delete <name>	Residence original permission	Player	Player	Alias-style delete action handled through the owning server when needed.
/res rename <old> <new>	Residence original permission	Player	Player	Renames a residence while keeping residence names globally unique across the network.
/res give <name> <player>	Residence original permission	Player	Player	Transfers a residence to another player. Cross-server ownership actions are routed to the owning server.
/res list <player>	residencebridge.list.others	OP	Admin	Lists another player's global residences.
/rb reload	residencebridge.command.reload	OP	Admin	Reloads the sub-server config.
/rb sync	residencebridge.command.sync	OP	Admin	Syncs local Residence data to MySQL immediately.
/rb debug	residencebridge.command.debug	OP	Admin	Prints Residence read and sync diagnostics.
/residencebridge reload	residencebridge.command.reload	OP	Admin	Alias of /rb reload.

Permission-driven behavior is configured in config.yml and works well with LuckPerms, for example lp group vip permission set reslink.count.vip true. Default examples:

Permission	Purpose
ResLinkDefault	3-second teleport wait
ResLinkDefaultCount	3 global residences
reslink.tp.vip	1-second teleport wait
reslink.count.vip	10 global residences
residencebridge.list.others	List another player's global residences
residencebridge.teleport.bypass	No teleport wait
residencebridge.limit.bypass	Unlimited global residence count

PlaceholderAPI

Placeholder	Description
%reslink_ressize%	Player's global residence count
%reslink_reslist_1%	Player's first residence name
%reslink_reslist_2%	Player's second residence name

Database Tables

Table	Purpose
residence_bridge_index	Global residence index with name, server, world, owner, and status
residence_bridge_pending_tp	Pending cross-server teleport requests
residence_bridge_pending_action	Pending cross-server command actions