custom_ore_gem/AGENTS.md

Custom Ore Gem - Developer Guide for Agents

This repository is a Minecraft NeoForge 1.21.1 mod created with MCreator. Agents must follow these strict guidelines to ensure build stability and code preservation.

1. Build & Test Commands

Use the Gradle wrapper for all operations. Ensure you are using Java 21 (NeoForge 1.21.1 requirement).

• Build Mod:

  ./gradlew build
  

  • Generates the mod JAR in build/libs/.
  • Always run this after making changes to verify compilation.

• Run Client:

  ./gradlew runClient
  

• Run Server:

  ./gradlew runServer
  

• Run Data Generation:

  ./gradlew runData
  

  • This generates resources (blockstates, models, loot tables) into src/generated/resources.

• Run All Tests:

  ./gradlew test
  

• Run Single Test Class:

  ./gradlew test --tests "net.mcreator.customoregen.OresCommandTest"
  

• Run Single Test Method:

  ./gradlew test --tests "net.mcreator.customoregen.OresCommandTest.testCommandRegistration_ShouldRegisterOresCommand"
  

• Clean Project:

  ./gradlew clean
  

2. MCreator & Code Preservation

CRITICAL: This project is partially generated by MCreator.

• Generated Files: Many files in src/main/java are regenerated on every build or MCreator export.

• User Code Blocks: You MUST only edit code within designated user code blocks in these files.

  // Start of user code block [block_name]
  // ... YOUR CODE HERE ...
  // End of user code block [block_name]
  

  • If a file does not have these blocks, assume it is UNSAFE to edit unless you created it yourself.

• Safe Files:

  • Files strictly created by you (e.g., in src/test/java).
  • New utility classes or event handlers not managed by MCreator.

• Do NOT directly modify the following unless inside a user block:

  • CustomOreGenModBlocks.java
  • CustomOreGenModItems.java
  • CustomOreGenModTabs.java
  • Any file in net.mcreator.customoregen.procedures (unless explicitly safe).

3. Code Style & Conventions

Formatting

• Indentation:
  • Source Code (src/main): Use TABS (default MCreator style).
  • Tests (src/test): Use 4 SPACES (typical for JUnit tests).
  • Consistency: Always check the current file's indentation before editing.
• Encoding: UTF-8.

Naming

• Classes: PascalCase (e.g., CustomOreGenMod).
• Methods: camelCase (e.g., queueServerWork).
• Constants: UPPER_SNAKE_CASE (e.g., MODID, COLD_BIOMES_TAG).
• Fields: camelCase (e.g., workQueue, oreGenConfig).
• Packages: net.mcreator.customoregen (lowercase).

Imports

• Group imports in this specific order:
  1. Java/Standard Libraries (java.*, javax.*)
  2. Third-party Libraries (e.g., org.apache.logging.log4j.*)
  3. Minecraft/NeoForge (net.minecraft.*, net.neoforged.*)
  4. Project Classes (net.mcreator.customoregen.*)
• Avoid import * unless there are many imports from the same package (e.g., java.util.* is acceptable if heavily used, but explicit imports are preferred for clarity).

Logging

• Use LogManager.getLogger(Class.class) for loggers.
• Field name: LOGGER.
• Log levels: Use debug for dev info, info for general status, error for exceptions.

4. Architecture & Patterns

• Framework: NeoForge 1.21.1 (Java 21).

• Registries: Use DeferredRegister for all registries (Blocks, Items, Tabs, SoundEvents).

  • Example: public static final DeferredRegister.Blocks REGISTRY = DeferredRegister.createBlocks(CustomOreGenMod.MODID);

• Event Bus:

  • The @Mod class registers the IEventBus.
  • Use @SubscribeEvent for event handling.
  • Event handlers often reside in net.mcreator.customoregen.event or static inner classes annotated with @EventBusSubscriber.

• Configuration:

  • Located in net.mcreator.customoregen.config.ModConfigs.
  • Uses ModConfig.Type.COMMON built with ModConfigSpec.
  • Access configs via the public static fields (e.g., ModConfigs.ORE_GEN.shardDiamondOreCount.get()).

• Commands:

  • Registered via RegisterCommandsEvent.
  • Use Brigadier (CommandDispatcher, CommandContext).
  • See OresCommand.java for the reference implementation.

5. Testing Guidelines

• Framework: JUnit 5 (Jupiter) + Mockito.
• Location: src/test/java.
• Mocking Strategy:
  • Since a full Minecraft environment is not available in unit tests, you MUST mock Minecraft classes.
  • Use @ExtendWith(MockitoExtension.class).
  • Mock critical classes: @Mock ServerPlayer player, @Mock Level level, @Mock BlockPos pos.
  • Stub methods: when(level.getBiome(pos)).thenReturn(biomeHolder);.
• Assertions: Use org.junit.jupiter.api.Assertions (e.g., assertEquals, assertDoesNotThrow).

6. Common Tasks

• Adding a New Ore:

  1. Create Block & Item (MCreator/Manual).
  2. Add JSONs: Loot Table, Configured Feature, Placed Feature, Biome Modifier.
  3. Register in CustomOreGenModBlocks and CustomOreGenModItems.
  4. Update OresCommand.java lists (e.g., COLD_ORES, HOT_ORES) to make it discoverable.
  5. Update OreBreakEventHandler.java if it has custom drops logic.
  6. Add to ModConfigs.java for generation parameters (vein size, count, etc.).

• Modifying Logic:

  • Check procedures/ for game logic (often MCreator generated).
  • Check event/ for event-driven logic.
  • Always verify if logic changes need a corresponding test update.

7. Safety & Verification

• Backups: If you are unsure about MCreator regeneration, backup the file before editing.
• Verification:
  • Always run ./gradlew build after changes to ensure no compilation errors.
  • If you touch config files, ensure ModConfigsTest still passes.
  • If you touch commands, ensure OresCommandTest still passes.

8. Directory Structure

src/
├── main/
│   ├── java/net/mcreator/customoregen/
│   │   ├── block/       # Block definitions
│   │   ├── config/      # Configuration classes
│   │   ├── event/       # Event handlers
│   │   ├── init/        # Registration (Blocks, Items, Tabs)
│   │   ├── item/        # Item definitions
│   │   └── procedures/  # Game logic procedures
│   └── resources/       # Assets and data (textures, models, lang)
└── test/
    └── java/net/mcreator/customoregen/  # Unit tests