BlueGit

timfa birdcourier

Files

birdcourier / README.md

README.md

README.md 4.4 KiB Download Raw

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.

  • ghast uses a baby HAPPY_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

CommandPermissionDefaultDescription
/send <player>birdcourier.sendeveryoneSend the held stack to an online player.
/courier <type>birdcourier.couriereveryoneSet your personal courier mob.
/birdcourier statusbirdcourier.adminopShow the number of active shipments.
/birdcourier reloadbirdcourier.adminopReload 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.
  • ghast uses a baby HAPPY_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
3Paper 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
121. Build the plugin (see [Build](#build)) or take the `BirdCourier-<version>.jar` from a BlueGit pipeline artifact.
132. Place the jar in the server `plugins/` folder.
143. Start or restart the Paper server.
154. Optional: edit `plugins/BirdCourier/config.yml`, then run `/birdcourier reload`.
16
17## Playing
18
191. Hold the stack you want to send in your main hand.
202. Run `/send <player>`. The other player must be online; you cannot send to yourself.
213. A courier spawns near you and flies to the recipient (including through unloaded chunks, and through Nether/End portals when enabled).
224. 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
24Pick 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
26Allowed 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
43Defaults 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
53Active shipments are stored in `plugins/BirdCourier/shipments.tsv`. Courier choices are stored in `plugins/BirdCourier/couriers.properties`.
54
55## Build
56
57The project targets the official Paper 26.2 API build `26.2.build.112-stable` and Java 25.
58
59With Gradle installed:
60
61```bash
62gradle build
63```
64
65The resulting JAR is `build/libs/BirdCourier-<version>.jar`.
66
67Run the unit tests with:
68
69```bash
70gradle test
71```
72
73## Releases
74
75On BlueGit, a master push runs the tests and builds the jar (no manual job).
76Push a version tag (for example `1.1.4` or `v1.1.4`) to publish a release
77automatically: 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
79from 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.