# 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:**
  ```bash
  ./gradlew build
  ```
  - Generates the mod JAR in `build/libs/`.
  - Always run this after making changes to verify compilation.

- **Run Client:**
  ```bash
  ./gradlew runClient
  ```

- **Run Server:**
  ```bash
  ./gradlew runServer
  ```

- **Run Data Generation:**
  ```bash
  ./gradlew runData
  ```
  - This generates resources (blockstates, models, loot tables) into `src/generated/resources`.

- **Run All Tests:**
  ```bash
  ./gradlew test
  ```

- **Run Single Test Class:**
  ```bash
  ./gradlew test --tests "net.mcreator.customoregen.OresCommandTest"
  ```

- **Run Single Test Method:**
  ```bash
  ./gradlew test --tests "net.mcreator.customoregen.OresCommandTest.testCommandRegistration_ShouldRegisterOresCommand"
  ```

- **Clean Project:**
  ```bash
  ./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.
  ```java
  // 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
```