Better Enchanted

Fabric Mod | Minecraft 1.20.4 | Java 17
Bring vanilla enchantment effects to food and potions — let them have enchantment abilities too.

---

Introduction

Better Enchanted is a Minecraft Fabric mod whose core gameplay revolves around creatively applying vanilla weapon, bow, crossbow, and trident enchantment effects to food and thrown potions. Food enchantments trigger on the eater when consumed, while potion enchantments trigger on targets upon impact. All damage formulas reference MC 1.20.4 vanilla enchantment mechanics as closely as possible for balance and consistency.

---

I. Food Enchantments

Food enchantments apply to all edible items and are also compatible with cake blocks (cakes use a dedicated block enchantment storage system).

1.1 Sharpness

• Effect: Deals damage to the eater upon consumption
• Formula: damage = 0.5 × level + 0.5
  • Sharpness I = 1.0 damage, II = 1.5, III = 2.0, IV = 2.5, V = 3.0
• Custom damage source: Has a unique death message ("XXX had their throat cut by sharp food")
• Cake support: Reads sharpness level from CakeEnchantmentStorage at the cake's position

1.2 Knockback

• Effect: Applies knockback to the eater upon consumption
• Direction: Random direction (360° random angle), simulating being "flung" by the food
• Strength formula:
  • Horizontal: strength = 0.5 × level
  • Vertical: If on ground, gives a small upward boost (max 0.4)
• Reference: Adapted from MC 1.20.4 PlayerEntity.attack() knockback logic

1.3 Fire Aspect

• Effect: Ignites the eater upon consumption
• Duration: level × 4 seconds
  • Fire Aspect I = 4s, Fire Aspect II = 8s
• Reference: Identical to MC 1.20.4 vanilla Fire Aspect logic (target.setOnFireFor(level * 4))

1.4 Efficiency

• Effect: Speeds up eating
• Formula: Each level reduces eating time by 10%
  • Efficiency I = 10% faster, Efficiency V = 50% faster
• Implementation: Mixin into Item.getMaxUseTime() to reduce eating tick count

1.5 Frost Walker

• Effect: Grants Frost Walker effect after eating
• Duration: Base 20 seconds + 10 seconds per level
  • Frost Walker I = 30s, II = 40s, III = 50s
• Ice formation: Water beneath the player freezes into frosted ice during the effect
• Continuous damage: Takes 1 frost damage every 4 seconds, with interval reduced by 0.5s per level
  • Frost Walker I = every 3.5s, II = every 3s
• Visual effect: Health bar displays in blue frozen style
• Configurable: Frost Walker logging can be toggled via debug menu

1.6 Unbreaking

• Effect: Chance to not consume food after eating
• Probability formula: References MC 1.20.4 vanilla Unbreaking formula
  • Consumption probability = 1 / (level + 1)
  • Non-consumption probability = level / (level + 1)
  • Unbreaking I = 50% no consumption, II = 66.7%, III = 75%
• Cake special handling: When triggered, restores one cake bite (BITES - 1); if the cake was just fully eaten, restores it to the last-bite state

---

II. Potion Enchantments — Weapon/Bow Category

Potion enchantments trigger when throwable potions (splash/lingering) are thrown and hit something. All damage/effects apply at full strength to directly hit entities, and with distance-based falloff to entities within splash range (4 blocks).

2.1 Sharpness [Potion]

• Effect: Thrown potion deals damage to hit entities
• Formula: damage = 0.5 × level + 0.5 (same as food Sharpness)
• Splash: Distance-attenuated damage within 4 blocks (damage × (1 - distance/4))
• Stacking: Stacks additively with Power enchantment damage
• Custom damage source: Unique death message ("XXX was shattered by a sharp potion")

2.2 Power [Potion]

• Effect: Thrown potion deals damage to hit entities
• Formula: References MC 1.20.4 bow Power enchantment
  • damage = level + 1 (simulating arrow base=2 Power bonus)
  • Power I = 2.0, II = 3.0, III = 4.0, IV = 5.0, V = 6.0
• Stacking: Adds directly to Sharpness damage
• Damage source: When Power damage ≥ Sharpness damage, uses Power-specific death message ("XXX was obliterated by a powerful potion")

2.3 Punch [Potion]

• Effect: Thrown potion applies knockback to hit entities
• Formula: References MC 1.20.4 bow Punch enchantment (AbstractArrowEntity.onHit)
  • knockbackStrength = punchLevel × 0.6
• Direction:
  • Direct hit: Along potion flight direction (normalized horizontal components)
  • Splash range: From impact point toward entity, strength attenuated by distance

2.4 Flame [Potion]

• Effect: Thrown potion ignites targets on hit
• Direct hit: 5 seconds of fire (100 ticks), matching MC 1.20.4 bow Flame rules
• Splash range: Fire duration attenuated by distance (ceil(5 × (1 - distance/4)) seconds)
• Level: Only level I (matching vanilla)

2.5 Channeling [Potion]

• Effect: MC 1.20.4 trident Channeling rules adapted as AOE version
• Conditions:
  1. Must be thunderstorm weather (world.isThundering())
  2. Target entity position must have sky visibility (isSkyVisible)
• Range: All living entities within 4 blocks of potion impact point
• Result: Each qualifying entity gets a lightning bolt summoned at its position
• Lightning attribution: Lightning channeler set to the thrower (affects drops and XP)
• Level: Only level I (matching vanilla)

---

III. Potion Enchantments — Crossbow Category

3.1 Multishot [Potion]

• Effect: Single throw produces multiple potions in a cone spread
• Count formula: Total projectiles = 2 + level
  • Multishot I = 3, II = 4, III = 5
• Distribution rules:
  • First potion (primary) flies straight along aim direction (cone center)
  • First 8 extra projectiles distribute evenly on a 10° cone circumference
  • Beyond 8 extras: randomly distributed within the cone (0°–10°, using sqrt for area-uniform distribution)
• Consumption: Only consumes 1 potion
• Compatibility: Fully compatible with all Swift Throw modes (physics/raycast)

3.2 Quick Charge [Potion]

• Effect: Reduces Infinity enchantment cooldown time
• Formula: Each level reduces cooldown by 20% (base 30 seconds)
  • Lv I = 24s, Lv II = 18s, Lv III = 12s, Lv IV = 6s, Lv V = 0s (no cooldown)
• Prerequisite: Must be used with Infinity enchantment; has no effect alone

3.3 Piercing [Potion]

• Effect: References MC 1.20.4 crossbow Piercing rules
• Mechanics:
  • Potion can pass through level entities (hitting level + 1 total)
  • Applies enchantment effects (Sharpness/Power/Punch/Flame) to each pierced entity
  • Already-pierced entities won't be hit again
  • Destroys normally and triggers splash effects when hitting a block or reaching pierce limit

---

IV. Potion Enchantments — Trident Category

4.1 Loyalty [Potion]

• Effect: Adapted from MC 1.20.4 trident Loyalty rules
• Mechanics:
  • Potion automatically returns to thrower 2 seconds after being thrown
  • Return speed = 0.5 × level blocks/tick
    • Lv I = 10 blocks/s, Lv II = 20 blocks/s, Lv III = 30 blocks/s
  • If it hits an entity or block during flight/return, it's consumed normally (won't return)
  • Successful return gives the potion item back to the player
• Consumption logic: Potion is consumed immediately on throw (entity itself carries return logic)

---

V. Universal Potion Enchantments

5.1 Infinity [Potion]

• Effect: Throwing potion doesn't consume it
• Cooldown system:
  • Custom cooldown system based on NBT tag (InfinityMarked)
  • Only affects items with the Infinity enchantment, not other identical items
  • Base cooldown: 30 seconds (reduced by Quick Charge)
• Interaction with Unbreaking:
  • With Unbreaking: perform durability check — pass → no cooldown, fail → enter cooldown
  • Without Unbreaking: always enters cooldown
• Client display: Gray semi-transparent cooldown overlay synced via networking
• Cooldown blocking: Cannot use the item again while on cooldown

5.2 Unbreaking [Potion]

• Effect: Chance to not consume potion after throwing
• Formula: Same as food Unbreaking (consumption probability = 1/(level+1))
• Interaction with Infinity: Check result determines whether cooldown triggers (see above)

---

VI. Custom Enchantments

6.1 Swift Throw

• Effect: Increases potion throw speed and trajectory flatness
• Speed formula: actual speed = base speed (0.5) × (1 + 0.5 × level)
• Angle formula: Upward offset angle y = 80 / (4 + level) degrees
  • Higher levels = flatter trajectory
  • When offset angle < 1°, set to 0 (perfectly flat throw)
• Two modes:
  • Level 1–20 (Physics mode): Normal physics throw with speed and direction calculated by formula, affected by gravity
  • Level >20 (Raycast mode): Instant hit via per-tick raytrace teleportation; potion entity is invisible and gravity-free; crit particles spawn every 0.5 blocks along the firing direction (up to 64 blocks)
• Compatibility: Fully compatible with Multishot — extra projectiles also use the same Swift Throw mode

---

VII. Utility Features

7.1 Entity Health HUD

• Displays target's current HP / max HP on screen when crosshair is aimed at an entity
• Detection distance is configurable (default 128 blocks)
• Can be independently toggled via debug menu

7.2 Held Item HUD

• Displays main hand item name and count in the top-left corner
• Advanced mode: Additionally shows item durability and full NBT tag data
• Can be independently toggled via debug menu

7.3 Debug Menu

• Opened via custom keybind (unbound by default, configurable in key settings)
• Provides sub-menus:
  • Entity health display settings (toggle + detection distance slider)
  • Held item display settings (toggle + advanced mode toggle)
  • Debug log toggles (independent control of 9 log modules: cake/place/food/potion/damage/swift throw/client/frost walker/infinity cooldown)

7.4 Persistent Configuration

• Config file located at config/hello-mod.json
• All setting changes auto-save; auto-loads on startup
• Human-readable JSON format, supports manual editing

---

VIII. Technical Architecture

8.1 Core Tech Stack

Component	Technology
Mod Framework	Fabric Loader 0.15.3 + Fabric API 0.97.1
Game Version	Minecraft 1.20.4
Java Version	Java 17
Build Tool	Gradle + Fabric Loom 1.7
Code Modification	Mixin Injection
Mappings	Yarn 1.20.4+build.3:v2

8.2 Mixin Injection Points

Mixin Class	Target	Purpose
PlayerEatFoodMixin	PlayerEntity.eatFood()	Food enchantment triggers (Sharpness/Knockback/Fire/Frost)
CakeBlockMixin	CakeBlock.tryEat()	Cake enchantment triggers
CakePlaceMixin	CakeBlock.onPlaced()	Store enchantment data when placing cake
EfficientEatingMixin	Item.getMaxUseTime()	Efficiency eating speed boost
UnbreakingFoodMixin	PlayerEntity.eatFood() RETURN	Food Unbreaking check
PotionItemMixin	ThrowablePotionItem.use()	Potion throw logic (Infinity/Unbreaking/Multishot/consumption)
PotionEntityMixin	PotionEntity.onCollision()	Potion hit effects (Sharpness/Power/Punch/Flame/Channeling)
SwiftThrowTickMixin	PotionEntity.tick()	Swift Throw raycast mode
MultishotEnchantmentMixin	—	Multishot helper
PiercingPotionMixin	PotionEntity collision	Piercing logic
LoyaltyPotionMixin	PotionEntity.tick()	Loyalty return logic
LoyaltyCollisionMixin	PotionEntity collision	Loyalty return collision handling
LivingEntityDamageCooldownMixin	LivingEntity	Damage invincibility frame adjustment

8.3 Package Structure

com.example.hellomod
├── HelloMod.java                    # Main entrypoint, registers events and systems
├── block/                           # Cake enchantment storage, block entities
│   ├── CakeEnchantmentStorage.java  # In-memory cake enchantment data management
│   ├── EnchantedCakeBlockEntity.java
│   └── HelloModBlockEntities.java
├── client/                          # Client-side features
│   ├── HelloModClient.java          # Client entrypoint
│   ├── EntityHealthHud.java         # Entity health HUD
│   ├── InfinityCooldownClientState.java # Infinity cooldown client sync
│   ├── DebugMenuScreen.java         # Debug menu UI
│   ├── DebugLogSettingScreen.java   # Log toggle UI
│   ├── HealthHudSettingScreen.java  # Health HUD settings UI
│   └── ItemHudSettingScreen.java    # Item HUD settings UI
├── config/                          # Configuration persistence
│   └── ModConfig.java
├── damage/                          # Custom damage sources
│   ├── ModDamageTypes.java
│   ├── SharpFoodDamageSource.java
│   ├── SharpPotionDamageSource.java
│   └── PowerPotionDamageSource.java
├── debug/                           # Debug log control
│   └── DebugLogConfig.java
├── effect/                          # Custom effects
│   └── FrostWalkerFoodEffect.java   # Frost Walker food effect (tick event)
├── enchantment/                     # Enchantment system
│   ├── ModEnchantments.java         # Custom enchantment registration
│   ├── SwiftThrowEnchantment.java   # Swift Throw enchantment definition
│   ├── InfinityCooldownManager.java # Infinity cooldown server-side management
│   └── InfinityCooldownSync.java    # Cooldown state network sync
└── mixin/                           # All Mixin injection classes
    ├── client/                      # Client-side Mixins
    └── ...                          # See table above

8.4 Key Design Decisions

1. Cake special handling: Cakes are blocks, not items, so ItemStack NBT can't be read directly. Uses CakeEnchantmentStorage to bind enchantment data to block coordinates — written on placement, cleared when fully eaten.

2. Potion enchantment data transfer: Enchantments are stored in the potion ItemStack's NBT. On throw, the complete ItemStack is passed to the projectile entity via potionEntity.setItem(stack). On impact, EnchantmentHelper.getLevel() reads from the entity's stack.

3. Infinity cooldown system: Doesn't use vanilla ItemCooldownManager (which affects all items of the same type). Instead uses a custom cooldown manager keyed by player UUID + NBT tag (InfinityMarked), only affecting specifically marked items.

4. Swift Throw raycast: At high Swift Throw levels (>20), physics-based throw speed is too fast causing wall-clipping and collision detection failures. Switches to per-tick raytrace teleportation to ensure correct collision detection.

---

IX. Enchantment Overview Table

Enchantment	Food	Potion	Max Level	Notes
Sharpness	✅	✅	V	Food damages eater, potion damages target
Knockback	✅	—	II	Random direction
Fire Aspect	✅	—	II	4s per level
Efficiency	✅	—	V	-10% eating time per level
Frost Walker	✅	—	III	Ice + continuous damage
Unbreaking	✅	✅	III	Chance to not consume
Power	—	✅	V	Stacks with Sharpness
Punch	—	✅	II	Knockback along flight direction
Flame	—	✅	I	5s fire
Infinity	—	✅	I	No consumption + cooldown
Channeling	—	✅	I	Thunderstorm AOE lightning
Multishot	—	✅	III+	Cone spread
Quick Charge	—	✅	V	Reduces Infinity cooldown
Piercing	—	✅	IV	Passes through multiple entities
Loyalty	—	✅	III	Returns after 2s
Swift Throw	—	✅	∞	Custom enchantment

---

X. Runtime Environment & Dependencies

• Minecraft: 1.20.4
• Fabric Loader: ≥ 0.15.0
• Fabric API: Any compatible version
• Java: ≥ 17
• License: MIT