Package org.spongepowered.asm.mixin.injection

Annotation Type Desc

  • @Target({TYPE,METHOD})
@Retention(RUNTIME)
@Repeatable(Descriptors.class)
public @interface Desc

    A descriptor for matching a target element, for details of usage see DynamicSelectorDesc.

    Unlike Explicit Target Selectors which can match any element of a candidate member, @Desc descriptors always match all elements of a target explicitly. Element defaults are as follows:

    owner()
    Defaults to the current target of the mixin if not specified
    ret()
    Defaults to void
    args()
    Defaults to an empty array matching a target with no arguments, omitting this value does not mean "match any" signature and will explicitly match targets with no arguments. This value is ignored for fields.

    Notes

    • It should be noted that specifying the only required value (value()) will therefore match elements with owner type equal to the current mixin target, taking no arguments and returning void.
    • Note that when matching fields the value of args() is ignored.

    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      java.lang.String value
      The name of the member to match.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.Class<?>[] args
      The argument types of a method to match, ignored for fields.
      java.lang.String id
      The identifier for this descriptor.
      int max
      The maximum number of times this selector can match.
      int min
      The minimum number of times this selector should match.
      Next[] next
      The next elements of this descriptor path, evaluated in order for each recurse point.
      java.lang.Class<?> owner
      The owner of the member to match.
      java.lang.Class<?> ret
      The return type of a method to match, or the declared type of a field.

    • Element Detail

      • value

        java.lang.String value
        The name of the member to match. Must be specified. Matched case-sensitively against targets.

      • id

        java.lang.String id
        The identifier for this descriptor. Can be an implicit coordinate or a user-defined string. IDs are not case-sensitive but must be unique within a mixin or resolution scope. For more details on resolution for descriptors see DynamicSelectorDesc.
        Default:
        ""

      • owner

        java.lang.Class<?> owner
        The owner of the member to match. The "owner" is the class which declares the member or, ocasionally the type of class upon which a virtual call is being made. For example if a class SuperType defines a method doSomething, usually owner will be SuperType. However note that where a method retrieves a reference to a derived type DerivedType which overrides doSomething, it's possible the invocation will be made using that type. To ensure usage of the correct type, inspect the disassembled bytecode for your target.

        When owner is not specified, it defaults to the current target of the mixin.

        Default:
        void.class

      • ret

        java.lang.Class<?> ret
        The return type of a method to match, or the declared type of a field. Defaults to void.
        Default:
        void.class

      • args

        java.lang.Class<?>[] args
        The argument types of a method to match, ignored for fields. Note that failing to specify this value matches a target with no arguments.
        Default:
        {}

      • next

        Next[] next
        The next elements of this descriptor path, evaluated in order for each recurse point.
        Default:
        {}

      • min

        int min
        The minimum number of times this selector should match. By default the selector is allowed to match no targets. When selecting fields or methods setting this value to anything other than 0 or 1 is pointless since the member can either be present or absent. However when matching method calls or field accesses (eg. when using this value inside @At.desc) this allows a minimum number of matches to be specified in order to provide early validation that the selector matched the correct number of candidates. To specify an exact number of matches, set max to the same value as min. Values less than zero are ignored since selectors cannot match a negative number of times.
        Default:
        0

      • max

        int max
        The maximum number of times this selector can match. By default the selector is allowed to match an unlimited number of targets. When selecting fields or methods, setting this value to anything other than 1 is pointless since the member can either be present or absent. However when matching method calls or field accesses (eg. when using this value inside @At.desc) this allows a maximum number of matches to be specified in order to limit the number of times that the selector can match candidates. To specify an exact number of matches, set max to the same value as min. Values less than 1 are treated as Integer.MAX_VALUE (the default) since setting a value of 0 or less has no meaning.
        Default:
        2147483647