ResidenceBridge

# ResidenceBridge > Cross-server Residence bridge for sharing (https://www.spigotmc.org/resources/residence.11480/) data, teleport requests, and global limits across a Velocity / BungeeCord network. (https://img.shields.io/badge/Server-Java%208%2B-orange.svg)](https://adoptium.net) (https://img.shields.io/badge/Minecraft-1.16%2B-brightgreen.svg)](https://papermc.io) ## 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: ```toml # velocity.toml s1 = "127.0.0.1:25566" s2 = "127.0.0.1:25567" ``` ```yaml # 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. ```yaml 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: ```yaml 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: ```text rb sync ``` Check what ResidenceBridge can read: ```text 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`