HTAFKZone v1.0.6

HTAFKZones
AFK zone reward system for Hytale servers. Define a zone where players can stand still to earn timed rewards. A HUD progress bar shows time remaining until the next reward.

Features

• Define a rectangular AFK zone in any world
• Players standing still in the zone accumulate time toward rewards
• Moving resets the timer
• Leaving the zone clears the timer and hides the HUD
• HUD progress bar displays in center of screen: [||||||||||----------] 45s until Reward
• Customizable HUD colors, title, and time format (via config or admin UI)
• Rewards can be items or commands
• Rewards cycle — after all rewards are granted, it loops back to the first
• Inventory space check before granting item rewards (checks hotbar, storage, and backpack)
• If inventory is full, timer pauses and player gets a reminder every 5 seconds
• Sound effect and title text on reward claim
• Leaderboard UI showing top 10 AFK players and their accumulated time
• Full admin UI for managing zone, rewards, and HUD settings in-game
• Fully translatable (i18n language files)
• MultipleHUD plugin compatibility (auto-detected, no dependency required)

Setup Guide

1. Install the Plugin
Place HTAFKZones-1.0-SNAPSHOT.jar in your server's mods/ directory and restart.

2. Define the AFK Zone
Stand at one corner of your desired zone and run:

/htafk setpos1

Click to expand...

Walk to the opposite corner and run:

/htafk setpos2

Click to expand...

The zone is a rectangular box between these two corners. The world you're standing in is automatically saved as the zone world.

3. Add Rewards

Option A — Admin UI:

/htafk manage

Click to expand...

Opens a full management page where you can add, edit, and delete rewards with item/sound dropdowns and all settings.
Option B — Edit config directly:
Edit plugins/HTAFKZones/config.json and add rewards to the rewards array (see Config section below), then run:

/htafk reload

Click to expand...

4. Test It
Use /afk to teleport to the zone center, then stand still. You should see the HUD progress bar appear and fill up as time passes.

Commands
| Command | Description |
|---------|-------------|
| /afk | Teleport to the AFK zone center |
| /afktop | Open the AFK leaderboard showing top 10 players |
| /htafk setpos1 | Set zone corner 1 to your current position |
| /htafk setpos2 | Set zone corner 2 to your current position |
| /htafk reload | Reload the config and language files |
| /htafk manage | Open the admin management UI |
Aliases: /htafk can also be used as /htafkzones

Permissions
| Permission | Description | Level |
|-----------|-------------|-------|
| htafkzones.afk | Use /afk to teleport to the zone | User |
| htafkzones.afktop | Use /afktop to view the leaderboard | User |
| htafkzones.admin | Use /htafk parent command | Admin |
| htafkzones.admin.setpos1 | Set zone corner 1 | Admin |
| htafkzones.admin.setpos2 | Set zone corner 2 | Admin |
| htafkzones.admin.reload | Reload config | Admin |
| htafkzones.admin.manage | Open admin management UI | Admin |

Rewards
Rewards are granted in order of timeRequired (lowest first). After all rewards have been given, it loops back to the first. The timer resets after each reward.
Reward Types

ITEM - Gives the player an item directly into their inventory.

{
"name": "Gold Bricks",
"timeRequired": 60,
"type": "ITEM",
"itemId": "Rock_Gold_Brick_Smooth",
"amount": 5,
"titleText": "&6You earned {item}!",
"sound": "SFX_Player_Pickup_Item",
"soundVolume": 1.0,
"soundPitch": 1.0
}

Click to expand...

COMMAND - Runs one or more commands when the reward is claimed.

{
"name": "VIP Reward",
"timeRequired": 300,
"type": "COMMAND",
"commands": [
"console:give {player} Tool_Growth_Potion --quantity=1",
"player:me just got a reward!"
],
"titleText": "&aVIP Reward Claimed!",
"sound": "SFX_CHEST_LEGENDARY_FIRSTOPEN_PLAYER",
"soundVolume": 1.0,
"soundPitch": 1.0
}

Click to expand...

Reward Fields
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| name | string | "New Reward" | Display name shown in HUD and messages |
| timeRequired | int | 60 | Seconds of AFK time needed to earn this reward |
| type | string | "ITEM" | Reward type: ITEM or COMMAND |
| itemId | string | — | Item ID to give (ITEM type only). Example: Rock_Gold_Brick_Smooth |
| amount | int | 1 | Quantity of items to give (ITEM type only) |
| commands | string[] | — | Commands to run (COMMAND type only) |
| titleText | string | "&6You earned a reward!" | Title shown on screen. Supports color codes. {item} = reward name |
| sound | string | "SFX_Player_Pickup_Item" | Sound effect to play on reward claim |
| soundVolume | float | 1.0 | Sound volume (0.0 - 2.0) |
| soundPitch | float | 1.0 | Sound pitch (0.1 - 2.0) |

Command Prefixes
Commands in the commands array support two prefixes:
| Prefix | Description | Example |
|--------|-------------|---------|
| console: | Runs as server console (default) | console:give {player} Rock_Stone --quantity=10 |
| player: | Runs as the player | player:me is AFK farming! |
If no prefix is specified, the command runs as console.
Placeholder: {player} is replaced with the player's username.
### Inventory Space Check
For ITEM rewards, the plugin checks if the player has at least one empty slot across their hotbar (9 slots), storage grid (36 slots), and backpack before granting the reward. If inventory is full:

• The timer pauses at the reward threshold
• The player receives a reminder message every 5 seconds
• Once they free up space, the reward is granted automatically

Leaderboard
The /afktop command opens a UI page showing the top 10 players currently in the AFK zone, ranked by accumulated time (highest first).

• Top 3 players are highlighted with distinct colors (gold, silver, bronze)
• Ranks 4-10 shown in gray
• Time formatted as Xs, Xm Ys, or Xh Ym Zs
• Shows an empty state message if no players are in the zone
• Only shows players currently in the zone (not historical data)

Config File
Located at plugins/HTAFKZones/config.json. Created automatically on first run.

{
"language": "en",
"hudEnabled": true,
"movementThreshold": 0.1,
"hudTitle": "&7AFK Rewards",
"hudBarFilledColor": "&a",
"hudBarEmptyColor": "&8",
"hudBarBracketColor": "&7",
"hudTimeFormat": "{time} until {reward}",
"hudRewardMessage": "&aYou received: &6{reward}",
"zone": {
"world": "world_name",
"x1": 100.0, "y1": 65.0, "z1": 200.0,
"x2": 110.0, "y2": 75.0, "z2": 210.0
},
"rewards": [
{
"name": "Starter Pack",
"timeRequired": 60,
"type": "ITEM",
"itemId": "Rock_Gold_Brick_Smooth",
"amount": 5,
"titleText": "&6You earned {item}!",
"sound": "SFX_Player_Pickup_Item",
"soundVolume": 1.0,
"soundPitch": 1.0
},
{
"name": "Bonus Reward",
"timeRequired": 300,
"type": "COMMAND",
"commands": [
"console:give {player} Tool_Growth_Potion --quantity=1"
],
"titleText": "&aBonus Reward!",
"sound": "SFX_CHEST_LEGENDARY_FIRSTOPEN_PLAYER",
"soundVolume": 1.0,
"soundPitch": 1.0
}
]
}

Click to expand...

Config Settings
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| language | string | "en" | Language file to use (loads from plugins/HTAFKZones/lang/) |
| hudEnabled | boolean | true | Show/hide the progress bar HUD |
| movementThreshold | double | 0.1 | Distance in blocks before movement is detected and timer resets |

HUD Appearance Settings
These can be edited in the config file or via the admin UI (/htafk manage > HUD Settings section).
| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| hudTitle | string | &7AFK Rewards | Title text shown above the progress bar |
| hudBarFilledColor | string | &a | Color code for the filled portion of the bar |
| hudBarEmptyColor | string | &8 | Color code for the empty portion of the bar |
| hudBarBracketColor | string | &7 | Color code for the [ and ] brackets |
| hudTimeFormat | string | {time} until {reward} | Text shown below the progress bar |
| hudRewardMessage | string | &aYou received: &6{reward} | Chat message sent when a reward is claimed |

All Placeholders Reference
| Placeholder | Where Used | Description |
|-------------|-----------|-------------|
| {time} | hudTimeFormat | Time remaining until next reward (e.g., "2m 30s") |
| {reward} | hudTimeFormat, hudRewardMessage | Name of the next/claimed reward |
| {item} | Reward titleText | Display name of the reward (same as reward name) |
| {player} | Reward commands | The player's username |

Color Codes

All text fields support Minecraft-style color codes:
| Code | Color | Code | Color |
|------|-------|------|-------|
| &0 | Black | &8 | Dark Gray |
| &1 | Dark Blue | &9 | Blue |
| &2 | Dark Green | &a | Green |
| &3 | Dark Aqua | &b | Aqua |
| &4 | Dark Red | &c | Red |
| &5 | Dark Purple | &d | Pink |
| &6 | Gold | &e | Yellow |
| &7 | Gray | &f | White |
| &l | Bold | &o | Italic |
| &r | Reset | | |
Hex colors: &#RRGGBB (e.g., &#FF6600 for orange)

Language Files
Located at plugins/HTAFKZones/lang/en.json. Created automatically. Supports Minecraft-style color codes (&6, &a, etc.) and hex colors (&#RRGGBB).
All messages are customizable. Edit the language file and run /htafk reload.

Admin UI
Access via /htafk manage. The admin panel has three sections:
Zone Configuration

• Displays the current zone world, corner 1 and corner 2 coordinates (read-only)
• Use /htafk setpos1 and /htafk setpos2 in-game to set positions

HUD Settings

• Edit HUD title, bar colors (filled, empty, brackets), time format, and reward message
• Click "Save HUD Settings" to apply — players must re-enter the zone to see changes

Rewards Management

• View all configured rewards in a list with name, time, and type
• Add new rewards, edit existing ones, or delete them
• Reward editor includes:

- Name, time required, type dropdown (ITEM/COMMAND)
- Item selector with search filter and icon preview (for ITEM type)
- Command input with pipe-separated multiple commands (for COMMAND type)
- Title text, sound selector with filter, volume, and pitch


MultipleHUD Integration
If the MultipleHUD plugin is installed, HTAFKZones automatically uses it as the HUD provider. This allows the AFK progress bar to coexist with other HUD overlays.

• Detected automatically at startup via reflection
• Falls back to Hytale's built-in CustomUIHud if MultipleHUD is not present
• HUD ID: htafkzones_afk

How It Works
1. Every second, the plugin checks all players in the zone world
2. If a player is inside the zone bounds, their AFK timer starts
3. If the player moves more than movementThreshold blocks, the timer resets
4. When the timer reaches a reward's timeRequired, the reward is granted (with inventory check for items)
5. The timer resets and starts counting toward the next reward
6. After all rewards are given, it loops back to the first
7. Leaving the zone clears the timer entirely