Skip to content

Commit 4d5143e

Browse files
Copilotrubensworks
Copilot
and
rubensworks
committed
Create comprehensive AGENTS.md file for repository
Co-authored-by: rubensworks <440384+rubensworks@users.noreply.github.com>
1 parent d2a834a commit 4d5143e

1 file changed

Lines changed: 179 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# AGENTS.md - Developer and AI Agent Guide
2+
3+
This document provides essential information for developers and AI agents working on the CyclopsCore codebase.
4+
5+
## Project Overview
6+
7+
CyclopsCore is a library mod for Minecraft that serves as a foundation for several other mods in the CyclopsMC ecosystem, including Integrated Dynamics and EvilCraft. The project is written in Java and uses Gradle as its build system.
8+
9+
## Multi-Loader Architecture
10+
11+
This repository uses a **multi-loader setup**, meaning the mod is available on multiple Minecraft mod loaders. Understanding this architecture is crucial when making changes:
12+
13+
### Directory Structure
14+
15+
- **`loader-common/`**: Contains source code that is common across all mod loaders. Most shared functionality should be implemented here.
16+
- **`loader-fabric/`**: Fabric-specific implementation and integration code.
17+
- **`loader-forge/`**: Forge-specific implementation and integration code (for older Minecraft versions).
18+
- **`loader-neoforge/`**: NeoForge-specific implementation and integration code (for newer Minecraft versions).
19+
20+
### Making Changes
21+
22+
When adding features or fixing bugs:
23+
1. Place shared logic in `loader-common/` whenever possible
24+
2. Only add loader-specific code to the respective `loader-*` directories when platform-specific APIs are required
25+
3. Ensure your changes work across all supported loaders
26+
27+
## Testing
28+
29+
CyclopsCore uses two types of tests:
30+
31+
### 1. Unit Tests
32+
33+
**Location**: `loader-neoforge/src/test/java/`
34+
35+
Traditional JUnit tests for testing isolated functionality without requiring a full Minecraft instance.
36+
37+
**Running unit tests**:
38+
```bash
39+
./gradlew test
40+
```
41+
42+
Unit tests are automatically executed when running the `build` command.
43+
44+
### 2. Game Tests
45+
46+
**Location**: Within normal sources, typically in the `org/cyclops/*/gametest` package (e.g., `loader-common/src/main/java/org/cyclops/cyclopscore/gametest/`)
47+
48+
Game tests run an actual Minecraft instance to test code with real game logic. These are essential for testing features that interact with Minecraft's gameplay systems.
49+
50+
**Running game tests**:
51+
```bash
52+
./gradlew runGameTestServer
53+
```
54+
55+
**Important**:
56+
- Game tests are **NOT** run automatically during the build process
57+
- For Minecraft 1.21 and above, game tests must be run manually before committing
58+
- Game tests must pass before finalizing your changes
59+
60+
### When to Add Tests
61+
62+
When adding new features or fixing bugs:
63+
- **Always** add unit tests when possible for isolated logic
64+
- **Always** add game tests when the feature interacts with Minecraft gameplay systems
65+
- Look at existing tests in the respective directories for examples of test patterns and conventions
66+
67+
## Building the Project
68+
69+
### Prerequisites
70+
71+
- Java 21 (as specified in `gradle.properties`)
72+
- Gradle (use the provided wrapper: `./gradlew`)
73+
74+
### Build Command
75+
76+
Before every commit, ensure the project builds successfully:
77+
78+
```bash
79+
./gradlew build
80+
```
81+
82+
This command will:
83+
- Compile all source code
84+
- Run unit tests automatically
85+
- Generate build artifacts
86+
87+
### Full Pre-Commit Validation (MC 1.21+)
88+
89+
For Minecraft 1.21 and above, run both build and game tests:
90+
91+
```bash
92+
./gradlew build
93+
./gradlew runGameTestServer
94+
```
95+
96+
Both must pass before committing changes.
97+
98+
## Code Formatting
99+
100+
This project uses Spotless for code formatting:
101+
102+
```bash
103+
./gradlew spotlessApply
104+
```
105+
106+
The pre-commit script in `scripts/pre-commit` automatically formats staged files. Consider setting it up as a Git hook:
107+
108+
```bash
109+
ln -s ../../scripts/pre-commit .git/hooks/pre-commit
110+
```
111+
112+
## Development Workflow
113+
114+
1. **Understand the change**: Read the issue/feature request thoroughly
115+
2. **Explore the codebase**: Use tools like `grep` to find relevant code
116+
3. **Make minimal changes**: Focus on the specific issue/feature
117+
4. **Add tests**: Write unit tests and/or game tests as appropriate
118+
5. **Build and test**:
119+
```bash
120+
./gradlew build
121+
./gradlew runGameTestServer # For MC 1.21+
122+
```
123+
6. **Format code**: `./gradlew spotlessApply`
124+
7. **Commit**: Use clear, descriptive commit messages
125+
126+
## Project Dependencies
127+
128+
### Project Lombok
129+
130+
This project uses [Project Lombok](https://projectlombok.org/) for annotation processing to reduce boilerplate code (getters, setters, constructors, etc.).
131+
132+
**Important**:
133+
- If you see errors about missing getters/setters, ensure your IDE has the Lombok plugin installed
134+
- Lombok annotations are processed at compile time
135+
136+
## Release Management
137+
138+
Version bumping and release management helper scripts are available in the [CyclopsMC/ReleaseHelpers](https://github.com/CyclopsMC/ReleaseHelpers) repository. These bash scripts assist with:
139+
- Version bumping across all loaders
140+
- Changelog management
141+
- Release preparation
142+
143+
## Gradle Tasks Reference
144+
145+
Common Gradle tasks for development:
146+
147+
| Task | Purpose |
148+
|------|---------|
149+
| `./gradlew build` | Build the project and run unit tests |
150+
| `./gradlew test` | Run unit tests only |
151+
| `./gradlew runGameTestServer` | Run game tests (manual, required for MC 1.21+) |
152+
| `./gradlew spotlessApply` | Format code according to project standards |
153+
| `./gradlew publishToMavenLocal` | Publish to local Maven for testing in other projects |
154+
155+
## CI/CD
156+
157+
GitHub Actions automatically:
158+
- Builds the project on every push and pull request
159+
- Runs unit tests
160+
- Runs game tests (including `runGameTestServer`)
161+
- Generates coverage reports
162+
- Deploys to CurseForge, Modrinth, and Maven on appropriate branches/tags
163+
164+
See `.github/workflows/ci.yml` for the full CI configuration.
165+
166+
## Additional Resources
167+
168+
- **README.md**: Project overview and usage information
169+
- **CONTRIBUTING.md**: Contribution guidelines and issue reporting
170+
- **Build configuration**: `build.gradle` and loader-specific build files
171+
- **Project properties**: `gradle.properties` (Minecraft version, mod version, etc.)
172+
173+
## Key Principles
174+
175+
1. **Minimal changes**: Make the smallest possible changes to achieve your goal
176+
2. **Test coverage**: Always add tests for new features and bug fixes
177+
3. **Multi-loader compatibility**: Ensure changes work across all supported loaders
178+
4. **Build validation**: Never commit without running `build` (and `runGameTestServer` for MC 1.21+)
179+
5. **Code quality**: Follow existing patterns and conventions in the codebase

0 commit comments

Comments
 (0)