custom_ore_gen/AGENTS.md

# Custom Ore Gem - Developer Guide for Agents

This repository is a Minecraft **NeoForge 1.21.1** mod. It was originally scaffolded with MCreator but is now **fully hand-maintained** — all files are safe to edit. Agents must follow these guidelines to ensure build stability.

## 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 "com.aulyrius.customoregen.OresCommandTest"
  ```

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

- **Clean Project:**
  ```bash
  ./gradlew clean
  ```

## 2. Code Ownership

The project was originally generated by MCreator but is no longer maintained with it
(MCreator is not installed anymore; the build is plain Gradle + NeoForge ModDev).
- **Every file** in `src/main/java` and `src/test/java` is hand-maintained and safe to edit.
- The historical "user code block" markers were removed; there is no regeneration step.
- Keep MCreator-era naming quirks (e.g. `SharddiamondpickaxeItem`) unless a rename is
  explicitly requested, to keep diffs readable.

## 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:** `com.aulyrius.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 (`com.aulyrius.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 `com.aulyrius.customoregen.event` or static inner classes annotated with `@EventBusSubscriber`.

- **Configuration:**
  - Located in `com.aulyrius.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 classes manually (copy an existing ore as template).
  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.
  - Check `event/` for event-driven logic.
  - Always verify if logic changes need a corresponding test update.

## 7. Safety & Verification

- **Backups:** All files are hand-maintained; standard git workflow is sufficient.
- **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/com/aulyrius/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/com/aulyrius/customoregen/  # Unit tests
```