custom_ore_gen/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Custom Ore Gem is a Minecraft NeoForge 1.21.1 mod (mod ID: custom_ore_gen) that modifies ore distribution and adds Diamond Shard-tier tools and armor. Originally scaffolded with MCreator, the project is now fully hand-maintained - no file is regenerated automatically.

Note: This mod replaces vanilla ore distribution with custom biome-based ore generation. For full functionality, it's recommended to use with KubeJS to remove vanilla ores (manual setup required).

Build Commands

# Build the mod (generates .jar in build/libs/)
./gradlew build

# Run client for testing
./gradlew runClient

# Run server for testing
./gradlew runServer

# Clean build artifacts
./gradlew clean

# Generate resources (data generation for assets/resources)
./gradlew runData

The built JAR is named custom_ore_gen-{version}.jar and appears in build/libs/.

Architecture

Code Ownership

The project was originally generated by MCreator but is no longer maintained with it. Every file in src/main/java is hand-maintained and safe to edit; there is no regeneration step and no protected code blocks.

Package Structure

com.aulyrius.customoregen/
├── CustomOreGenMod.java          # Main mod class
├── OresCommand.java              # /ores command implementation
├── OreTypes.java                 # Block -> ore type mapping (single source of truth)
├── block/                        # Ore block classes (17 blocks)
├── item/                         # Items (Diamond Shard, tools, armor, Paxel, OreBiomeFinder)
├── config/                       # NeoForge configuration system (ModConfigs, ConfigHelper)
├── event/                        # Event handlers (OreBreakEventHandler)
├── loot/                         # CustomOreLootModifier (Global Loot Modifier for drops)
├── mixin/                        # MultiNoiseBiomeSourceMixin (Deep Dark latitude lock)
├── procedures/                   # Game logic (ConfigurableOreDropsProcedure, OreDropMath)
├── worldgen/                     # Latitude zones, density function, placement, biome gating
└── init/
    ├── CustomOreGenModBlocks.java  # Block registry (deferred register)
    ├── CustomOreGenModItems.java   # Item registry
    └── CustomOreGenModTabs.java    # Creative tabs registry

Ore Generation System

The mod uses NeoForge biome modifiers to distribute ores based on biome temperature tags. The architecture:

1. Biome Tags (src/main/resources/data/custom_ore_gen/tags/worldgen/biome/):

   • cold_biomes.json - Cold biomes (lapis, concentrated diamond)
   • hot_biomes.json - Hot biomes (pure gold, copper, redstone)
   • mountain_biomes.json - Mountain biomes (high emerald)
   • rare_biomes.json - Rare biomes (lower emerald)
   • tempered_biomes.json - Temperate biomes (iron, concentrated coal)
   • BOP biomes are included with "required": false for optional compatibility

2. Biome Modifiers (src/main/resources/data/custom_ore_gen/neoforge/biome_modifier/):

   • Each ore has a JSON file linking it to biome tags
   • Special case: deepslatesharddiamondore_biome_modifier.json uses "type": "forge:any" for all biomes
   • JSON Structure:

     {
       "type": "neoforge:add_features",
       "biomes": "custom_ore_gen:cold_biomes",  // or {"type": "forge:any"} for all biomes
       "features": "custom_ore_gen:deepslatesharddiamondore",
       "step": "underground_ores"
     }
     

3. Worldgen Features (src/main/resources/data/custom_ore_gen/worldgen/):

   • configured_feature/ - Defines ore vein size and height range
   • placed_feature/ - Places the feature in the world with vertical anchors

Diamond Shard Progression Tier

Diamond Shards are an intermediate tier between Iron and Diamond:

• Items: Diamond Shard (diamondshard) - craft 9 shards into 1 diamond
• Tools: Pickaxe, Shovel, Axe (200 durability), Paxel (1000 durability, combines all three)
• Armor: Helmet (3), Chestplate (7), Leggings (5), Boots (2) - Total 17 protection, 1060 durability
• Repair: All Diamond Shard equipment uses Diamond Shards

Configuration System

Located in src/main/java/com/aulyrius/customoregen/config/:

• ModConfigs.java - NeoForge configuration with nested config classes: ToolStatsConfig, DropsConfig, FeatureToggleConfig, LatitudeOreConfig
• ConfigHelper.java - Utility class for accessing config values
• Generated config file: config/custom_ore_gen-common.toml (created on first run)

Current Implementation Status:

• ✅ Ore Drops: Fully implemented via OreBreakEventHandler.java which listens to BlockEvent.BreakEvent and calls ConfigurableOreDropsProcedure.execute() for all custom ores
• ⚠️ Tool Stats: Wired. Tools read their stats from TOOL_STATS config when the config is loaded, with a hardcoded fallback when not yet loaded (e.g. SharddiamondpickaxeItem.java: return ModConfigs.isLoaded() ? ModConfigs.TOOL_STATS.shardDiamondPickaxeDurability.get() : 200;).
• ⚠️ Feature Toggles: Wired (commit 48a0d797). Toggles in FeatureToggleConfig drive ore generation via ConfigGatedFeaturesModifier + the config_gated_features biome modifiers in data/custom_ore_gen/neoforge/biome_modifier/add_*_ores.json. A regression test (ModConfigsTest.testFeatureToggleConfig_declaresAllTogglesReferencedByConfigHelper()) ensures every toggle string used by ConfigHelper.isFeatureEnabled() actually maps to a field on FeatureToggleConfig, so a typo can't silently produce a dead toggle. Note: item/block registration still always fires (toggling only gates worldgen, not whether the items exist in creative).
• ⚠️ Ore Generation (gating): Feature toggles gate whether each ore feature is added (see Feature Toggles above). Vein parameters (size, count, height) are hard-coded in the data-driven worldgen JSONs under data/custom_ore_gen/worldgen/ (configured_feature/ + placed_feature/), exactly like vanilla; there is no runtime-config-driven ore parameter provider.
• Enchantability: Works natively in 1.21.1 via the enchantable tags (data/minecraft/tags/item/enchantable/{mining,weapon,armor,durability}.json, which include all Shard Diamond tools + armor) combined with Tier.getEnchantmentValue() == 9 on the tool Tiers. The dead EnchantabilityFix.java class (which referenced the non-existent DataComponents.ENCHANTABLE / net.minecraft.world.item.enchantment.Enchantable from an earlier 1.20.5-snapshot API) has been removed.

Ore Biome Finder

The OreBiomeFinderItem (item/OreBiomeFinderItem.java) and /ores command (OresCommand.java) detect which mod tags apply to the current biome and list findable ores.

Implementation Details:

• Both are thin wrappers over worldgen/OreZoneCatalog.buildZoneReport(x, z), which derives the zone from the Z coordinate via LatitudeConfig (cold/temperate/hot thresholds)
• Ore lists per zone live in OreZoneCatalog (single source of truth)

Adding a New Ore

The project is fully hand-maintained (no MCreator). To add a new ore type:

1. Create the block class in block/ (copy an existing ore, adjust properties)
2. Register block + item in init/CustomOreGenModBlocks.java and init/CustomOreGenModItems.java
3. Add loot table at src/main/resources/data/custom_ore_gen/loot_table/blocks/{orename}.json (note: loot_table not loot_tables)
4. Add configured_feature JSON in src/main/resources/data/custom_ore_gen/worldgen/configured_feature/
5. Add placed_feature JSON in src/main/resources/data/custom_ore_gen/worldgen/placed_feature/ (use a custom_ore_gen:latitude_zone placement modifier to bind it to a climate zone)
6. Create biome_modifier JSON in src/main/resources/data/custom_ore_gen/neoforge/biome_modifier/ (use custom_ore_gen:config_gated_features to make it config-toggleable)
7. Add BOP entries (optional) to appropriate biome tag JSON files with "required": false wrapper
8. Update OreZoneCatalog.java to list the new ore in the appropriate zone
9. Add the ore type mapping in OreTypes.java + a drop spec in CustomOreLootModifier if you want configurable drops

User Code Sections

Historical MCreator "user code block" markers were removed - every source file is fully editable.

Event Handlers

The mod uses NeoForge's event system for ore processing:

OreBreakEventHandler

• Listens to BlockEvent.BreakEvent with @SubscribeEvent
• Maps custom ore blocks to ore type strings (shard_diamond, concentrated_coal, pure_golden, etc.)
• Calls ConfigurableOreDropsProcedure.execute() with ore type when player breaks ore with correct tool
• Supports 10 ore types: shard_diamond, concentrated_coal, pure_golden, impure_iron, concentrated_diamond, lapis, redstone, emerald, copper

Enchantability

• Implemented natively via 1.21.1 mechanisms: the Shard Diamond tools + armor are listed in data/minecraft/tags/item/enchantable/{mining,weapon,armor,durability}.json, and the tool Tiers return getEnchantmentValue() == 9.
• A former EnchantabilityFix.java used ModifyDefaultComponentsEvent to set a DataComponents.ENCHANTABLE component, but that API does not exist in 1.21.1 (only ENCHANTMENTS/ENCHANTMENT_GLINT_OVERRIDE/STORED_ENCHANTMENTS exist on DataComponents). The dead class has been deleted.

Loot Table Format

NeoForge 1.21 uses loot_table (singular) instead of loot_tables (plural):

• Location: src/main/resources/data/custom_ore_gen/loot_table/blocks/{orename}.json
• Includes Silk Touch support via match_tool condition
• Uses random_sequence for loot table randomization
• Example structure in deepslatesharddiamondore.json shows Silk Touch → drop block, otherwise drops handled by OreBreakEventHandler

Vanilla Ore Removal

The mod removes vanilla ores via NeoForge biome modifiers (NOT KubeJS anymore):

• src/main/resources/data/custom_ore_gen/neoforge/biome_modifier/remove_vanilla_ores.json
• Uses neoforge:remove_features type to remove vanilla ore generation
• This replaces the old KubeJS automatic script system from Forge 1.20.1

Biomes O' Plenty Integration

The mod includes BOP biome support through biome tag entries. BOP biomes are wrapped with:

{
  "id": "biomesoplenty:biome_name",
  "required": false
}

The "required": false flag ensures the game doesn't crash if BOP isn't installed. When adding new BOP biomes, add them to the appropriate category tag JSON files in tags/worldgen/biome/.

Testing

After making changes:

1. Run ./gradlew build to verify compilation
2. Run ./gradlew runClient to test in-game
3. Check logs in run/logs/ for errors

Enchantment Tags

The mod includes enchantment tags at src/main/resources/data/minecraft/tags/item/enchantable/:

• armor.json - Marks Shard Diamond armor pieces as enchantable
• durability.json - Marks tools and armor for durability enchantments
• mining.json - Marks pickaxes, shovels, and paxel as mining tools
• weapon.json - Marks axes as weapons

These tags enable proper enchantment behavior for custom items in the enchanting table and anvil.

Important Notes

README Disclaimer

The README.md file contains outdated information referring to Forge 1.20.1. The current codebase uses NeoForge 1.21.1. Always trust gradle.properties and this file for accurate version information.

Recipe Compatibility

The mod includes recipes for:

• Mekanism: Enriching recipes for concentrated ores and shard diamond
• Create: Crushing and milling recipes for ore processing
• Sculk Catalyst: Diamond shard to sculk catalyst conversion

Version Information

• Minecraft: 1.21.1
• NeoForge: 21.1.219 (defined in gradle.properties as neo_version)
• Java: 21 (configured via Java toolchain in build.gradle)
• Mod Version: 3.0 (defined in gradle.properties as mod_version)

Mod Registration Order

In CustomOreGenMod constructor, registration order is:

1. CustomOreGenModBlocks.REGISTRY.register(modEventBus) - Blocks must be registered first
2. CustomOreGenModItems.REGISTRY.register(modEventBus) - Items depend on blocks for BlockItems
3. CustomOreGenModTabs.REGISTRY.register(modEventBus) - Creative tabs depend on items

Server Work Queue Pattern

The mod includes a server tick work queue (CustomOreGenMod.java:52-69) for deferring execution:

• queueServerWork(int tick, Runnable action) - Schedule work to run after N server ticks
• Only executes on server thread (SidedThreadGroups.SERVER)
• Processed during ServerTickEvent.Post
• Use this for operations that need to happen after a delay or during gameplay

DeferredRegister Pattern

All registries use NeoForge's DeferredRegister.create(Registries.X, CustomOreGenMod.MODID) pattern. This is the modern NeoForge 1.21 registration method replacing the old Forge registry system.

NeoForge 1.21 Tool Tier Implementation

When creating custom tool items (Tier), you must implement getIncorrectBlocksForDrops():

• Returns TagKey<Block> or null
• If null, all blocks can be dropped (current implementation in SharddiamondpickaxeItem.java:38-40)
• This replaces the old Forge 1.20 getTier() and incorrect blocks logic