Ohh Shiny

A Minecraft Fabric mod that allows server administrators to create interactive, one-time reward points that players can claim by right-clicking blocks in the world.

Features

Interactive Rewards: Create claimable reward locations anywhere in your Minecraft world
One-Time Claims: Each reward can only be claimed once per player
Visual Feedback: Particle effects for creating, removing, and claiming rewards
Block Protection: Rewards are protected from being broken
Permission System: Full LuckPerms integration for granular access control
Persistent Storage: All reward data is automatically saved to disk
Multi-Dimension Support: Place rewards in any dimension (Overworld, Nether, End, custom dimensions)
Custom Items: Built-in support for giving custom textured player heads (chests and pokeballs)

Requirements

Minecraft: 1.21.1
Fabric Loader: 0.17.2 or newer
Fabric API: Required
Fabric Language Kotlin: Required
Java: 21 or newer
LuckPerms: Optional (for advanced permission management)
TextPlaceholderAPI: Optional (for text formatting in language files)

Installation

Place the JAR file in your mods folder
(Optional) Install LuckPerms for advanced permission management
(Optional) Install TextPlaceholderAPI for text formatting
Start your server

Usage

Creating Rewards

Hold the item you want to give as a reward in your main hand
Run /ohhshiny set to enter setup mode
Right-click on any block to create a reward at that location
The reward is immediately saved and ready for players to claim

Note: Setup mode automatically exits after placing one reward. Run /ohhshiny set again to place another.

Removing Rewards

Run /ohhshiny remove to enter remove mode
Right-click on a block with an existing reward to delete it
The reward and all associated claim data are permanently removed

Note: Remove mode automatically exits after removing one reward.

Claiming Rewards

Players with claim permissions can simply right-click on any block that has a reward:

If they haven't claimed it before, they receive the reward item
If they've already claimed it, they see a message indicating they've already claimed it
If no reward exists at that location, normal block interactions occur

Administrative Commands

All commands require appropriate permissions (see Permissions section below).

`/ohhshiny set`

Enters setup mode to create a new reward location.

`/ohhshiny remove`

Enters remove mode to delete an existing reward location.

`/ohhshiny list`

Lists all active reward locations with details:

World dimension
Coordinates
Reward item
Number of players who have claimed it
Clickable teleport link for easy navigation

`/ohhshiny give chest <type>`

Gives a custom textured chest player head.

Types: copper, iron, gold
These are special items perfect for use as visually distinctive rewards

`/ohhshiny give pokeball <type>`

Gives a custom textured pokeball player head.

Types: poke, ultra, master
Great for themed servers or special events

`/ohhshiny reload`

Reloads all reward data from the configuration file on disk.

Useful for applying manual edits or recovering from errors
Shows the number of rewards loaded

`/ohhshiny reloadlang`

Reloads the language file (lang.json) without restarting the server.

Apply message customizations immediately
No server restart required

`/ohhshiny reset <player>`

Resets a specific player's claim history, allowing them to claim all rewards again.

Useful for testing or special events
Shows the number of claims reset

`/ohhshiny clearall`

DESTRUCTIVE: Permanently deletes all rewards and claim data.

Requires confirmation (run the command twice within 30 seconds)
This action cannot be undone
Use with extreme caution

Permissions

Ohh Shiny uses LuckPerms for permission management. If LuckPerms is not installed, all commands default to requiring operator status (level 2+).

Available Permissions

Permission	Description	Default
`ohhshiny.base`	Access to the base `/ohhshiny` command	OP
`ohhshiny.claim`	Ability to claim rewards by right-clicking blocks	OP
`ohhshiny.set`	Create new reward locations	OP
`ohhshiny.remove`	Delete existing reward locations	OP
`ohhshiny.list`	View all active reward locations	OP
`ohhshiny.give`	Spawn custom textured items	OP
`ohhshiny.reload`	Reload data from disk	OP
`ohhshiny.reset`	Reset player claim histories	OP
`ohhshiny.clearall`	Delete all reward data	OP

Permission Examples

To allow all players to claim rewards:

lp group default permission set ohhshiny.claim true

To give moderators full access except clearall:

lp group moderator permission set ohhshiny.base true
lp group moderator permission set ohhshiny.claim true
lp group moderator permission set ohhshiny.set true
lp group moderator permission set ohhshiny.remove true
lp group moderator permission set ohhshiny.list true
lp group moderator permission set ohhshiny.give true
lp group moderator permission set ohhshiny.reload true
lp group moderator permission set ohhshiny.reset true

To give admins complete access:

lp group admin permission set ohhshiny.* true

Language Configuration

All messages are fully configurable through a language file. The file is automatically created at:

config/ohhshiny/lang.json

Basic Usage

Edit the lang.json file to customize any message:

{
  "prefix": "&lt;aqua&gt;[Ohh Shiny]&lt;/aqua&gt;",
  "loot.claimed": "&lt;aqua&gt;You found something shiny: {item}!",
  "error.already_claimed": "&lt;red&gt;You've already claimed this!"
}

After editing, reload with:

/ohhshiny reloadlang

Text Formatting

Requires TextPlaceholderAPI (optional but recommended).

Colors:

<red>, <green>, <blue>, <yellow>, <aqua>, <gold>, etc.
Hex colors: <#FF0000>

Formatting:

<bold>, <italic>, <underline>, <strikethrough>

Advanced:

Gradients: <gradient:blue:aqua>text</gradient>
Rainbow: <rainbow>text</rainbow>
Hover: <hover:'tooltip text'>hover me</hover>

Placeholders:

Built-in: {x}, {y}, {z}, {item}, {player}, {count}
TextPlaceholderAPI: %player:name%, %server:tps%, etc.

Example:

{
  "prefix": "&lt;gradient:aqua:blue&gt;&lt;bold&gt;[Ohh Shiny]&lt;/bold&gt;&lt;/gradient&gt;",
  "loot.claimed": "&lt;rainbow&gt;✨ You found: {item}! ✨&lt;/rainbow&gt;"
}

Data Storage

All reward data is stored in JSON format at:

config/ohhshiny/ohhshiny.json

The file is automatically created on first use and updated whenever:

Rewards are created or removed
Players claim rewards
Data is manually reloaded

Data Structure

Each reward entry contains:

Location: Dimension and block coordinates
Reward Item: Serialized item data (type, count, NBT data)
Claimed Players: List of player UUIDs who have claimed this reward

You can manually edit this file, but remember to run /ohhshiny reload afterward to apply changes.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Authors

Destroyaa

Support

For bug reports, feature requests, or questions, please open an issue on the project repository.

Performance

Efficient storage: JSON-based with automatic saving
Thread-safe: Uses concurrent data structures where needed
Optimized particle effects: Runs on server tick with distance checks

Tips and Best Practices

Backup your data: Always backup config/ohhshiny/ohhshiny.json before major operations
Use custom items: The built-in chest and pokeball heads make rewards more visually appealing
Strategic placement: Place rewards in interesting or hard-to-reach locations
Regular reloads: If you manually edit the JSON file, always reload afterward
Permission hierarchy: Give players only the permissions they need
Testing: Use /ohhshiny reset to test rewards without creating new ones
Visual feedback: The particle effects help players know they've found something special

Troubleshooting

Players can't claim rewards

Verify they have the ohhshiny.claim permission
Check the server logs for permission errors
Ensure LuckPerms is properly configured

Rewards not saving

Check file permissions on the config/ohhshiny directory
Look for errors in the server console
Try manually running /ohhshiny reload

Rewards disappear after restart

Ensure the ohhshiny.json file exists and is not corrupted
Check that the mod loaded correctly during startup
Verify no other mods are interfering with the config directory

Particles not showing

Particles automatically load on server start (as of v1.1.0)
Particles only appear for players who haven't claimed the reward
Particles only render within 16 blocks of a player
Try running /ohhshiny reload if particles still don't appear

Ooh Shiny!