Injection Point Reference

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.