Merge pull request #7 from TheElan/add-migration-instructions

add documentation for mod migration and porting
This commit is contained in:
Johann Bernhardt authored and GitHub committed 2021-11-07 19:31:15 +01:00
commit 4502bb39d7
3 files changed
+94 -7

No files matched your search

+11 -7
View File
@@ -11,6 +11,7 @@ We had our fair share in struggles with build scripts for Minecraft Forge. There
### Getting started
Creating mod from scratch:
1. Fork this repository (you can keep the fork to simplify merging any build script updates in the future)
2. Clone repository
3. Replace placeholders (edit values in gradle.properties, change example package and class names, etc.)
@@ -18,6 +19,8 @@ We had our fair share in struggles with build scripts for Minecraft Forge. There
5. Make sure to checkout the rest sections of this file.
6. You are good to go!
We also have described guidelines for existing mod [migration](docs/migration.md) and [porting](docs/porting.md)
### Features
- Updatable: Replace [`build.gradle`](https://github.com/SinTh0r4s/ExampleMod1.7.10/blob/main/build.gradle) with a newer version
@@ -40,23 +43,24 @@ We had our fair share in struggles with build scripts for Minecraft Forge. There
- [`jitpack.yml`](https://github.com/SinTh0r4s/ExampleMod1.7.10/blob/main/jitpack.yml): Ensures that your mod is available as import over [Jitpack](https://jitpack.io).
- [`.github/workflows/gradle.yml`](https://github.com/SinTh0r4s/ExampleMod1.7.10/blob/main/.github/workflows/gradle.yml): A simple CI script that will build your mod any time it is pushed to `master` or `main` and publish the result as release in your repository. This feature is free with GitHub if your repository is public.
### Feedback wanted
If you tried out this build script we would love to head your opinion! Is there any feature missing for you? Did something not work? Please open an issue and we will try to resolve it asap!
### Forge's Access Transformers
You may activate Forge's Access Transformers by defining a configuration file in `gradle.properties`.
Check out the [`example-access-transformers`](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-access-transformers) brach for a working example!
### For Advanced Modders: Mixins
### Mixins
You may activate Mixin in 'gradle.properties'. In that case a mixin configuration (usually named `mixins.mymodid.json`) will be generated automatically, and you only have to write the mixins itself. Dependencies are handled as well.
Take a look at the examples in [`com.myname.mymodid.mixinplugin.*`](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-mixins/src/main/java/com/myname/mymodid/mixinplugin) and [`com.myname.mymodid.mixins.*`](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-mixins/src/main/java/com/myname/mymodid/mixins). The use of a MixinPlugin allows the injection into any mod and not just vanilla Minecraft.
Mixins are usually used to modify vanilla or mod/library in runtime without having to change source code. For example, redirect a call, change visibility or make class implement your interface. It's an advanced topic and most mods don't need to do that.
You can activate Mixin in 'gradle.properties'. In that case a mixin configuration (usually named `mixins.mymodid.json`) will be generated automatically, and you only have to write the mixins itself. Dependencies are handled as well.
Take a look at the examples in [`com.myname.mymodid.mixinplugin.*`](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-mixins/src/main/java/com/myname/mymodid/mixinplugin) and [`com.myname.mymodid.mixins.*`](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-mixins/src/main/java/com/myname/mymodid/mixins).
Check out the [`example-mixins`](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-mixins) brach for a working example!
### Feedback wanted
If you tried out this build script we would love to head your opinion! Is there any feature missing for you? Did something not work? Please open an issue and we will try to resolve it asap!
Happy modding, \
[SinTh0r4s](https://github.com/SinTh0r4s), [TheElan](https://github.com/TheElan) and [basdxz](https://github.com/basdxz)
+27
View File
@@ -0,0 +1,27 @@
# Migration guides
## Generic migration
Migration for the typical mod which doesn't use anything special but Minecraft forge and some library dependencies.
For core plugin, Mixins, shadowing, access transformers, ASM or etc. you'll need to do some extra steps.
If they are missing in this document - we will gladly receive your suggestions/contribution.
1. Copy and replace all files from template to your repository, but:
1. `build.gradle`
2. `src`
3. `LICENSE`
4. `README.md`
5. `build.gradle(.kts)`
2. Copy all repositories from your `build.gradle(.kts)` to `repositories.gradle`
3. Copy all dependencies from your `build.gradle(.kts)` to `dependecies.gradle`
4. replace your `build.gradle(.kts)` with `build.gradle` from template. In case you have written some custom tasks/configurations not present in the template - you'll best to move them to separate file and link it in this, like for example it does this with `dependencies.gradle`
5. Adapt `gradle.properties` to your mod
6. Ensure `src/main/resources/mcmod.info` contains `${modId}`, `${modName}`. `${modVersion}` and `${minecraftVersion}`
7. Re-import the project to your IDE (e.g. restart with clean caches in IntelliJ IDEA)
8. Run `./gradlew clean setupDecompWorkspace`
## Mixin configuration
For the reference checkout the [example mixin configuration branch](https://github.com/SinTh0r4s/ExampleMod1.7.10/tree/example-mixins) of the template.
1. Extract mixins package and plugin configuration from `mixins.yourModId.json` to `gradle.properties`
2. Implement MixinPlugin according to example from the reference
3. Remove mixins.mymodid.json
+56
View File
@@ -0,0 +1,56 @@
# Porting guidelines
This is a list of steps which should help you on your probably not so easy journey of porting some mod:
### 1. Setting up repository and build system
1. Checkout any information in mod REAMDE/Wiki/Docs to find out if there are any special tasks/configs that need to be applied to the build
2. Fork original repository to preserve commit history
3. Apply build migration as explained in [migration guidelines](migration.md) on your fork
### 2. Refining the fork
Try to get rid of dependencies on concrete jars (usually in the `lib` folder) if any present. This way it will be much easier to change (upgrade/downgrade) your project dependencies, when needed.
Check if they are in maven repository (usually authors put such information in the project readme), if it isn't accessible but project is open source with permissive enough license (e.g., MIT) - you still can publish them yourselves:
1. Fork the repository
2. Drop `jitpack.yml` and `.github/workflows/gradle.yml` in project root. You can find this file in this repository root.
3. Make sure everything builds from console by running `./gradlew clean setupCIWorkspace`
4. If all is fine/after fixing the errors - make a tag on Github or using console, this should trigger Github build hook and generate a release
4. Lookup forked repository on `https://jitpack.io/`
5. Find your release and click "Get it", which should scroll you down to the example of how to add the dependency (make sure you have jitpack repository in mod you are porting)
6. Checkout build log beside button you clicked to make sure it succeeds
Now when you are sure dependency is available in maven repository - just add it as a normal gradle dependency in `dependencies.gradle`.
If there is not online dependency available, you may upload it as a jar to jitpack, see [jitpack single file publishing thread](https://gist.github.com/jitpack-io/f928a858aa5da08ad9d9662f982da983). Please ensure, that you have the rights to do so!
There may also be a case where mods depend on another mods - then you'll need to port any dependencies first. (Yay, dependency hell! :D)
### 3. Preparing for porting
Try to build the project and see check what types of errors are you getting. Generally, there should be 2 types of errors you encounter:
- Missing references to packages/classes/methods/fields/parameters. Things get renamed, moved, restructured, removed or even not yet exist. That's the straightforward part - you'll need to adjust references and way things are invoked.
In case of missing things, you'll either need to implement something that's imitates missing parts or resign from some functionality
- Build related errors (e.g., something that is a part of the mod in never versions previously was an external library - you'll need to add it as a dependencies)
Fix all build related errors (so build system won't get in your way)
### 4. Porting the mod
After all these preparations nothing should be in the way of porting the mod, the only thing left is the actual code to change, which probably is a most tedious part of this process.
Good approach is to start working with smaller things first, building up your confidence in how the mod works and gradually approaching more complex stuff, here is a general algorithm:
1. Begin with fixing moved/renamed things by deleting all bad imports and with help of the IDE re-import equivalents if present.
Intelij IDEA has settings for unambiguous auto-import and import optimization on the fly, which can greatly speedup the process. Just pay attention to what is actually imported.
2. Remove all nonworking code which is not easily fixable (e.g., class only introduced in newer forge) and provide stubs in its place.
For example, replace reference to method of non existing class with your method in your class, it can have an empty body and mocked return so the code can compile and run without issues.
Do not forget to track all things you've stubbed, if you are working on port alone - TODOs should be sufficient (most IDEs have a built in TODO browser).
3. Build the project and attempt to run it
4. If there were any critical errors which cause Minecraft to crash or mod to not work - try fixing them first, so you can test your changes
5. Start fixing small things, ones that you think you have most chances to fix and work your way up
6. If any there is any feature that is not worth it's time or you simply don't know how to do it - consider dropping it entirely and open an issue in your repository where you'll explain your findings and blockers.
Maybe somebody with greater knowledge/more time/motivation will try to take bite at it.
9. Fix bugs you've introduced when porting.
It is uncommon for mods to have lots of workarounds and hidden connections.
You'll need to test things and check if they work as intended (gl;hf ;p)
### 5. Final words
If after reading this, you are not discouraged and still want to port it - good luck porting it! You'll definitively need it.