WelcomeReward

A Minecraft Paper plugin that rewards players who welcome newcomers to the server.

Description

WelcomeReward encourages a friendly community by rewarding the first players who welcome new members. When a new player joins the server, the first few players (configurable) who send a welcome message in chat will receive rewards.

Features

• Automatic Rewards: First players to welcome newcomers get rewards
• Fully Configurable: Customize greetings, rewards, and limits
• Multi-Language Support: Regex-based greeting detection supports multiple languages
• Session Tracking: Time-limited welcome sessions for each newcomer
• Smart Detection: Prevents spam and duplicate welcomes
• Character Limit: Configurable maximum message length (default: 32 characters)

Requirements

• Minecraft Version: 1.20.6+
• Server Software: Paper/Purpur/Pufferfish
• Java Version: 21

Installation

1. Download the latest welcomereward-1.0-SNAPSHOT.jar from releases
2. Place the JAR file in your server's plugins folder
3. Restart or reload your server
4. Configure the plugin in plugins/WelcomeReward/config.yml
5. Reload the plugin with /wr reload

Configuration

Default config.yml

settings:
  # Maximum welcome chat characters (including symbols)
  max-characters: 32

  # Number of fastest players who can get rewards
  max-winners: 4

  # Welcome session duration in seconds
  session-duration: 60

  # Enable/disable broadcast messages
  # Set to false to disable all broadcast announcements
  enable-broadcasts: true

  # Regex pattern to detect welcome messages
  # Supports: welcome, selamat datang, met gabung, hi, halo, etc.
  welcome-regex: "^(?i)(welcome|selamat datang|met gabung|met join|wilujeng|halo|hi|hai|yo welcome|wb|hallo).*"

messages:
  # Message when receiving reward
  reward-received: "&a✓ Thanks for welcoming! You are the &e%pos% &ato welcome &f%newcomer%&a."

  # Message when too late
  too-late: "&c✗ Too bad, %max% people already welcomed %newcomer% before you!"

  # Broadcast when a new player joins
  # Only shown if enable-broadcasts is true
  newcomer-join: "&e&l✦ &6New player &f%player% &6has joined! &eWelcome them! &7(%max% fastest get rewards)"

  # Broadcast when someone welcomes
  # Only shown if enable-broadcasts is true
  welcome-broadcast: "&a✓ &f%player% &awelcomed &f%newcomer% &a(#%pos%/%max%)"

rewards:
  commands:
    - "give %player% diamond 1"
    - "eco give %player% 100"

Configuration Options

Broadcast Control

The enable-broadcasts setting controls whether broadcast messages are sent to all players:

• true (default): Broadcasts are enabled

  • Players see when newcomers join
  • Players see when someone welcomes a newcomer
  • Creates a more social and engaging experience

• false: Broadcasts are disabled

  • No public announcements when newcomers join
  • No public announcements when someone welcomes
  • Rewards still work silently - only the welcomer receives a confirmation message
  • Useful for servers that prefer minimal chat spam

Example use cases for disabling broadcasts:

• Busy servers with frequent new players
• Servers that want rewards without public announcements
• Servers with custom welcome messages that conflict with plugin broadcasts

Placeholders

Available placeholders in messages:

• %player% - The greeter's name
• %newcomer% - The newcomer's name
• %pos% - Position order (1, 2, 3, 4...)
• %max% - Maximum number of winners

Customizing Welcome Regex

The welcome-regex setting uses Java regex patterns to detect welcome messages. You can customize it to match your server's language:

# English only
welcome-regex: "^(?i)(welcome|hi|hello|hey).*"

# Multiple languages
welcome-regex: "^(?i)(welcome|bienvenue|bienvenido|willkommen|benvenuto).*"

# Add custom phrases
welcome-regex: "^(?i)(welcome|hey there|greetings|what's up).*"

Tips:

• (?i) makes the pattern case-insensitive
• Use | (pipe) to separate multiple variations
• .* matches any text after the greeting
• Test your regex at regex101.com

Customizing Rewards

Rewards are executed as console commands. You can add any command your server supports:

rewards:
  commands:
    - "give %player% diamond 1"                    # Give items
    - "eco give %player% 100"                      # Give money (Vault required)
    - "lp user %player% permission set vip.perk"   # Give permissions (LuckPerms)
    - "points give %player% 10"                    # Give custom points
    - "crate key give %player% vote 1"            # Give crate keys

Commands

Command	Aliases	Description	Permission
/welcomereward reload	/wr reload	Reload configuration	welcomereward.reload
/welcomereward status	/wr status	View plugin status	welcomereward.admin

Permissions

Permission	Description	Default
welcomereward.admin	Access all WelcomeReward commands	op
welcomereward.reload	Reload plugin configuration	op

How It Works

1. New Player Joins: When a player joins for the first time, a welcome session is created
2. Broadcast (optional): If broadcasts are enabled, all online players (except the newcomer) see a message encouraging them to welcome the new player
3. Welcome Messages: Players who send matching welcome messages (within character limit) in chat are detected
4. Rewards: The first X players (configurable, default 4) to welcome receive rewards
5. Session Ends: After the configured duration (default 60 seconds), the session closes

Building from Source

Prerequisites

• JDK 21 or higher
• Maven 3.9.12 or higher

Build Steps

# Clone the repository
git clone <repository-url>
cd welcomereward

# Build with Maven
mvn clean package

# JAR file will be in target/welcomereward-1.0-SNAPSHOT.jar

Support

For bug reports, feature requests, or questions:

• Check existing issues on GitHub
• Create a new issue with detailed information
• Include server version, Java version, and error logs

License

This project is licensed under the MIT License.

---