org.spongepowered.asm.mixin.injection

Annotation Type At

@Retention(value=RUNTIME)
public @interface At

Annotation for specifying the type of InjectionPoint to use to perform an Inject process. This annotation allows the InjectionPoint class to be specified, as well as arguments to be passed to the InjectionPoint instance to configure it. The data contained in the annotation are wrapped into a InjectionInfo object before being passed to the InjectionPoint for parsing. All values are optional apart from value(), which specifies the type of InjectionPoint to use. All other parameters depend on the InjectionPoint chosen, and the javadoc for each InjectionPoint class should be consulted for the meaning of the argument to that particular class. A general description of each parameter is provided below.

Required Element Summary

Required Elements

Modifier and Type	Required Element and Description
java.lang.String	value Type of InjectionPoint to use.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
java.lang.String[]	args The named arguments list is used to expand the scope of the annotation beyond the fixed values below in order to accommodate the needs of custom injection point classes.
int	by If shift() is specified as BY, specifies the number of opcodes to shift by (negative numbers are allowed).
java.lang.String	id The identifier for this injection point, can be retrieved via the CallbackInfo.getId() accessor.
int	opcode Target opcode for FIELD and JUMP InjectionPoints.
int	ordinal Ordinal offset.
boolean	remap By default, the annotation processor will attempt to locate an obfuscation mapping for the target() member and any other args() known to contain potentially obfuscated references, since it is anticipated that in general the target of an At annotation will be an obfuscated method or field.
At.Shift	shift Shift type for returned opcodes.
java.lang.String	slice For Inject queries, this specifies the ID of the slice to use for this query.
java.lang.String	target Target identifier used by INVOKE, INVOKE_STRING, INVOKE_ASSIGN, FIELD and NEW.

Element Detail

value

public abstract java.lang.String value

Type of InjectionPoint to use. Can be a built-in class or the fully-qualified name of a custom class which extends InjectionPoint.

Built-in types are HEAD, RETURN, TAIL, INVOKE, INVOKE_ASSIGN, FIELD, NEW, INVOKE_STRING, JUMP and CONSTANT. See the javadoc for each type for more details on the scheme used by each injection point.

Returns:

Injection point specifier or fully-qualified class name

id

public abstract java.lang.String id

The identifier for this injection point, can be retrieved via the CallbackInfo.getId() accessor. If specified, the ID is appended to the value specified in the outer annotion. Eg. specifying "foo" for this attribute and "bar" for the Inject.Inject.id() attribute will result in a combined id of "bar:foo". Note that if no id is specified for the outer injector, the name of the calling method is used.

Returns:

the injection point id to use

Default:

""

slice

public abstract java.lang.String slice

For Inject queries, this specifies the ID of the slice to use for this query. For other injector types it is ignored because only one slice is supported.

For more details see the Slice.id()

Returns:

the slice identifier, or empty string to use the default slice

Default:

""

shift

public abstract At.Shift shift

Shift type for returned opcodes. For example use AFTER with an INVOKE InjectionPoint to move the returned opcodes to after the invoation. Use BY in conjunction with the by() parameter to shift by an arbitrary number of opcodes.

Returns:

Type of shift to apply

Default:

org.spongepowered.asm.mixin.injection.At.Shift.NONE

by

public abstract int by

If shift() is specified as BY, specifies the number of opcodes to shift by (negative numbers are allowed). Note that values above 3 should be avoided and in general either replaced with a custom injection point or with sliced injection points. The warning/error threshold is defined by the config (with a hard limit on value of InjectionPoint.MAX_ALLOWED_SHIFT_BY)

Returns:

Amount of shift to apply for the BY shift

Default:

0

args

public abstract java.lang.String[] args

The named arguments list is used to expand the scope of the annotation beyond the fixed values below in order to accommodate the needs of custom injection point classes.

Returns:

Named arguments for the injection point

Default:

{}

target

public abstract java.lang.String target

Target identifier used by INVOKE, INVOKE_STRING, INVOKE_ASSIGN, FIELD and NEW. This must be specified as a fully-qualified member path including the class name and signature. Failing to fully-qualify the target member will result in an error at obfuscation time.

Returns:

target reference for supported InjectionPoint types

Default:

""

ordinal

public abstract int ordinal

Ordinal offset. Many InjectionPoints will return every opcode matching their criteria, specifying ordinal allows a particular opcode to be identified from the returned list. The default value of -1 does not alter the behaviour and returns all matching opcodes. Specifying a value of 0 or higher returns only the requested opcode (if one exists: for example specifying an ordinal of 4 when only 2 opcodes are matched by the InjectionPoint is not going to work particularly well!)

Returns:

ordinal value for supported InjectionPoint types

Default:

-1

opcode

public abstract int opcode

Target opcode for FIELD and JUMP InjectionPoints. See the javadoc for the relevant injection point for more details.

Returns:

Bytecode opcode for supported InjectionPoints

Default:

-1

remap

public abstract boolean remap

By default, the annotation processor will attempt to locate an obfuscation mapping for the target() member and any other args() known to contain potentially obfuscated references, since it is anticipated that in general the target of an At annotation will be an obfuscated method or field. However since it is also possible that the target is a non-obfuscated reference it may be necessary to suppress the compiler error which would otherwise be generated. Setting this value to false will cause the annotation processor to skip this annotation when attempting to build the obfuscation table for the mixin.

Returns:

True to instruct the annotation processor to search for obfuscation mappings for this annotation

Default:

true