BirthdayGift

Rewards players on their birthday and announces it to the network.

The plugin is split into a backend half and a proxy half, which talk over a plugin message channel:

Module	Runs on	Responsibility
Bukkit	Paper backend servers	All player interaction: commands, item and money rewards
Velocity	The proxy	All state: the MySQL database and the network-wide birthday announcement
Bungee	legacy	The old BungeeCord proxy plugin, replaced by Velocity

Players set their birthday once and, on that day, claim a one-off gift of items and/or money. The proxy owns the data so a birthday is network-wide rather than per-server.

The Bungee module is deprecated. It only runs on Velocity through the discontinued Snap compatibility plugin. Use the Velocity module instead; see Migrating from the BungeeCord module.

Building

mvn clean package

Requires JDK 25 or newer, because the Velocity module targets Velocity 4.x. The reactor compiles each module at its own level: Bukkit at Java 21, Velocity at Java 25, and the legacy Bungee module at Java 8.

Artifacts:

• Bukkit/target/BirthdayGift-Bukkit-<version>.jar goes on each backend server
• Velocity/target/BirthdayGift-Velocity-<version>.jar goes on the proxy

The Velocity jar shades HikariCP and the MySQL driver (relocated under au.com.addstar.birthdaygift.lib), since Velocity ships neither.

Requirements

• Velocity 4.x on Java 25 (proxy)
• Paper 1.21.11+ (backends)
• MySQL, reachable from the proxy only
• Vault on the backends, for money rewards (optional)

Commands

All commands run on the backend servers.

/birthday [date]

• /birthday shows your birthday, or tells you how to set it.
• /birthday <date> sets it. The format is DD-MM-YYYY by default, or MM-DD-YYYY when us-date-format is true. -, / and . all work as separators, so 1/8/1990 and 1-8-1990 are equivalent.

A birthday can only be set once - players cannot change it afterwards, and cannot set it to today. Requires birthdaygift.use.

/bgift <subcommand> (alias /birthdaygift)

Subcommand	Description	Permission
claim	Claim today's birthday gift	birthdaygift.claim
info <player>	Show a player's birthday record and age	birthdaygift.info
stats	Show network birthday statistics	birthdaygift.stats
set <player> <date>	Set a player's birthday	birthdaygift.set
reset <player>	Clear a player's claim so they can claim again	birthdaygift.reset
delete <player>	Delete a player's birthday record	birthdaygift.delete
addreward	Add the item in your hand to the reward list	birthdaygift.reward.add
listreward	List the configured reward items	birthdaygift.reward.list
deletereward <index>	Remove a reward item by its index (1-based)	birthdaygift.reward.delete

Permissions

Permission	Default	Gates
birthdaygift.*	op	All of the below
birthdaygift.use	everyone	/birthday
birthdaygift.claim	everyone	/bgift claim. Restrict per-world to limit where gifts can be claimed
birthdaygift.info	op	/bgift info
birthdaygift.stats	op	/bgift stats
birthdaygift.set	op	/bgift set
birthdaygift.reset	op	/bgift reset
birthdaygift.delete	op	/bgift delete
birthdaygift.reward.add	op	/bgift addreward
birthdaygift.reward.list	op	/bgift listreward
birthdaygift.reward.delete	op	/bgift deletereward
birthdaygift.silent	false	Suppresses the birthday announcement for that player. Checked on the proxy

Configuration

Proxy: plugins/birthdaygift/config.yml

Key	Default	Meaning
debug	false	Verbose logging
database.host	localhost	MySQL host
database.port	3306	MySQL port
database.database	birthdaygift	Schema name
database.user	username	MySQL user
database.password	password	MySQL password
database.use-ssl	false	Use SSL for the connection
database.pool-size	4	Maximum HikariCP pool size
database.connection-timeout	10000	Connection timeout, milliseconds

The birthdaygift table is created automatically if it does not exist.

Proxy: plugins/birthdaygift/messages.yml

Written in MiniMessage. Legacy & colour codes are not supported. <player> is replaced with the player's name, already coloured aqua. Set a message to '' to disable it.

Key	Meaning
announcement	Broadcast to the network when a player joins on their birthday
claim	Sent to the birthday player reminding them to claim

Backend: plugins/BirthdayGift/config.yml

Key	Default	Meaning
debug	false	Verbose logging
money	1000	Money awarded on a birthday. 0 disables. Needs Vault
us-date-format	false	true for MM-DD-YYYY, false for DD-MM-YYYY
messages.gift		Sent when the gift is claimed
messages.money		Sent when money is awarded. <MONEY> is substituted
messages.noclaimpermission		Sent when the player lacks birthdaygift.claim
items-serialized		Reward items, as serialized ItemStacks. Manage with /bgift addreward and /bgift deletereward
items		Deprecated legacy reward list. Use items-serialized

Backend messages still use legacy & colour codes.

Notable behaviour

• The announcement fires once per birthday. It is delayed about a second after login so it lands as the last thing on the player's screen.
• Announcing and claiming are tracked separately (lastAnnounced, lastGift), so a player who is announced but never claims still gets counted as unclaimed in /bgift stats.
• If the proxy cannot reach the database, the proxy still starts and logins are unaffected; BirthdayGift simply stays inactive.
• Claiming fires a BirthdayEvent on the backend so other plugins can hook in and grant their own rewards.

How the two halves talk

Over the plugin message channel bungee:gift. The backend sends Set, Get, Claim, ResetClaim, Stats and Del; the proxy replies to the originating server with ^Get, ^Claim and ^Stats. Requests time out after 5 seconds.

Because a plugin message needs a player to carry it, backend commands only work while at least one player is online on that server.

This wire format is a compatibility contract. The Velocity module speaks it byte-for-byte identically to the old BungeeCord module, so the backend plugin did not change during the migration. Do not alter it on one side alone.

Migrating from the BungeeCord module

The Velocity module is a drop-in functional replacement, but it is configured differently. The database is reused as-is - the schema is unchanged and no data migration is needed.

1. Make sure the proxy runs Velocity 4.x on Java 25.
2. Remove BirthdayGift-Bungee.jar and, once your other plugins allow it, Snap.
3. Install BirthdayGift-Velocity.jar and start the proxy once. It writes a default config.yml and messages.yml into plugins/birthdaygift/.
4. Port your settings across. config.properties is not read: copy the host, port, database, user and password values into the database block of the new config.yml.
5. Port your messages. bgift_messages.properties is not read, and its & colour codes are no longer supported: rewrite announcement and claim as MiniMessage in messages.yml, replacing <PLAYER> with <player>.
6. Restart the proxy and confirm the log shows BirthdayGift is enabled.

The backend plugin needs no changes.