|
1 | | -# Stonecutter Mod Template |
2 | | - |
3 | | -A multi-platform Minecraft mod template for **Fabric** and **NeoForge**, |
4 | | -using [Stonecutter](https://stonecutter.kikugie.dev/) for |
5 | | -multiversion and multiloader code. |
6 | | -This is the Java-only version adapted from KikuGie's Elytra Trims |
7 | | -rewrite following major Stonecutter feature updates. |
8 | | - |
9 | | -This template is as "batteries included" as possible. |
10 | | -If you don't like this, it's not the right template for |
11 | | -you ([Alternative Templates](https://stonecutter.kikugie.dev/wiki/tips/multiloader)). |
12 | | - |
13 | | -## Features |
14 | | - |
15 | | -* Single codebase for both Fabric and NeoForge |
16 | | -* Single codebase for multiple Minecraft versions |
17 | | -* CI/CD with GitHub Actions for automated builds and releases |
18 | | -* Separate build scripts for each platform |
19 | | - |
20 | | -## Getting Started |
21 | | - |
22 | | -### Prerequisites |
23 | | - |
24 | | -* Knowledge of Fabric and NeoForge |
25 | | -* Suitable IDE |
26 | | -* Java 21 or higher |
27 | | -* Git |
28 | | - |
29 | | -### Initial Setup |
30 | | - |
31 | | -#### 1. **Clone or use this template** |
32 | | - |
33 | | -```bash |
34 | | -git clone https://github.com/rotgruengelb/stonecutter-mod-template.git |
35 | | -cd stonecutter-mod-template |
36 | | -``` |
37 | | - |
38 | | -#### 2. **Open in your IDE** |
39 | | - |
40 | | -Import the project as a Gradle project |
41 | | -in your preferred IDE (e.g., IntelliJ IDEA, Eclipse). |
42 | | - |
43 | | -#### 3. **Stonecutter IntelliJ plugin** |
44 | | - |
45 | | -The IntelliJ plugin adds comment syntax highlighting and completion, |
46 | | -a button to switch the active version, alongside other utilities. |
47 | | - |
48 | | -#### 4. **Configure your mod** |
49 | | - |
50 | | -Edit `gradle.properties` to set your mod's metadata: |
51 | | - |
52 | | -| Property | Description | Example | |
53 | | -|--------------------|----------------------------------------------|-------------------------------------------------------------------| |
54 | | -| `mod.id` | Your mod’s identifier (lowercase, no spaces) | `modtemplate` | |
55 | | -| `mod.name` | Display name of your mod | `Mod Template` | |
56 | | -| `mod.group` | Java package group | `com.example` | |
57 | | -| `mod.version` | Mod version number | `0.1.0` | |
58 | | -| `mod.channel_tag` | Optional release channel tag | `-alpha.0` | |
59 | | -| `mod.authors` | Name of the author(s), comma-separated | `AuthorName` | |
60 | | -| `mod.contributors` | Contributor names, comma-separated | `ContributorName, AnotherContributorName` | |
61 | | -| `mod.license` | License type | `MIT` | |
62 | | -| `mod.description` | Short mod description | `Example Description` | |
63 | | -| `mod.sources_url` | Link to your source code repository | `https://github.com/rotgruengelb/stonecutter-mod-template` | |
64 | | -| `mod.homepage_url` | Mod homepage or info page | `https://github.com/rotgruengelb/stonecutter-mod-template` | |
65 | | -| `mod.issues_url` | Link to issue tracker | `https://github.com/rotgruengelb/stonecutter-mod-template/issues` | |
66 | | -| `mod.discord_url` | Link to a Discord invite | `https://discord.gg/aunYJB4wz9` | |
67 | | - |
68 | | -Dependencies/Properties that are specific to a version/loader |
69 | | -are defined in `gradle.properties` as `[VERSIONED]` then set in `versions/{version}-{loader}/gradle.properties`. |
70 | | - |
71 | | -#### 5. **Rename package structure** |
72 | | - |
73 | | -Rename the `com.example.modtemplate` package in |
74 | | -`src/main/java/` to match your `mod.group` and `mod.id`. |
75 | | - |
76 | | -#### 6. **Update resource files** |
77 | | - |
78 | | -Rename these files to match your `mod.id`: |
79 | | - |
80 | | -* `src/main/resources/modtemplate.accesswidener` |
81 | | -* `src/main/resources/modtemplate.mixins.json` |
82 | | - |
83 | | -Replace and `src/main/resources/assets/icon.png` and `.idea/icon.png` with the mods icon. |
84 | | - |
85 | | -## Development |
86 | | - |
87 | | -### Stonecutter |
88 | | - |
89 | | -[Stonecutter](https://stonecutter.kikugie.dev/) allows multiple Minecraft versions and loaders in a single codebase. |
90 | | -Configure Stonecutter in `stonecutter.gradle.kts` and `settings.gradle.kts`. |
91 | | - |
92 | | -Example of platform-specific code using Stonecutter comments: |
93 | | - |
94 | | -```java |
95 | | -//? if fabric { |
96 | | -/*fabricOnlyCode();*/ |
97 | | -//?} else { |
98 | | -neoforgeOnlyCode(); |
99 | | -//?} |
100 | | -``` |
101 | | -Verson-specific code works similarly: |
102 | | - |
103 | | -```java |
104 | | -//? if 1.21.7 { |
105 | | -LOGGER.info("hello 1.21.7!"); |
106 | | -//?} else { |
107 | | -/*LOGGER.info("hello from any other version!"); |
108 | | - *///?} |
109 | | -``` |
110 | | - |
111 | | -For more details, read the [Stonecutter documentation](https://stonecutter.kikugie.dev/wiki/). |
112 | | - |
113 | | -### Running in Development |
114 | | - |
115 | | -The Gradle plugins of the respective platform should provide run configurations. |
116 | | -If not, you can run the server and client with the respective Gradle tasks. |
117 | | -Be careful to run the correct task for the selected Stonecutter platform and Minecraft version. |
118 | | - |
119 | | -### Platform Abstraction |
120 | | - |
121 | | -The template uses a platform abstraction pattern to keep shared code loader-agnostic: |
122 | | - |
123 | | -* **Shared code** goes in `com.example.modtemplate` (no platform dependencies) |
124 | | -* **Platform-specific code** goes in `com.example.modtemplate.platform.{fabric|neoforge}` |
125 | | -* The `Platform` interface provides loader-specific functionality to shared code |
126 | | - |
127 | | -### Adding Dependencies |
128 | | - |
129 | | -To add dependencies for a specific platform, modify the `platform` block in the respective `build.gradle.kts` file. |
130 | | -The declared dependencies are automatically added to the metadata file for the loader and when publishing the mod to |
131 | | -mod hosting platforms. |
132 | | -**Important:** This does not replace the `dependencies` block! |
133 | | - |
134 | | -```kotlin |
135 | | -platform { |
136 | | - loader = "fabric" // or "neoforge" |
137 | | - dependencies { |
138 | | - required("my-lib") { |
139 | | - slug("my-lib") // Mod hosting platform slug (here the slug is the same on both Modrinth and CurseForge) |
140 | | - versionRange = ">=${prop("deps.my-lib")}" // version range (for fabric.mod.json) |
141 | | - forgeVersionRange = |
142 | | - "[${prop("deps.my-lib")},)" // version range (for neoforge mods.toml), uses Maven version range syntax |
143 | | - } |
144 | | - } |
145 | | -} |
146 | | -``` |
147 | | - |
148 | | -### Data Generation |
149 | | - |
150 | | -Run Fabric data generation to create recipes, tags, and other data: |
151 | | - |
152 | | -```bash |
153 | | -./gradlew :1.21.7-fabric:runDatagen |
154 | | -``` |
155 | | - |
156 | | -Generated files appear in `src/main/generated/`. |
157 | | -The current setup uses Fabric data generation for both platforms. |
158 | | - |
159 | | -## Resouerces and Links |
160 | | -- [Stonecutter Documentation](https://stonecutter.kikugie.dev/wiki/) |
161 | | -- [NeoForge Documentation](https://docs.neoforged.net/docs/gettingstarted/) |
162 | | -- [Fabric Documentation](https://docs.fabricmc.net/develop/) |
163 | | -- [Pre-commit](https://pre-commit.com/) |
164 | | -- [Git Source Control](https://git-scm.com/doc) |
165 | | -- [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) |
166 | | -- [Semantic Versioning](https://semver.org/) |
167 | | - - [How to denote a pre-release version](https://semver.org/#spec-item-9) |
168 | | -- [Your Modrinth PAT](https://modrinth.com/settings/pats) |
169 | | -- [Your CurseForge API Tokens](https://legacy.curseforge.com/account/api-tokens) |
170 | | -- [GitHub Actions Documentation](https://docs.github.com/en/actions) |
171 | | -- [Gradle Documentation](https://docs.gradle.org/current/userguide/userguide.html) |
172 | | - |
173 | | -### Help and Support |
174 | | -For help and support, consider the following places: |
175 | | -- ["Kiku's Realm" Discord Server](https://discord.kikugie.dev/) for Stonecutter-related questions. |
176 | | -- ["Cascading Colors" (My) Discord Server](https://discord.gg/aunYJB4wz9) for questions about this template and its setup. |
177 | | -- ["The NeoForge Project" Discord Server](https://github.com/neoforged) for NeoForge-related questions. |
178 | | -- ["The Fabric Project" Discord Server](https://discord.gg/v6v4pMv) for Fabric-related questions. |
179 | | - |
180 | | -## License/Credits |
181 | | - |
182 | | -This template is provided under the MIT License. |
183 | | -Check `LICENSE` for details. |
184 | | - |
185 | | -* Based on [murderspagurder/mod-template-java](https://github.com/murderspagurder/mod-template-java) |
186 | | - * Adapted from [KikuGie's Elytra Trims](https://github.com/kikugie/elytra-trims) setup |
187 | | -* Uses [Stonecutter](https://stonecutter.kikugie.dev/) by KikuGie |
0 commit comments