Overview#
AppleCore is a fundamental library mod designed to expose and modify the underlying hunger and food mechanics of Minecraft. While it does not add new food items or mobs on its own, it acts as a critical bridge for complex gameplay overhauls. It provides a unified API for developers to change how food restores hunger, how saturation behaves, and how plant growth is calculated.
For players, AppleCore (and its visual counterpart features) provides much-needed transparency to the hunger system by displaying hidden values like saturation and exhaustion directly on the HUD. This allows for more strategic decision-making regarding when to eat and which foods to prioritize based on their nutritional value.
Visual Features & HUD Improvements#
AppleCore introduces several visual enhancements to the standard Minecraft interface to help players track their nutritional status. These features are highly compatible with most modded food items.
Food Value Tooltips
When hovering over a food item in the inventory and holding the Shift key, a tooltip appears showing the exact amount of hunger and saturation that item will restore.
Hunger & Saturation Overlay
When a player holds a food item in their hand, the hunger bar will display flashing icons representing the potential hunger and saturation that would be restored upon eating. This allows players to see if they are about to waste food by overeating.
- Hunger Restoration: Represented by flashing meat shank icons.
- Saturation Restoration: Represented by a yellow/gold border or highlight around the hunger icons.
Exhaustion Underlay
Exhaustion is a hidden mechanic that determines when your hunger or saturation will next drop. AppleCore visualizes this as a progress bar or a "grid" pattern behind the hunger bar. As you perform actions like sprinting or jumping, this bar fills up. Once it reaches its maximum, it resets and consumes a point of saturation or hunger.
Mechanics#
AppleCore modifies the internal logic of the FoodStats class to allow for dynamic changes. Below are the core mechanics it manages:
Hunger and Saturation
In vanilla Minecraft, saturation is a hidden value that must be depleted before the hunger bar starts to shake and drop. AppleCore makes this relationship explicit and allows other mods to cap or scale these values.
| Mechanic | Description | Range |
|---|---|---|
| Hunger | The visible bar; determines health regeneration and sprinting ability. | 0 - 20 |
| Saturation | A hidden buffer that prevents hunger loss. Cannot exceed current hunger level. | 0 - 20 |
| Exhaustion | A counter that increases with physical activity. | 0.0 - 4.0 |
Exhaustion Rates
Every action in the game contributes to exhaustion. AppleCore tracks these values precisely:
| Action | Exhaustion Increase |
|---|---|
| Walking (per meter) | 0.01 |
| Sprinting (per meter) | 0.1 |
| Swimming (per meter) | 0.01 |
| Jumping | 0.05 |
| Sprint-Jumping | 0.2 |
| Breaking a Block | 0.005 |
| Attacking an Enemy | 0.1 |
| Receiving Damage | 0.1 |
| Health Regeneration | 6.0 (per half-heart) |
Plant Growth Integration
AppleCore provides a PlantGrowthEvent that allows mods to intercept and modify the growth speed of crops (like Wheat, Carrots, and Potatoes) and saplings. This is often used by survival mods to make farming more difficult or dependent on seasons/biomes.
Commands#
AppleCore adds administrative commands to help players and server owners manage hunger levels without needing external tools.
| Command | Description |
|---|---|
/hunger [player] <value> |
Sets the specified player's hunger level to the given value (0-20). |
/hunger [player] add <value> |
Adds the specified amount of hunger to the player's current level. |
/hunger [player] set <value> |
An alternative syntax for setting the hunger level. |
Configuration#
The configuration file (applecore.cfg) allows players to toggle visual features or adjust how the API interacts with the game.
| Option | Default | Description |
|---|---|---|
showFoodValuesInTooltip |
true | Enables the hunger/saturation info when holding Shift. |
showFoodValuesOnHud |
true | Enables the flashing icons on the hunger bar when holding food. |
showSaturationHudOverlay |
true | Enables the yellow border representing current saturation. |
showExhaustionHudUnderlay |
true | Enables the exhaustion progress bar behind the hunger bar. |
showFoodValuesInTooltipAlways |
false | If true, tooltips show without needing to hold Shift. |
API & Integration#
For developers, AppleCore is the industry standard for food-related modifications. It provides several key classes and events:
FoodValues: A simple container class for hunger and saturation values.IAppleCoreFood: An interface that can be implemented by custom items to provide dynamic food values based on player state or item NBT.AppleCoreAPI: The main entry point for accessing player food stats and global modifiers.- Events:
HungerEvent.FoodStatsAddition: Fired when a player is about to gain hunger/saturation.HungerEvent.ConditionCheck.CanRegen: Allows mods to disable health regen based on hunger.HungerEvent.ConditionCheck.CanStarve: Allows mods to prevent or modify starvation damage.
Compatibility#
AppleCore is designed to be a "core" mod, meaning it is built to support other mods. The following mods are well-known for requiring or utilizing AppleCore:
- Hunger Overhaul: Uses AppleCore to completely rewrite the hunger system, making it more challenging.
- The Spice of Life: Uses AppleCore to track food history and apply diminishing returns to repeated meals.
- Hunger In Peace: Re-enables the hunger bar and health regeneration mechanics in Peaceful difficulty.
- Hunger Tweaker: Provides CraftTweaker integration, allowing users to change food values via scripts.
