Goals

🎯 Playtime Goals Tutorial

Welcome to the PlayTimeManager Goal System! This guide walks you through creating, managing, and customizing playtime goals to reward your players for their dedication.

---

⚠️ IMPORTANT ⚠️

🚨 CHAT-BASED INPUT COMPATIBILITY
If the chat-based input system doesn't work properly in your server environment, please read here.

🔐 ADMINISTRATOR ACCESS ONLY
The goal management GUI (/playtimegoal) is designed exclusively for server administrators. Only grant the playtime.goal permission to trusted staff members, as users with this permission can create, modify, or delete goals and execute powerful reward commands.

---

📘 What Are Playtime Goals?

Playtime goals are milestones based on configurable requirements. When a player meets all configured requirements, the plugin automatically executes all configured rewards.

Goals can be configured as repeatable or one-time. Repeatable goals allow players to complete the same goal multiple times, while one-time goals can only be completed once per player.

Requirements can include:

• ⏱️ Specific amount of playtime (optional)
• 🔑 Required permissions or group memberships
• 📊 Placeholder conditions using PAPI placeholders

Rewards can include:

• ✅ Granting permissions and groups (via LuckPerms)
• 🛠️ Executing commands
• 💬 Sending messages
• 🔊 Playing sounds

Everything can be configured visually through the in-game GUI, making it user-friendly and efficient.

---

🚀 Getting Started

To open the goal management interface, use:

/playtimegoal

Permission: playtime.goal
Default Access: ❌ Disabled by default

This GUI allows you to create, edit, and activate goals, assign rewards, and manage player progression with ease.

---

⚒️ Creating a New Goal

To create a new goal:

1. Open the goal management GUI with /playtimegoal
2. Click the "Create New Goal" button
3. Follow the chat prompts to enter the goal name

⚠️ If the chat input doesn’t work due to compatibility issues, use the /playtimegoal create command instead.
In this case, you’ll need to manually edit the goal’s settings in its corresponding YAML configuration file.

1. Configure requirements and rewards through the goal settings GUI

---

⚙️ Goal Settings

Each goal has different configuration sections accessible through the goal settings GUI:

⏱️ Completion check Section

Each goal has its own individual check rate that can be configured through the goal settings GUI.

The completion check time rate can be configured in two formats:

FORMAT 1 - SECONDS (Simple Number)

This format requires entering a number representing seconds (e.g., 900 for 15 minutes), the check starts counting immediately after server reload/restart, subsequent checks occur every X seconds from the first check.

check-time-interval: '900' #will execute each 900 seconds after server startup

With this format, check-time-timezone field will be ignored.

FORMAT 2 - CRON EXPRESSION (Scheduled Times)

This format requires entering a cron schedule with the format:

<seconds> <minute> <hour> <day-of-month> <month> <day-of-week>

Checks will then occur at fixed times regardless of server restarts.

I suggest using this website: https://www.freeformatter.com/cron-expression-generator-quartz.html or ChatGPT for generating such schedules (use the keyword 'quartz cron format').

Examples:

check-time-interval: '0 */15 * * * ?' #will execute every 15 minutes at fixed times 

check-time-interval: '0 0 0 * * ?' #will execute daily at midnight (00:00)

check-time-interval: '0 0 0 ? * MON' #will execute weekly on Monday at midnight

check-time-interval: '0 0 0 1 * ?' #will execute monthly on the 1st at midnight

In case of this format, the check-time-timezone field will be used to determine whether to use server timezone or UTC for cron scheduling:

check-time-timezone: server #(default)
#or
check-time-timezone: utc

📋 Requirements Section

Requirements determine what conditions must be met for a player to achieve the goal. All configured requirements must be satisfied for the goal to be completed.

⏱️ Time Requirement

• Set a specific amount of playtime required
• Time format supports: y (years), d (days), h (hours), m (minutes), s (seconds)
• Example: 40d for 40 days, 5h,30m for 5 hours and 30 minutes

🔑 Permission Requirements

• Require players to have specific permissions or group memberships
• Example: group.newbie to require players to be in the "newbie" group

📊 Placeholder Conditions

• Create powerful boolean conditions using PAPI placeholders
• Supports placeholders from PlayTimeManager and other plugins
• Uses two-operand expressions with these operators:
  • == (equals)
  • != (not equals)
  • > (greater than)
  • < (less than)
  • >= (greater than or equal)
  • <= (less than or equal)

Special Placeholder: PLAYER_NAME can be used to compare against the current player's name.

Placeholder Condition Examples:

%PTM_nickname_top_1% == PLAYER_NAME

Only gives the goal to the #1 player on the playtime leaderboard

%player_exp% >= 50

Requires the player to be level 50 or higher (using PlaceholderAPI's official placeholders)

%vault_eco_balance% > 10000

Requires the player to have more than $10,000 (using Vault economy placeholder)

🎁 Rewards Section

Configure what happens when a player completes the goal:

• ✅ Permission Rewards: Grant permissions and groups automatically thanks to a LuckPerms integration
• 🛠️ Commands: Execute server commands (using the PLAYER_NAME special placeholder for player name)
• 💬 Messages: Send custom messages to the player
• 🔊 Sounds: Play sounds for the player

📦 Offline Rewards

Control how rewards are handled for offline players:

offline-rewards: true

If true,Players who are offline when completing the goal will receive rewards when they next log in.

⚠️ Important Limitation:

Currently, for performance reasons, only players who were online during the last completion check interval are eligible for offline rewards. For example, if the goal is checked daily and a player does not join within that day, they will not receive the reward even if offline-rewards is enabled.

🧍 Per-Player Check

By default, a goal runs a single shared completion check for all online players at once, on the schedule set in the Completion Check section. You can instead give each player their own individual check timer:

per-player-check: true

If true, instead of one check running for everyone at the same time, each player gets their own check task using the same check-time-interval, starting when they join and stopping when they leave. This spreads the check load out over time instead of checking every online player at the same instant.

⚠️ Important Limitation:

offline-rewards has no effect while per-player check is enabled, since a player's check task only exists while they are online — there's no shared "last check window" to catch players who joined and left while offline.

This can also be toggled from the goal settings GUI (look for the "Per-Player" button).

🔄 Activation & Repeatability

Each goal can be toggled on or off, and configured to be repeatable or one-time.

active: true #Determines whether this goal is enabled and tracked by the plugin.

repeatable: false #Determines if a goal can be completed multiple times by the same player.

🎨 Customizations

You can customize sounds and messages shown when a player completes a goal.

goal-sound: ENTITY_PLAYER_LEVELUP

goal-message: "&6Congratulations %PLAYER_NAME%! You completed %GOAL_NAME%!"

Available placeholders for message:

• %PLAYER_NAME% → Player’s name

• %GOAL_NAME% → Goal name

• %TIME_REQUIRED% → Time required to complete the goal

🧪 Examples

Rather than walking through every GUI click, here's what each goal's .yml file looks like once configured — build it with /playtimegoal → Create New Goal, then match these values in the settings GUI (or edit the file directly and reload).

Veteran Goal

Rewards players in the member group once they've played 40 days.

# Goals/veteran.yml
active: true
repeatable: false
offline-rewards: false
check-time-interval: '900'       # checked every 15 minutes
check-time-timezone: server
per-player-check: false
verbose: false
goal-sound: ENTITY_PLAYER_LEVELUP
goal-message: '&6Congratulations! You are now a server Veteran!'
requirements:
  time: 3456000                  # 40d, stored in seconds
  permissions:
  - group.member
  placeholders: []
rewards:
  permissions:
  - group.veteran
  commands:
  - /give PLAYER_NAME diamond 64

Top Player Goal

Awarded to the #1 player on the playtime leaderboard every Monday at midnight — even if they're offline, as long as they logged in at least once that week.

# Goals/top_player.yml
active: true
repeatable: true
offline-rewards: true
check-time-interval: '0 0 0 ? * MON'   # every Monday at midnight
check-time-timezone: server
per-player-check: false                # required: offline-rewards needs the shared check
verbose: false
goal-sound: ENTITY_PLAYER_LEVELUP
goal-message: '&6&lYou are the ultimate playtime champion!'
requirements:
  permissions: []
  placeholders:
  - '%PTM_nickname_top_1% == PLAYER_NAME'
rewards:
  permissions: []
  commands:
  - /broadcast PLAYER_NAME is our playtime champion!

No requirements.time set here — the goal has no playtime requirement of its own, only the placeholder condition decides completion.

Playtime Cash Goal

Gives every player $1000 for each 5 minutes they spend online — a simple play-to-earn loop.

# Goals/playtime_cash.yml
active: true
repeatable: true
offline-rewards: false
check-time-interval: '300'       # fires every 5 minutes, per player
check-time-timezone: server
per-player-check: true
verbose: false
goal-sound: ENTITY_EXPERIENCE_ORB_PICKUP
goal-message: '&aYou earned &f$1000&a for your playtime!'
requirements:
  permissions: []
  placeholders: []
rewards:
  permissions: []
  commands:
  - /eco give PLAYER_NAME 1000

No requirements.time set — the reward isn't gated by a playtime threshold, it's driven entirely by the check schedule: with per-player-check: true and check-time-interval: '300', every player gets their own recurring check every 5 minutes of their session, and since the goal is repeatable with no other requirement, it pays out on every one of those checks. offline-rewards must stay false here — it has no effect once per-player-check is on.

---