Overview
AstralHomes provides personal homes, global network warps, /back, /spawn, and cross-server teleport requests (/tpa, /tpahere) for the AstralRealms network.
Requirements
Dependency | Required | Notes |
|---|---|---|
Paper | Yes |
|
Java 25 | Yes | Compiled with |
AstralCore | Yes | Hard |
AstralSync | Yes | Hard |
Both AstralCore and AstralSync are listed under depend in plugin.yml — the plugin will not load if either is missing.
Runtime infrastructure
AstralHomes leans entirely on AstralCore for its backing services; it opens no connections of its own beyond what those services manage:
Service | Backing tech | Used for |
|---|---|---|
| MariaDB via HikariCP | The global |
| Redis | Pending teleport requests ( |
| Cross-server packet bus | Teleport request packets ( |
| Binary-serialized per-player data |
|
Persistence split
Two storage models coexist, and the plugin is deliberate about which one owns which data:
Warps are global and stored in MariaDB (the
warpstable:name,server_group,x/y/z,yaw/pitch,world). They're loaded into an in-memory map at startup and kept in sync with the database on every set/delete.Homes, last-locations, and the TPA toggle are per-player and live in
HomePlayerData, replicated across the network by AstralSync — they are never written to MariaDB.
See Homes and Warps & Spawn for the full behavior of each.
Feature map
Feature | Page |
|---|---|
Personal homes ( | |
Global warps and | |
Cross-server |
Warmup
/home, /warp, /spawn, and /back teleports go through a shared WarmupService: a progress bar built out of coloured | characters plus a percentage is shown in the action bar while the player waits, and the warmup is cancelled by WarmupListener when the player changes block (moves) or disconnects. Warmup duration is permission-driven, configured under warmup in config.yml as a permission → duration map; the lowest duration among permissions the player holds wins (e.g. astralhomes.mvp: 0s overrides astralhomes.default: 5s), and a duration of 0s skips the warmup entirely.
Accepted teleport requests (/tpaccept) are the exception — TeleportationRequestService hands the move straight to AstralCore's TeleportationService without going through WarmupService, so there is no countdown before the teleport happens. See Teleport Requests → Movement.
Commands at a glance
Command | Purpose |
|---|---|
| Teleport to / list homes. |
| Create a home at the player's location. |
| Delete a home. |
| Teleport to / list global warps. |
| Return to the last location (requires |
| Teleport to the server spawn. |
| Request to teleport to another player. |
| Request another player to teleport to you. |
| Accept a pending teleport request. |
| Decline a pending teleport request. |
| Cancel a request you sent. |
| Toggle whether you accept incoming teleport requests. |
Full syntax, aliases, and permissions for every (sub)command are on the Commands page.
Configuration and messages
Runtime behavior is controlled by config.yml (home/warp limits, warmup durations, world blacklist, protected-world permissions, join-location restore groups) and user-facing text by messages.yml. Start at Configuration.