Package org.spongepowered.asm.mixin.injection

Annotation Interface 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
    String
    value
    The name of the member to match.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Class<?>[]
    args
    The argument types of a method to match, ignored for fields.
    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.
    Class<?>
    owner
    The owner of the member to match.
    Class<?>
    ret
    The return type of a method to match, or the declared type of a field.

  • Element Details

    • id

      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

      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

    • value

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

    • ret

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

    • args

      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