Skip to content

Commit 1c50cec

Browse files
rubensworksrubensworks
committed
Merge remote-tracking branch 'origin/master-1.21-lts' into master-1.21
2 parents 2b22f22 + 801a373 commit 1c50cec

File tree

2 files changed

+235
-0
lines changed

2 files changed

+235
-0
lines changed

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: "Copilot Setup Steps"
2+
3+
on:
4+
workflow_dispatch:
5+
push:
6+
paths:
7+
- .github/workflows/copilot-setup-steps.yml
8+
pull_request:
9+
paths:
10+
- .github/workflows/copilot-setup-steps.yml
11+
12+
jobs:
13+
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
14+
copilot-setup-steps:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: read
18+
19+
# Steps that will run before the agent starts
20+
steps:
21+
- name: 'Checkout'
22+
uses: actions/checkout@v4
23+
with:
24+
submodules: true
25+
- name: Read Java version from gradle.properties
26+
id: java_version
27+
run: |
28+
if [ -f gradle.properties ] && grep -q '^java_version=' gradle.properties; then
29+
VERSION=$(grep '^java_version=' gradle.properties | cut -d'=' -f2)
30+
else
31+
VERSION=17
32+
fi
33+
echo "Using Java version: $VERSION"
34+
echo "version=$VERSION" >> $GITHUB_OUTPUT
35+
- name: 'Setup Java'
36+
uses: actions/setup-java@v4
37+
with:
38+
distribution: 'microsoft'
39+
java-version: ${{ steps.java_version.outputs.version }}
40+
- name: 'Setup Gradle'
41+
uses: gradle/actions/setup-gradle@v4
42+
with:
43+
gradle-version: wrapper
44+
cache-read-only: false
45+
- name: 'Build'
46+
run: ./gradlew build --no-daemon
47+
env:
48+
MAVEN_USERNAME: ${{ secrets.MAVEN_USERNAME }}
49+
MAVEN_KEY: ${{ secrets.MAVEN_KEY }}
50+
GITHUB_USER: ${{ github.actor }}
51+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
52+
- name: 'Warmup for game test server'
53+
run: ./gradlew runGameTestServer --no-daemon

‎AGENTS.md‎

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

0 commit comments

Comments
 (0)