Skip to content

Injection Point Reference

Jump to bottom
irtimaled edited this page Dec 30, 2017 · 2 revisions

Quick Navigation

Short Name Full Name
HEAD org.spongepowered.asm.mixin.injection.points.MethodHead
RETURN org.spongepowered.asm.mixin.injection.points.BeforeReturn
TAIL org.spongepowered.asm.mixin.injection.points.BeforeFinalReturn
INVOKE org.spongepowered.asm.mixin.injection.points.BeforeInvoke
INVOKE_STRING org.spongepowered.asm.mixin.injection.points.BeforeStringInvoke
INVOKE_ASSIGN org.spongepowered.asm.mixin.injection.points.AfterInvoke
FIELD org.spongepowered.asm.mixin.injection.points.BeforeFieldAccess
NEW org.spongepowered.asm.mixin.injection.points.BeforeNew
CONSTANT org.spongepowered.asm.mixin.injection.points.BeforeConstant

MethodHead

Overview

Short name HEAD
Full name org.spongepowered.asm.mixin.injection.points.MethodHead
Options None
Arguments None

Description

This injection point always returns the first instruction in the candidate list. When selecting within a method, this is always the first instruction in the method. When selecting in a slice, this is always the first instruction in the slice.

Notes

This injection point is guaranteed to select only 1 instruction.

BeforeReturn

Overview

Short name RETURN
Full name org.spongepowered.asm.mixin.injection.points.BeforeReturn
Options
ordinal
the ordinal of the RETURN instruction to select (indexed from 0)
Arguments None

Description

This injection point selects RETURN opcodes in the target instruction list. If ordinal is not specified, all RETURN instructions are selected.

ordinal search in result reason
Omitted Method 1 or more instructions method is guaranteed to always have at least 1 RETURN
Specified Method 0 or 1 instructions RETURN with matching ordinal may not be present
Omitted Slice 0 or more instructions Matches all RETURNs in slice, slice may not contain any
Specified Slice 0 or 1 instructions Matches one RETURNs in slice, slice may not contain a matching insn
### Notes This is the only injection point which is allowed to be used when an @Inject injector targets a constructor.

When used in combination with cancellable non-void injections this injection point will make the return type available within the CallbackInfoReturnable via the getReturnType() method.

BeforeFinalReturn

Overview

Short name TAIL
Full name org.spongepowered.asm.mixin.injection.points.BeforeFinalReturn
Options None
Arguments None

Description

This injection point returns the final RETURN opcode in the target method.

Notes

Note that the last RETURN opcode may not correspond to the notional "bottom" of a method in the original Java source, since conditional expressions can cause the bytecode emitted to differ significantly in order from the original Java.

BeforeInvoke

Overview

Short name INVOKE
Full name org.spongepowered.asm.mixin.injection.points.BeforeInvoke
Options
target
the invocation to target, must be fully-qualified if remapped
ordinal
the ordinal index of the matching invocation to select (selects all if omitted)
Arguments
boolean log
produces verbose output in the console as the injector scans a method, useful for diagnosing injectors which are behaving incorrectly or in unexpected ways

Description

This injection point searches for invoke instructions within the target instruction list and returns instructions which match the criteria. target should be a parsable MemberInfo which specifies an invocation to search for (omitting target will return all invoke instructions in the target). The ordinal specifies the index of the invocation to select, if omitted then all matching invocations are returned.

Notes

The ordinal value selects within the instructions matched by target, so if there are 4 invoke instructions in the target method, but only 2 match the value specified in target, then specifying ordinal=1 selects the second instruction matching target not the second invocation in the method. In other words, target is always applied before ordinal.

BeforeStringInvoke

Overview

Short name INVOKE_STRING
Full name org.spongepowered.asm.mixin.injection.points.BeforeStringInvoke
Options
target
the invocation to target, must be fully-qualified if remapped
ordinal
the ordinal index of the matching invocation to select (selects all if omitted)
Arguments
string ldc
constant value to match, see description
boolean log
produces verbose output in the console as the injector scans a method, useful for diagnosing injectors which are behaving incorrectly or in unexpected ways

Description

Like BeforeInvoke, this injection point searches for invoke instructions within the target instruction list and returns instructions which match the criteria. This specialised version will only match methods which accept a single String argument and return void, the string itself must be a literal string and is matched as part of the query process.

The primary purpose of this query is to match specific invocations of Profiler::startSection and similar methods which accept a literal string.

The string constant to match should be specified using the named argument ldc.

Notes

This query can only be used to match invocations where the argument is passed as a String literal.

See notes in BeforeInvoke regarding the application order of target and ordinal

AfterInvoke

Overview

Short name INVOKE_ASSIGN
Full name org.spongepowered.asm.mixin.injection.points.AfterInvoke
Options
target
the invocation to target, must be a non-void return type and must be fully-qualified if remapped
ordinal
the ordinal index of the matching invocation to select (selects all if omitted)
Arguments
boolean log
produces verbose output in the console as the injector scans a method, useful for diagnosing injectors which are behaving incorrectly or in unexpected ways

Description

Like BeforeInvoke, this injection point searches for invoke instructions within the target instruction list and returns instructions which match the criteria. However the method targetted must return a value. If this condition is met then the injection point returns the instruction immediately following the invocation. If the invocation is immediately followed by a STORE instruction (eg. the result of the invocation is stored in a local variable) then the injection point returns the instruction immediately following the STORE instruction.

Notes

This injection point selects candidate instructions in exactly the same way as BeforeInvoke so the considerations are the same.

BeforeFieldAccess

Overview

Short name FIELD
Full name org.spongepowered.asm.mixin.injection.points.BeforeFieldAccess
Options
target
the field access to target, must be fully-qualified if remapped
opcode
the instruction opcode to search for (must be one of GETSTATIC, PUTSTATIC, GETFIELD or PUTFIELD), matches all field accesses if not specified
ordinal
the ordinal index of the field access to select (or all if omitted)
Arguments
boolean log
produces verbose output in the console as the injector scans a method, useful for diagnosing injectors which are behaving incorrectly or in unexpected ways

Description

This injection point searches for GETFIELD and PUTFIELD instructions (and their static equivalents) within the target instruction list and returns instructions which match the criteria. target should be a parsable MemberInfo which specifies an field name to search for (omitting target will return all access instructions of the corresponding type in the target). The ordinal specifies the index of the instruction to select, if omitted then all matching field access instructions are returned.

Notes

The ordinal value selects within the instructions matched by target, so if there are 4 field access instructions in the target method, but only 2 match the value specified in target, then specifying ordinal=1 selects the second instruction matching target not the second field access in the method. In other words, target is always applied before ordinal.

BeforeNew

Overview

Short name NEW
Full name org.spongepowered.asm.mixin.injection.points.BeforeNew
Options
target
A constructor descriptor to remap, the descriptor must consist only of the class name or the class name and constructor signature
ordinal
the ordinal index of the NEW opcode to select (or all if omitted)
Arguments
String class
alternative to target for backwards compatibility (NEW originally only supported this argument). Identical to target, specify only one or the other

Description

This injection point searches for NEW instructions within the target instruction list and returns instructions which match the criteria. If target is specified then only NEW instructions for the specified type are returned. If the target includes a method signature (which must specify void (V) as the return type) then only NEW instructions followed by an INVOKESPECIAL(<init>) with a matching signature are returned. Note that the NEW instruction is always returned, not the INVOKESPECIAL.

Notes

Note that like other injection points, ordinal applies to the overall result of the other injection point parameters. So if using target to identify a subset of NEW opcodes, ordinal will select with that subset rather than from the entire pool of NEW opcodes in the target. In order words, ordinal is always applied last.

BeforeConstant

Overview

Short name CONSTANT
Full name org.spongepowered.asm.mixin.injection.points.BeforeConstant
Options
ordinal
the ordinal index of the NEW opcode to select (or all if omitted)
Arguments
boolean nullValue
Set this value to true to match null literals in the method body
int intValue
Set this value to an integer literal to match in the method body. Note that it may be necessary to also set the expandZeroConditions argument if you wish to match literal zeroes which form part of a conditional expression.
float floatValue
Set this value to a float literal to match in the method body.
long longValue
Set this value to a long literal to match in the method body.
double doubleValue
Set this value to a double literal to match in the method body.
String stringValue
Set this value to a literal String value to match in the method body.
String class
Set this to a fully-qualified class name to match a Class literal in the method body
boolean log
Set this value to true to emit logging information when applying this injection point query
String expandZeroConditions
Whilst most constants can be located in the compiled method with relative ease, there exists a special case when a zero is used in a conditional expression. For example:
if (x >= 0)
This special case occurs because java includes explicit instructions for this type of comparison, and thus the compiled code might look more like this:
if (x.isGreaterThanOrEqualToZero())
Of course if we know that the constant we are searching for is part of a comparison, then we can explicitly search for the isGreaterThanOrEqualToZero and convert it back to the original form in order to redirect it just like any other constant access.

To enable this behaviour, you may specify one or more values for this argument based on the type of expression you wish to expand. Since the Java compiler is wont to compile certain expressions as the inverse of their source-level counterparts (eg. compiling a do this if greater than structure to a ignore this if less than or equal structure); specifying a particular expression type implicitly includes the inverse expression as well.

It is worth noting that the effect on ordinals may be hard to predict, and thus care should be taken to ensure that the selected injection points match the expected locations.

Specifying this option has the following effects:

  • Matching conditional opcodes in the target method are identified for injection candidacy.
  • An intValue of 0 is implied and does not need to be explicitly defined.
  • However, explicitly specifying an intValue of 0 will cause this selector to also match explicit 0 constants in the method body as well.
To specify values for this key, separate values of Condition with commas or spaces, eg:
"expandZeroConditions=LESS_THAN_ZERO,GREATER_THAN_ZERO"

Description

This injection point searches for literal values (constants) within the target instruction list and returns instructions which match the criteria. Note that all of the discriminator arguments are mutually exclusive and only one discriminator should be specified. Specifying more than one discriminator argument will raise an exception.

Notes

Note that like other injection points, ordinal applies to the overall result of the other injection point parameters. In order words, ordinal is always applied last.

Clone this wiki locally