ВЕРСИИ (6)

Allow to run on MC 1.20.1

## Better Enchanted 1.1.1 ### New Features - **Food & potions can now be enchanted at the enchanting table** (a custom list of available enchantments is provided). - **Food & potions can now be enchanted via enchanted books on the anvil.** - Enchantable scope: - Food: Sharpness, Knockback, Fire Aspect, Efficiency, Frost Walker, Unbreaking - Potions: Sharpness, Power, Punch, Flame, Infinity, Unbreaking, Multishot, Quick Charge, Piercing, Channeling, Loyalty, Swift Throw - Super / Ultimate Enchanted Golden Apple: full food + potion enchantment set ### Enhancements - Added a **player behavior logging system** tracking attack/interact/hurt/death/drop/jump/sprint-sneak/move/pickup actions and block place/break/interact events. - Added a "Player Behavior Log" toggle in the debug menu, with persistent config. - Added English/Chinese localization strings. ### Misc - Updated README (EN/CN) and dev docs with the enchantment acquisition mechanism, behavior logging, and super/ultimate golden apple details.

支持mc1.20.1版本

## v1.1.0（相对于 v1.0.0） ### 新物品 #### 超级附魔金苹果 - 新增超级附魔金苹果物品，支持双模式切换（食用模式/投掷模式） - 支持铁砧附魔系统，可叠加各种附魔效果 - 铁砧合成绕过原版"Too Expensive"（过于昂贵）限制 - 铁砧附魔惩罚（RepairCost）锁定为固定值 10，避免多次附魔后成本飙升 - 支持药水效果存储：合成时可关联药水，食用/投掷时释放对应效果 - 物品 Tooltip 显示当前存储的药水效果信息 #### 终极附魔金苹果 - 新增终极附魔金苹果物品，作为超级附魔金苹果的进阶版本 - 投掷命中敌对生物时无条件召唤闪电 - 自定义伤害类型（绕过护甲和附魔保护） - 新增终极金苹果挑战进度（Achievement），通过进度奖励监听触发 ### 附魔调整 #### 迅投附魔 - 附魔台最高可附魔 10 级，且仅可附到书上（需通过铁砧转移到物品） - 铁砧最高等级改为 19，防止触发射线追踪模式 - 修复迅投等级 >20 射线追踪模式的 pitchOffset 偏移问题，投掷物精确对准准星 ### 功能增强 #### 实体血量 HUD - 设置菜单新增"显示详细信息"按钮 - 开启后显示实体完整 NBT 信息（0.5x 缩放，靠右对齐） - ActiveEffects（药水效果）优先显示在血量行下方（绿色高亮） - 通过服务端网络包同步完整 NBT 数据（含药水效果） - 无血量实体显示 `[-/-]` - 手持物品 NBT 显示同步缩放为 0.5x ### Bug 修复 - 修复超级金苹果铁砧 RepairCost 锁定值错误的问题 - 修复迅投高等级投掷偏移不对准准星的问题 ### 其他 - 新增超级附魔金苹果设计文档 (`SUPER_GOLDEN_APPLE_DESIGN.md`) - 新增终极附魔金苹果设计文档 (`ULTIMATE_GOLDEN_APPLE_DESIGN.md`) - 更新 README 和 DEV_PLAN，补充新功能章节及实现细节 ### 功能增强 #### 玩家行为日志系统 - 新增玩家行为实时追踪日志，记录攻击、交互、受伤、死亡、物品丢弃、跳跃、手切换、疾跑/潜行状态变化、移动、物品拾取等动作 - 新增方块交互日志，记录放置、破坏、交互方块事件 - 新增客户端行为日志（键盘输入、鼠标点击、客户端 tick 事件） - 调试功能菜单新增"玩家行为日志"开关按钮（BehaviorLog toggle） - 新增 `playerBehaviorLogEnabled` 配置项，支持持久化保存 - 添加中英文本地化文本

port to Minecraft 1.20.1

# 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