BirdCourier 1.1.3
Paper 26.2 plugin that sends the item stack in your hand to another online player with a flying courier mob.
Requirements
- Paper 26.2 (Java 25)
- No other plugins required
Install
1. Build the plugin (see Build) or take the BirdCourier-<version>.jar from a BlueGit pipeline artifact. 2. Place the jar in the server plugins/ folder. 3. Start or restart the Paper server. 4. Optional: edit plugins/BirdCourier/config.yml, then run /birdcourier reload.
Playing
1. Hold the stack you want to send in your main hand. 2. Run /send <player>. The other player must be online; you cannot send to yourself. 3. A courier spawns near you and flies to the recipient (including through unloaded chunks, and through Nether/End portals when enabled). 4. On arrival the stack is delivered into the recipient's inventory. If nobody can receive it, the courier returns or the shipment is lost after the configured wait.
Pick a personal courier with /courier <type> (tab completion). The choice is stored per player in plugins/BirdCourier/couriers.properties. If you have not chosen one, the default from visual.entity-type is used (parrot).
Allowed types: allay, bat, bee, blaze, chicken, baby_chicken, ghast, parrot, vex.
ghastuses a babyHAPPY_GHAST(Ghastling).- Visual mobs with a usable main-hand equipment slot show a visual copy of the shipment item.
- Bats are kept awake so they do not hang upside down mid-flight.
Commands
| Command | Permission | Default | Description |
|---|---|---|---|
/send <player> | birdcourier.send | everyone | Send the held stack to an online player. |
/courier <type> | birdcourier.courier | everyone | Set your personal courier mob. |
/birdcourier status | birdcourier.admin | op | Show the number of active shipments. |
/birdcourier reload | birdcourier.admin | op | Reload config.yml. |
Configuration
Defaults live in config.yml (copied to plugins/BirdCourier/ on first run):
- visual — default entity type (
PARROT) and whether the courier is silent - flight — visible speed (default 10 blocks/s), unloaded-chunk speed multiplier (5×), preferred height (10), direct-approach distance (15), delivery range, pathfinding limits
- unreachable — how long to wait and retry when the recipient cannot be reached
- portals — follow Nether/End portals (enabled by default)
- persistence — autosave interval for
shipments.tsv - messages — player-facing chat text
- cleanup — delayed cleanup of leftover courier visuals after chunk load; BirdCourier tags are authoritative, so ordinary invulnerable or no-gravity mobs are not removed
Active shipments are stored in plugins/BirdCourier/shipments.tsv. Courier choices are stored in plugins/BirdCourier/couriers.properties.
Build
The project targets the official Paper 26.2 API build 26.2.build.112-stable and Java 25.
With Gradle installed:
gradle build
The resulting JAR is build/libs/BirdCourier-<version>.jar.
Run the unit tests with:
gradle test
Releases
On BlueGit, a master push runs the tests and builds the jar (no manual job). Push a version tag (for example 1.1.4 or v1.1.4) to publish a release automatically: the pipeline runs the tests, builds the jar, and attaches BirdCourier-<version>.jar to the tag. A leading v on the tag is stripped from the version and file name.
Changelog
1.1.3
- Cleanup no longer removes legitimate courier-capable mobs merely for being invulnerable or gravity-disabled.
- Legacy ghost fallback now requires AI to be explicitly disabled.
- BirdCourier tags remain authoritative for cleanup.
1.1.2
- Phantom removed; chicken and baby_chicken added; bats forced awake.
1.1.1 / 1.1.0
- Adds
/courier <type>with tab completion for allay, bat, bee, blaze, ghast, parrot, phantom and vex (phantom later removed in 1.1.2). - Courier choice is stored per player in
couriers.properties. ghastuses a babyHAPPY_GHAST(Ghastling).- Visual mobs with a usable main-hand equipment slot receive a visual copy of the shipment item.
1.0.15
- Default visible speed: 10 blocks/second.
- Default unloaded travel multiplier: 5x.
- Default preferred flight height: 10 blocks.
- Default direct-approach distance: 15 blocks.
- Visual courier entities are non-persistent, so they are not saved into chunk data and later return as ghosts.
Source
| 1 | # BirdCourier 1.1.3 |
| 2 | |
| 3 | Paper 26.2 plugin that sends the item stack in your hand to another online player with a flying courier mob. |
| 4 | |
| 5 | ## Requirements |
| 6 | |
| 7 | - Paper **26.2** (Java **25**) |
| 8 | - No other plugins required |
| 9 | |
| 10 | ## Install |
| 11 | |
| 12 | 1. Build the plugin (see [Build](#build)) or take the `BirdCourier-<version>.jar` from a BlueGit pipeline artifact. |
| 13 | 2. Place the jar in the server `plugins/` folder. |
| 14 | 3. Start or restart the Paper server. |
| 15 | 4. Optional: edit `plugins/BirdCourier/config.yml`, then run `/birdcourier reload`. |
| 16 | |
| 17 | ## Playing |
| 18 | |
| 19 | 1. Hold the stack you want to send in your main hand. |
| 20 | 2. Run `/send <player>`. The other player must be online; you cannot send to yourself. |
| 21 | 3. A courier spawns near you and flies to the recipient (including through unloaded chunks, and through Nether/End portals when enabled). |
| 22 | 4. On arrival the stack is delivered into the recipient's inventory. If nobody can receive it, the courier returns or the shipment is lost after the configured wait. |
| 23 | |
| 24 | Pick a personal courier with `/courier <type>` (tab completion). The choice is stored per player in `plugins/BirdCourier/couriers.properties`. If you have not chosen one, the default from `visual.entity-type` is used (parrot). |
| 25 | |
| 26 | Allowed types: `allay`, `bat`, `bee`, `blaze`, `chicken`, `baby_chicken`, `ghast`, `parrot`, `vex`. |
| 27 | |
| 28 | - `ghast` uses a baby `HAPPY_GHAST` (Ghastling). |
| 29 | - Visual mobs with a usable main-hand equipment slot show a visual copy of the shipment item. |
| 30 | - Bats are kept awake so they do not hang upside down mid-flight. |
| 31 | |
| 32 | ## Commands |
| 33 | |
| 34 | | Command | Permission | Default | Description | |
| 35 | |---|---|---|---| |
| 36 | | `/send <player>` | `birdcourier.send` | everyone | Send the held stack to an online player. | |
| 37 | | `/courier <type>` | `birdcourier.courier` | everyone | Set your personal courier mob. | |
| 38 | | `/birdcourier status` | `birdcourier.admin` | op | Show the number of active shipments. | |
| 39 | | `/birdcourier reload` | `birdcourier.admin` | op | Reload `config.yml`. | |
| 40 | |
| 41 | ## Configuration |
| 42 | |
| 43 | Defaults live in `config.yml` (copied to `plugins/BirdCourier/` on first run): |
| 44 | |
| 45 | - **visual** — default entity type (`PARROT`) and whether the courier is silent |
| 46 | - **flight** — visible speed (default 10 blocks/s), unloaded-chunk speed multiplier (5×), preferred height (10), direct-approach distance (15), delivery range, pathfinding limits |
| 47 | - **unreachable** — how long to wait and retry when the recipient cannot be reached |
| 48 | - **portals** — follow Nether/End portals (enabled by default) |
| 49 | - **persistence** — autosave interval for `shipments.tsv` |
| 50 | - **messages** — player-facing chat text |
| 51 | - **cleanup** — delayed cleanup of leftover courier visuals after chunk load; BirdCourier tags are authoritative, so ordinary invulnerable or no-gravity mobs are not removed |
| 52 | |
| 53 | Active shipments are stored in `plugins/BirdCourier/shipments.tsv`. Courier choices are stored in `plugins/BirdCourier/couriers.properties`. |
| 54 | |
| 55 | ## Build |
| 56 | |
| 57 | The project targets the official Paper 26.2 API build `26.2.build.112-stable` and Java 25. |
| 58 | |
| 59 | With Gradle installed: |
| 60 | |
| 61 | ```bash |
| 62 | gradle build |
| 63 | ``` |
| 64 | |
| 65 | The resulting JAR is `build/libs/BirdCourier-<version>.jar`. |
| 66 | |
| 67 | Run the unit tests with: |
| 68 | |
| 69 | ```bash |
| 70 | gradle test |
| 71 | ``` |
| 72 | |
| 73 | ## Releases |
| 74 | |
| 75 | On BlueGit, a master push runs the tests and builds the jar (no manual job). |
| 76 | Push a version tag (for example `1.1.4` or `v1.1.4`) to publish a release |
| 77 | automatically: the pipeline runs the tests, builds the jar, and attaches |
| 78 | `BirdCourier-<version>.jar` to the tag. A leading `v` on the tag is stripped |
| 79 | from the version and file name. |
| 80 | |
| 81 | ## Changelog |
| 82 | |
| 83 | ### 1.1.3 |
| 84 | |
| 85 | - Cleanup no longer removes legitimate courier-capable mobs merely for being invulnerable or gravity-disabled. |
| 86 | - Legacy ghost fallback now requires AI to be explicitly disabled. |
| 87 | - BirdCourier tags remain authoritative for cleanup. |
| 88 | |
| 89 | ### 1.1.2 |
| 90 | |
| 91 | - Phantom removed; chicken and baby_chicken added; bats forced awake. |
| 92 | |
| 93 | ### 1.1.1 / 1.1.0 |
| 94 | |
| 95 | - Adds `/courier <type>` with tab completion for allay, bat, bee, blaze, ghast, parrot, phantom and vex (phantom later removed in 1.1.2). |
| 96 | - Courier choice is stored per player in `couriers.properties`. |
| 97 | - `ghast` uses a baby `HAPPY_GHAST` (Ghastling). |
| 98 | - Visual mobs with a usable main-hand equipment slot receive a visual copy of the shipment item. |
| 99 | |
| 100 | ### 1.0.15 |
| 101 | |
| 102 | - Default visible speed: 10 blocks/second. |
| 103 | - Default unloaded travel multiplier: 5x. |
| 104 | - Default preferred flight height: 10 blocks. |
| 105 | - Default direct-approach distance: 15 blocks. |
| 106 | - Visual courier entities are non-persistent, so they are not saved into chunk data and later return as ghosts. |