Add a detailed Mixin tutorial in advanced area.

.gitignore

@@ -21,3 +21,6 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+/.vs/Documentation/FileContentIndex
+/.vs/Documentation/v17
+/.vs

docs/advanced/mixin/1.preparation.md

@@ -0,0 +1,148 @@
+Preparation
+===========
+
+Edit Your ```build.gradle```
+----------------------
+
+Apply the mixin plugin.
+```groovy
+plugins {
+ id 'org.spongepowered.mixin' version '0.7.+'
+}
+```
+
+Add run arguments to gradle tasks.
+```groovy
+minecraft {
+ runs {
+ client {
+ property 'forge.enabledGameTestNamespaces', mod_id
+ args "-mixin.config=${mod_id}.mixins.json" // add this line
+ }
+ server {
+ property 'forge.enabledGameTestNamespaces', mod_id
+ args '--nogui'
+ args "-mixin.config=${mod_id}.mixins.json" // add this line
+ }
+ data {
+ workingDirectory project.file('run-data')
+ args '--mod', mod_id, '--all', '--output', file('src/generated/resources/'), '--existing', file('src/main/resources/')
+ args "-mixin.config=${mod_id}.mixins.json" // add this line
+ }
+ }
+}
+```
+
+Add the mixin config block before ```repositories``` block
+```groovy
+mixin {
+ add sourceSets.main, "${mod_id}.refmap.json"
+}
+```
+
+Add the mixin annotation processors in the ```dependencies``` block
+```groovy
+dependencies {
+ minecraft "net.neoforged:forge:${minecraft_version}-${neo_version}"
+ annotationProcessor 'org.spongepowered:mixin:0.8.5:processor' // add this line
+}
+```
+
+Add the mixin config file in the manifest
+```groovy
+'Specification-Title' : mod_id,
+'Specification-Vendor' : mod_authors,
+'Specification-Version' : '1', // We are version 1 of ourselves
+'Implementation-Title' : project.name,
+'Implementation-Version' : project.jar.archiveVersion,
+'Implementation-Vendor' : mod_authors,
+'Implementation-Timestamp': new Date().format("yyyy-MM-dd'T'HH:mm:ssZ"),
+'MixinConfigs': "${mod_id}.mixins.json" // add this line
+```
+Save the file and sync the gradle project.
+
+Create Mixin Config Class
+---------------------------
+All classes related to mixin must be in a separate package, which is called "mixin package". So you can create a package called ```mixin```.
+
+Then create a class called ```MixinPlugin``` in the ```mixin``` package and implement the interface ```IMixinConfigPlugin```. The IDE will instruct you to implement all methods. This will be a mixin config class.
+
+```java
+public class MixinPlugin implements IMixinConfigPlugin {
+ private boolean isModInstalled;
+ @Override
+ public void onLoad(String mixinPackage) {
+ try{
+ Class.forName("com.example.modid.ExampleMod"); // Your main class
+ isModInstalled = true;
+ } catch (ClassNotFoundException e) {
+ isModInstalled = false;
+ }
+ }
+
+ @Override
+ public String getRefMapperConfig() {
+ return null;
+ }
+
+ @Override
+ public boolean shouldApplyMixin(String targetClassName, String mixinClassName) {
+ return isModInstalled;
+ }
+
+ @Override
+ public void acceptTargets(Set<String> myTargets, Set<String> otherTargets) {
+ }
+
+ @Override
+ public List<String> getMixins() {
+ return null;
+ }
+
+ @Override
+ public void preApply(String targetClassName, ClassNode targetClass, String mixinClassName, IMixinInfo mixinInfo) {
+ }
+
+ @Override
+ public void postApply(String targetClassName, ClassNode targetClass, String mixinClassName, IMixinInfo mixinInfo) {
+ }
+}
+```
+
+Create Mixin Config File
+-------------------
+The config file will be like this, which can be named "mod_id.mixins.json" and should be in your ```resources``` folder
+```json
+{
+ "required": true,
+ "package": "com.example.modid.mixin",
+ "compatibilityLevel": "JAVA_17",
+ "minVersion": "0.8",
+ "refmap": "modid.refmap.json",
+ "plugin": "com.example.modid.mixin.MixinPlugin",
+ "mixins": [
+
+ ],
+ "client": [
+
+ ],
+ "injectors": {
+ "defaultRequire": 1
+ }
+}
+```
+You should mainly care about 4 of those properties:
+
+```package``` - The path of your mixin package.
+
+```plugin``` - The path of the mixin config class you created above.
+
+```mixin``` - The array contains your mixin classes that will be applied to both sides.
+
+```client``` - The array contains your mixin classes that will only be applied to the client side.
+
+Here, you have accomplished all the preparations.
+
+:::caution
+Please be careful about file references (i.e. package and class names) in those config files. Any mistakes may take the Mixin system down.
+:::

docs/advanced/mixin/2.mixinclass.md

@@ -0,0 +1,36 @@
+Mixin Class
+===========
+
+A mixin class is a special class that contains mixin codes that be applied to its target class. A mixin class can only have one target class, which is designated by the class annotation ```@Mixin```.
+
+None of the mixin classes will be instantiated, as they will only be compiled to bytecodes and then applied in target classes. Therefore, the mixin classes can be abstract.
+
+Here is an example of a mixin class.
+
+```java
+@Mixin(TargetClass.class)
+public abstract class TargetClassMixin {
+
+}
+```
+All mixin classes must be specified in the mixin config file like this, either for the client side only or both sides. Otherwise, they will not take any effects.
+
+```json
+{
+ "required": true,
+ "package": "com.example.modid.mixin",
+ "compatibilityLevel": "JAVA_17",
+ "minVersion": "0.8",
+ "refmap": "modid.refmap.json",
+ "plugin": "com.example.modid.mixin.MixinPlugin",
+ "mixins": [
+ "TargetClassMixin"
+ ],
+ "client": [
+
+ ],
+ "injectors": {
+ "defaultRequire": 1
+ }
+}
+```

docs/advanced/mixin/3.inject.md

@@ -0,0 +1,133 @@
+@Inject
+======
+Injection is the most used technology which can "insert" your codes to a certain place of a certain vanilla method.
+
+Injection is similar to the [Events][events] system, where every event can be considered as an injection point and you can inject your codes through listener methods. But injection is more flexible because:
+
+- The Event system may not cover any situations but mixin injection can cover all vanilla methods.
+- The Event system reuses codes for different objects but mixin injection can be specific to each class.
+
+Basic
+-----
+
+### Injection Method
+
+Injection methods are some special methods in Mixin that will not be invoked directly. Their codes will be injected into their target methods. Injection methods are annotated with ```@Inject```. Such an annotation is used to specify the target method, injection position, and other configurations.
+
+Two parameters are mandatory in ```@Inject```:
+
+- ```method``` - The name of the target method, which should be in the target class. If the method is overloaded, it should be specified by the descriptors, which will be discussed later.
+- ```at``` - The injection position in the target method. 
+
+The most common positions for ```at``` are:
+
+- ```HEAD``` - At the start of the method
+- ```TAIL``` - At the end of the method
+- ```RETURN``` - Before every return statement of the method
+
+The name of the injection method can be different from the target method while the types and sequences of the parameters should not be changed. Additionally, there is an extra parameter that should be appended to the parameter list of the injection method. 
+
+- ```CallbackInfo``` - If the target method is void.
+- ```CallbackInfoReturnable<ReturnType>``` - If the target method has a return value.
+
+
+Here is an example of injection method
+
+```java
+@Inject(method = {"methodName"}, at = {@At("HEAD")})
+public void onMethodName(Type1 param1, Type2 param2, CallbackInfoReturnable<Boolean> ci){
+ ...
+}
+```
+
+whose target is
+```java
+public boolean methodName(Type1 param1, Type2 param2){
+ ...
+}
+```
+
+Constructors are also treated as methods with name ```<init>``` but not ```init```. Here are some different situations when injecting into the constructors.
+
+- To inject into non-parameterized constructors, or there is only one constructor no matter whether parameterized or non-parameterized, the method should be ```method = {"<init>"}```. 
+
+- To inject into parameterized and overloaded constructors, the method should be specified by the descriptors, which will be discussed later.
+
+- To inject into all constructors, the method should be ```method = {"<init>*"}```.
+
+- The injection position of constructors can only be ```TAIL``` or ```RETURN```.
+
+- To inject into static blocks, the method should be ```method = {"<clinit>"}```
+
+
+
+### Injection Codes
+Injection codes are the codes in the injection methods that will be injected into the target methods.
+
+Most time you can complete the injection codes as if they were in the corresponding places of target methods. But to access fields or invoke methods, you should use [Shadow][shadow]. 
+
+Additionally, ```this``` cannot be directly used to refer to the target instance as the codes are in the mixin class. You should cast ```this``` to ```Object``` and then to the target class. It may seem strange elsewhere, but it is normal in Mixin.
+
+```java
+TargetClass self = (TargetClass) (Object) this;
+```
+
+If you want to end the methods in advance, or "return" the target method in your injection codes, you should add an optional parameter ```cancellable``` to the annotation.
+
+```java
+@Inject(method = {""}, at = {@At("")}, cancellable = true)
+```
+
+Then use ```CallbackInfo#cancel()``` to end the target method if it is void
+or use ```CallbackInfoReturnable#setReturnValue(T)``` to set the return value and end the target method.
+
+Advanced
+--------
+
+### Method Overloading
+
+Methods with different parameter types can have the same name. This is called method overloading, such as ```methodName(int)``` and ```methodName(int,int)```
+
+To inject into overloaded methods, you should explicitly designate the method name as well as their descriptors in the ```()```. The following [Oracle's document][doc] can help you to finish this. Accordingly, the parameters of their injection methods are also different.
+
+| FieldType term | Type | Interpretation |
+|----------------|-----------|-----------------------------------------------------------------------------------| 
+| B | byte | signed byte |
+| C | char | Unicode character code point in the Basic Multilingual Plane, encoded with UTF-16 |
+| D | double | double-precision floating-point value |
+| F | float | single-precision floating-point value |
+| I | int | int integer |
+| J | long | long integer |
+| L ClassName ; | reference | an instance of class ClassName |
+| S | short | signed short |
+| Z | boolean | true or false |
+| [ | reference | one array dimension |
+
+Therefore, the injection methods should be:
+
+```java
+@Inject(method = {"methodName(I)V"}, at = {@At("HEAD")})
+public void onMethodName(int param1, CallbackInfo ci){
+ ...
+}
+```
+and
+
+```java
+@Inject(method = {"messageName(II)V"}, at = {@At("HEAD")})
+public void onMethodName(int param1, int param2, CallbackInfo ci){
+ ...
+}
+```
+
+:::tip
+For overloaded constructors, the name is always ```method = {"<init>(...)V"}```. What you need to edit is the parameter type in (). 
+:::
+
+
+
+
+
+[events]: ../../concepts/events.md
+[shadow]: 4.shadow.md
+[doc]: https://docs.oracle.com/javase/specs/jvms/se14/html/jvms-4.html#jvms-4.3.2

docs/advanced/mixin/4.shadow.md

@@ -0,0 +1,46 @@
+@Shadow
+======
+
+Shadow is a technology that redirects the access of the fields and methods from the mixin classes to the vanilla classes. It allows you to use those elements like normal ones so that your method code can be simplified. It can also help you to access the private fields or methods in the target class. 
+
+Fields
+------
+Shadowed fields are annotated with ```@Shadow``` and have the same access modifiers, names, and types as the vanilla fields in the target class. 
+
+```java
+@Shadow
+<access modifier> <static or not> <type name> <field name>;
+```
+
+The Mixin system will automatically redirect your access to the corresponding fields in the target class.
+
+
+Methods
+-------
+Shadowed methods are annotated with ```@Shadow``` and have the same access modifiers, names, parameter types, and return types as the vanilla methods in the target class.
+
+If the vanilla method is not static, the shadowed method should be abstract.
+
+
+```java
+@Shadow
+<access modifier> abstract <type name> <method name>(parameter list...);
+```
+
+If the vanilla method is static, the shadowed method should be static and have a method body. The return value does not matter because this method is just a placeholder.
+```java
+@Shadow
+<access modifier> static <type name> <method name>(parameter list...){
+ return null; // for reference types
+ // return 0; // for primitives
+ // return false;
+}
+```
+
+The Mixin system will automatically redirect your access to the corresponding methods in the target class.
+
+:::tip
+Do not change field names, method names, parameter types, and sequences, or the shadow will not work.
+
+You can change parameter names.
+:::