Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/SpongePowered/Mixin

Mixin is a trait/mixin and bytecode weaving framework for Java using ASM
https://github.com/SpongePowered/Mixin

annotations asm gradle java minecraft mixin-framework mixins processor trait

Last synced: 11 days ago
JSON representation

Mixin is a trait/mixin and bytecode weaving framework for Java using ASM

Host: GitHub
URL: https://github.com/SpongePowered/Mixin
Owner: SpongePowered
License: mit
Created: 2014-12-04T03:57:51.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2024-08-05T04:16:27.000Z (3 months ago)
Last Synced: 2024-10-29T15:19:44.476Z (12 days ago)
Topics: annotations, asm, gradle, java, minecraft, mixin-framework, mixins, processor, trait
Language: Java
Homepage:
Size: 7.36 MB
Stars: 1,418
Watchers: 55
Forks: 192
Open Issues: 96
Metadata Files:
- Readme: README.MD
- License: LICENSE.txt

Awesome Lists containing this project

awesome-java - Mixin - Manipulate bytecode at runtime using real Java code. (Projects / Bytecode Manipulation)
awesome-java-zh - Mixin - 使用真正的Java代码在运行时操作字节码。 (项目 / 字节码操作)
awesome-java - Mixin - Manipulate bytecode at runtime using real Java code. (Projects / Bytecode Manipulation)

README

### [![Build Status](http://ci.liteloader.com/view/Other/job/Mixin/badge/icon)](http://ci.liteloader.com/view/Other/job/Mixin/lastSuccessfulBuild/)

![Mixin Logo](docs/javadoc/resources/logo.png?raw=true)

**Mixin** is a trait/mixin framework for Java using [ASM](https://asm.ow2.io/)
and hooking into the runtime classloading process via a set of pluggable
built-in or user-provided services. Built-in services currently support Mojang's
[LegacyLauncher](https://github.com/Mojang/LegacyLauncher) system, though this
is deprecated in favour of [ModLauncher](https://github.com/cpw/modlauncher) by
cpw, which has greater extensibility and has support for Java 8 and later.

### Documentation

The main documentation for **Mixin** can be found in the
[Wiki](https://github.com/SpongePowered/Mixin/wiki).

Additional documentation for individual features and annotations can be found in
the extensive [Javadoc](http://jenkins.liteloader.com/job/Mixin/javadoc/). For
additional help use the channel [`#mixin` on the Sponge Discord Server](https://discord.gg/tBcwxz2).

### Binaries

Mixin binaries are available via [Jenkins](https://jenkins.liteloader.com/view/Other/job/Mixin/)
and are published to the following maven repositories:

* https://repo.spongepowered.org/repository/maven-public/ - SNAPHOTs and RELEASE
builds
* https://files.minecraftforge.net/maven/ - RELEASE builds only

### Tooling

For handling obfuscation tasks, Mixin provides an [Annotation Processor](https://github.com/SpongePowered/Mixin/wiki/Using-the-Mixin-Annotation-Processor)
which works at compile time to generate obfuscation mappings for your toolchain
to apply. If using Gradle 5 or later, annotation processors are no longer
automatically loaded from `compile` configurations and must be specified
explicitly via `annotationProcessor` configurations. For this purpose, Mixin
provides "fat jar" artefacts containing all required dependencies via the
`:processor` classifier. For example if your build uses the dependency
`org.spongepowered:mixin:1.2.3` then your annotationProcessor configuration
should specify dependency `org.spongepowered:mixin:1.2.3:processor`.

If you are using Mixin in a [Minecraft Forge](https://minecraftforge.net/)
project then the [MixinGradle](https://github.com/SpongePowered/MixinGradle)
plugin can be used to simplify the configuration of the Mixin Annotation
Processor. It provides a simple syntax for configuring the Mixin AP for your
project, see the [MixinGradle README](https://github.com/SpongePowered/MixinGradle/blob/master/README.md)
for how to configure MixinGradle.

### Integration with Eclipse

When developing using **Mixin**, you can use the **Mixin Annotation Processor**
within Eclipse to provide context-sensitive errors and warnings to help you more
easily troubleshoot your mixins. To do so:

1. Run the `gradle build` command to generate the mixin jar
2. Open the properties of your eclipse project and navigate to `Java Compiler`
-> `Annotation Processing` -> `Factory Path`
3. Check the `Enable project specific settings` checkbox
4. Click the `Add External JARs` button and select the generated mixin jar with
the suffix **-processor** (hint: it should be in `Mixin/build/libs`)
5. Navigate up one level to `Java Compiler` -> `Annotation Processing`
6. Check the `Enable project specific settings` checkbox
7. Check the `Enable annotation processing` checkbox
8. Click the `New...` button next to the `Processor options` box
* Set `Key` to **reobfSrgFile**
* Set `Value` to the fully-qualified path to the `mcp-srg.srg` file (the
location of the mapping file varies by platform, if you are unsure where to
find it please follow the discord link below).
9. Click `OK` to apply the changes

### Integration with IntelliJ IDEA

Enhanced functionality for working with **Mixin** in IntelliJ IDEA is available
via the [Minecraft Development for IntelliJ IDEA](https://plugins.jetbrains.com/idea/plugin/8327)
plugin developed by [DemonWav](https://github.com/demonwav).

### Version History

[Specifying the `minVersion` property in your configurations](https://github.com/SpongePowered/Mixin/wiki/PSA-Forward-Compatibility-Features-in-Mixin)
is extrememly important. The following version history can be used to determine
when features were introduced (and sometimes when major bugs are squashed) in
order to help you determine which `minVersion` you should specify.

Version
Date
Features / Changes

0.8.3
February 2021

Added dynamic target selector support and @Desc
target selector

Added pattern target selector

Added more expressive quantifier support to explicit target
selectors

Facelift and overall improvements to javadoc

0.8.1 (0.8.2)
September 2020

Hotfix for supporting ModLauncher 7.0

Fix critical issue with resolving obfuscated members in inherited
interfaces

Updated to ASM 7.2

0.8
January 2020

Updated to ASM 6.2

Support for
ModLauncher

Added recognition for Java 9 and 10

Support for ForgeGradle 3+ tsrg obfuscation tables

Configs can now inherit from other configs

@Invoke can now be used to expose constructors

Dramatically improved context reporting of unexpected applicator
and preprocessor exceptions, making it easier to diagnose when an
agent chokes on a specific opcode

Bug fixes for
- Calling members of accessor mixins from inside mixin code
- Incorrect handling of spaces in explicit target declarations
- Unexpected behaviour when attempting to redirect a ctor
- Properly detect incompatible accessor overlap and ignore valid
  ones (don't warn)
- Interface static accessors now correctly conform target if
  interface is classloaded before target class
- Staticness mismatch for accessor correctly detected and
  reported instead of causing crash
- Fixed generator and injector errors relating to double-word
  operands on the stack needing DUP2
- Fixed issue in LVT generator folded in from FabricMC
- Fail-fast when a final method is accidentally hidden
  by a mixin
- Fix the appearance of stray CallbackInfo instances in
  local capture injector LVTs

Apache Commons-IO Dependency removed

Renamed shaded ASM removed

Improved resolution of local variables for local variable capture
injections

@Coerce on callback injectors and redirects can now
resolve super interfaces including mixed-in interfaces

0.7.11
July 2018

Fixes for 3 minor bugs: handling of maxShiftBy fixed, improved
BeforeInvoke permissive search, disable generic signature merging
unless decompiler is active.

0.7.10
June 2018

Log an error when a mixin class is subject to classloader restrictions

0.7.9
April 2018

Allow certain injectors to target mixin methods.

0.7.8
April 2018

Bug fixes for member declaration validation, non-wild ctor redirects,
and internal errors in Args subclass generator

0.7.7
March 2018

Fixes for handling of log message triggers for INIT phase and error
when running with unexpected logger configurations

Add warnings for invalid slice points and narrowing conversion in
ModifyConstant handlers

0.7.6
November 2017

Fix inheritance for string system properties

0.7.5
October 2017

Add support for @Coerce on redirect injectors.

0.7.4
September 2017

Added @Dynamic annotation for decorating mixin
elements with dynamically-injected targets.

0.7.3
August 2017

Internal changes to provide for support modlauncher and java 9

0.7.2
August 2017

Add profiler for inspecting mixin performance.

0.7.1
August 2017

Fixes and improvements to the Mixin AP, fixing handling of multi-
dimensional arrays and resolving methods in superclasses of derived
types of obfuscated classes

Add runtime refmap remapping to support using deobfCompile
dependencies with different mapping versions.

0.7
July 2017

All official binaries are now signed

Upgrade to ASM 5.2

Add support for inner classes in Mixins

Injectors can now have multiple explicit targets

@At annotations can now have their own id

Add support for using @Overwrite on non-obfuscated
methods as a way of verifying that an overwrite target exists

Improve support for synthetic bridges, detect conflicting bridge
methods

Detect and warn of excessive At.Shift.BY values

ModifyConstant can now support multiple slices

Add allow to injectors to detect over-injection

0.6.15
July 2017

Add support for multiple constants in ModifyConstant

Add CONSTANT as general-purpose injection point

Add support for redirecting array length access in field
redirectors

0.6.14
July 2017

Add support for using @Coerce on reference types in
Callback Injectors to support derived types.

0.6.13
July 2017

Add support for conforming visibility of overwrite methods to
match target class. Fixes issues where a target class method has been
modified by an Access Transformer to have higher visibility

0.6.12
June 2017

Add slice argument to @ModifyConstant

Add @ModifyArgs injector which can change multiple
method call arguments with a single handler.

0.6.11
June 2017

Fix handling of @Unique when the same unique method
exists in more than one mixin targetting the same class

Fix handling of merged lambdas so that lambdas from mixins are
applied correctly when lambdas already exist in the target class (both
in the original class and when applied by earlier mixins)

0.6.10
May 2017

(0.6.9) Minor fix to remove dependence on deprecated helper

Respect remap on Mixin for contained @At

Require redirectors which occur before call to superctor to be static

0.6.8
February 2017

Allow @ModifyConstant to hook implicit zero in comparisons

0.6.7
January 2017

Add support for @Redirect on array access

0.6.6
January 2017

Allow static methods in accessor mixins in Java 8 and above

0.6.5
January 2017

Add support for injector slices

0.6.4
January 2017

Allow descriptors on NEW injection points

0.6.3
December 2016

SourceDebugExtension support

0.6.2
December 2016

Add support for @Pseudo (virtual target) mixins

0.6.1
November 2016

Process soft-implements annotations in the AP

0.6
October 2016

Accessor Mixin support

0.5.17
October 2016

Allow @Redirect injectors to target NEW opcodes for
constructor redirection

0.5.16
October 2016

Annotation Processor improvements. Support shadows and overrides
in multi-target mixins

Support pluggable obfuscation environments in AP

0.5.14
September 2016

Add async decompilation support

0.5.13
September 2016

Add alternative strategy for injecting field initialisers

0.5.10
June 2016

Support @Unique on fields

0.5.9
June 2016

Hard fail if a required mixin target was already transformed

0.5.8
June 2016

Support constraints on injectors

0.5.7
June 2016

Add @Unique annotation

0.5.6
May 2016

Environment changes, support environment via agents

0.5.5
April 2016

Add @ModifyConstant injector

Add @Debug annotation

Allow static @ModifyArg handlers in instance methods

0.5.4
April 2016

Error handlers also receive mixin prepare errors

0.5.3
February 2016

Conform injectors

Enable hotswapper automatically if agent is active

Fix multiple issues with generics in Annotation Processors

0.5.2
February 2016

Support ID on injectors

Support priority for injectors

0.5.1
February 2016

Overhaul injectors, injectors from all mixins now scan before any
injectors are actually processed. Makes injectors more deterministic.

0.4.19
February 2016

Add support for @Redirect on fields as well as methods

0.4.18
February 2016

Add @ModifyLocal injector

0.4.17
January 2016

Support ExtraSRGs in Annotation Processor

Include constructors in reference map

Add @Mutable annotation to suppress @Final warnings

0.4.15
January 2016

Include soft targets in refmap

0.4.14
January 2016

Add support for interface mixins

0.4.13
January 2016

Add @Final annotation

0.4.11
January 2016

Add support for injector grouping and config-wide require value

0.4.10
December 2015

Runtime remapping support using RemapperChain

Ignore class transformers decorated with @Resource

Support @reason and @author validation on overwrites

0.4.8
December 2015

Annotation Processor improved to support

MixinGradle

Support multiple target obfuscation environments in refmaps

0.4.6
September 2015

Add INIT phase for handling early FML startup

Add support for lambdas in mixins

Add support for hot code replacement in mixins

Improve Java 8 feature support

0.4.4
July 2015

Add constraints for overwrites

0.4.3
May 2015

Add INVOKE_ASSIGN injection point

Support injector callbacks without args

Support coercion of covariant parameter types in callbacks

Support truncating local-capturing injector handlers

Runtime decompilation of exported classes using fernflower

Add export filter

0.4
May 2015

Shade relocated ASM package and use throughout

0.3.2
April 2015

Error handler support

0.3.1
April 2015

Annotation Merging

Allow Overwrite methods to be aliased

0.3
March 2015

Implemented Environments

Intrinsic method support

Enabled local variable capture

Alias support

0.2
March 2015

Added supermixin support (mixins inheriting from other mixins)

0.1
January 2015

Basic Mixin Support

Basic Injector Support

Annotation Processor