# SaturnAPI
**A lightweight Heart management API for Minecraft developers.**
---
## Overview
SaturnAPI is a powerful and easy-to-use API that allows developers to manage player hearts on their Minecraft server. Whether you want to add a custom health system, create a heart shop, or integrate hearts into your own plugin, SaturnAPI provides a clean and reliable solution.
No complicated setup. No heavy dependencies. Just drop it in and use the API.
---
## Features
- Full Heart Management API
- Custom Events (SaturnHeartChangeEvent)
- PlaceholderAPI Support
- Developer-Friendly API
- YAML Storage
- Configurable Min/Max Hearts
- Configurable Default Hearts
- Lightweight
- No Dependencies (except PlaceholderAPI optional)
---
## Compatibility
- Minecraft Versions: 1.13 to 1.21+
- Server Software: Spigot, Paper, Purpur, Bukkit
- Java: Java 17 or higher
---
## Installation
1. Download the latest release
2. Place the JAR file into your server's plugins folder
3. Restart your server
4. Configure min/max/default hearts in config.yml
5. Start using the API in your own plugins
---
## Commands and Permissions
Player Commands:
- /hearts — Show your current hearts
Admin Commands:
- /saturnapi — Show plugin information
- /saturnapi reload — Reload config
- /saturnapi give <player> <amount> — Give hearts
- /saturnapi take <player> <amount> — Take hearts
- /saturnapi set <player> <amount> — Set hearts
Permissions:
- saturnapi.admin — Admin commands (default: op)
---
## Developer API
Adding SaturnAPI to your project:
```java
import ir.UxcYT.api.SaturnProvider;
```
Available Methods:
- getHearts(Player) — Get player hearts
- getHearts(UUID) — Get hearts by UUID
- setHearts(Player, int) — Set hearts
- addHearts(Player, int) — Add hearts
- removeHearts(Player, int) — Remove hearts
- resetHearts(Player) — Reset to default
- getMaxHearts() — Get max hearts
- getMinHearts() — Get min hearts
Custom Event:
```java
@EventHandler
public void onHeartChange(SaturnHeartChangeEvent event) {
Player player = event.getPlayer();
int oldHearts = event.getOldHearts();
int newHearts = event.getNewHearts();
if (newHearts > 20) {
event.setCancelled(true);
}
}
```
---
## PlaceholderAPI
If PlaceholderAPI is installed, you can use the following placeholders:
- %saturnapi_hearts% — Current hearts
- %saturnapi_hearts_display% — Hearts with heart symbol
- %saturnapi_hearts_bar% — Heart bar display
- %saturnapi_max_hearts% — Maximum hearts
- %saturnapi_min_hearts% — Minimum hearts
- %saturnapi_hearts_left% — Remaining hearts
- %saturnapi_hearts_percent% — Hearts percentage
- %saturnapi_default_hearts% — Default hearts
---
## Configuration
The config.yml file contains:
- min-hearts — Minimum hearts (default: 1)
- max-hearts — Maximum hearts (default: 40)
- default-hearts — Default hearts for new players (default: 10)
---
## Examples
Getting player hearts in your plugin:
```java
int hearts = SaturnProvider.getHearts(player);
player.sendMessage("You have " + hearts + " hearts!");
```
Adding hearts to a player:
```java
SaturnProvider.addHearts(player, 5);
player.sendMessage("You received 5 extra hearts!");
```
Using placeholders in a scoreboard:
```
Hearts: %saturnapi_hearts_display%
Bar: %saturnapi_hearts_bar%
```
---
## Why Choose SaturnAPI
- Clean and simple API
- Full documentation for developers
- Custom events for integration
- PlaceholderAPI support
- Works on almost every Minecraft version
- Minimal performance impact
- Fully open for customization
---
## Support
For issues, suggestions, or feature requests:
- Open a ticket on the discussion page
- Report bugs with detailed information
- Include your server version and any error logs
---
## Terms of Use
- Do not redistribute or resell this plugin without permission
- Do not claim this plugin as your own
- Credit must be given to the original author
---
## Author
UxcYT
---
## License
This project is licensed under the MIT License.
---
If you find this plugin useful, consider leaving a review or rating. Your feedback helps improve future updates.
**A lightweight Heart management API for Minecraft developers.**
---
## Overview
SaturnAPI is a powerful and easy-to-use API that allows developers to manage player hearts on their Minecraft server. Whether you want to add a custom health system, create a heart shop, or integrate hearts into your own plugin, SaturnAPI provides a clean and reliable solution.
No complicated setup. No heavy dependencies. Just drop it in and use the API.
---
## Features
- Full Heart Management API
- Custom Events (SaturnHeartChangeEvent)
- PlaceholderAPI Support
- Developer-Friendly API
- YAML Storage
- Configurable Min/Max Hearts
- Configurable Default Hearts
- Lightweight
- No Dependencies (except PlaceholderAPI optional)
---
## Compatibility
- Minecraft Versions: 1.13 to 1.21+
- Server Software: Spigot, Paper, Purpur, Bukkit
- Java: Java 17 or higher
---
## Installation
1. Download the latest release
2. Place the JAR file into your server's plugins folder
3. Restart your server
4. Configure min/max/default hearts in config.yml
5. Start using the API in your own plugins
---
## Commands and Permissions
Player Commands:
- /hearts — Show your current hearts
Admin Commands:
- /saturnapi — Show plugin information
- /saturnapi reload — Reload config
- /saturnapi give <player> <amount> — Give hearts
- /saturnapi take <player> <amount> — Take hearts
- /saturnapi set <player> <amount> — Set hearts
Permissions:
- saturnapi.admin — Admin commands (default: op)
---
## Developer API
Adding SaturnAPI to your project:
```java
import ir.UxcYT.api.SaturnProvider;
```
Available Methods:
- getHearts(Player) — Get player hearts
- getHearts(UUID) — Get hearts by UUID
- setHearts(Player, int) — Set hearts
- addHearts(Player, int) — Add hearts
- removeHearts(Player, int) — Remove hearts
- resetHearts(Player) — Reset to default
- getMaxHearts() — Get max hearts
- getMinHearts() — Get min hearts
Custom Event:
```java
@EventHandler
public void onHeartChange(SaturnHeartChangeEvent event) {
Player player = event.getPlayer();
int oldHearts = event.getOldHearts();
int newHearts = event.getNewHearts();
if (newHearts > 20) {
event.setCancelled(true);
}
}
```
---
## PlaceholderAPI
If PlaceholderAPI is installed, you can use the following placeholders:
- %saturnapi_hearts% — Current hearts
- %saturnapi_hearts_display% — Hearts with heart symbol
- %saturnapi_hearts_bar% — Heart bar display
- %saturnapi_max_hearts% — Maximum hearts
- %saturnapi_min_hearts% — Minimum hearts
- %saturnapi_hearts_left% — Remaining hearts
- %saturnapi_hearts_percent% — Hearts percentage
- %saturnapi_default_hearts% — Default hearts
---
## Configuration
The config.yml file contains:
- min-hearts — Minimum hearts (default: 1)
- max-hearts — Maximum hearts (default: 40)
- default-hearts — Default hearts for new players (default: 10)
---
## Examples
Getting player hearts in your plugin:
```java
int hearts = SaturnProvider.getHearts(player);
player.sendMessage("You have " + hearts + " hearts!");
```
Adding hearts to a player:
```java
SaturnProvider.addHearts(player, 5);
player.sendMessage("You received 5 extra hearts!");
```
Using placeholders in a scoreboard:
```
Hearts: %saturnapi_hearts_display%
Bar: %saturnapi_hearts_bar%
```
---
## Why Choose SaturnAPI
- Clean and simple API
- Full documentation for developers
- Custom events for integration
- PlaceholderAPI support
- Works on almost every Minecraft version
- Minimal performance impact
- Fully open for customization
---
## Support
For issues, suggestions, or feature requests:
- Open a ticket on the discussion page
- Report bugs with detailed information
- Include your server version and any error logs
---
## Terms of Use
- Do not redistribute or resell this plugin without permission
- Do not claim this plugin as your own
- Credit must be given to the original author
---
## Author
UxcYT
---
## License
This project is licensed under the MIT License.
---
If you find this plugin useful, consider leaving a review or rating. Your feedback helps improve future updates.
Quick facts
- Edition: Minecraft Java
- File type: .jar
- Minecraft versions listed: 1.8, 1.21
- How to install: Install the matching mod loader (Forge, Fabric or NeoForge) for your Minecraft version. → Download the .jar. → Put it in the .minecraft/mods folder and launch that loader profile.
- Where to get it: Opens on Spigot — not every file is mirrored on our own servers.
Install steps are the general flow for this file type — How to install Minecraft Java mods & modpacks walks through it step by step.
SaturnAPI | Best heart api for developers is a free Minecraft Java mod. Compatible with Minecraft 1.8, 1.21. Downloaded 3 times (via Spigot). Download it and open it directly in the game.