felden.r@grenoble.archi.fr
173 lines
6.4 KiB
Markdown
173 lines
6.4 KiB
Markdown
# 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
|
|
```
|