Package org.spongepowered.asm.mixin

Annotation Type Shadow

  • @Documented
@Retention(RUNTIME)
@Target({FIELD,METHOD})
public @interface Shadow
    The Shadow annotation can be put on methods and fields that are present in the target class without overwriting them. This allows to reference methods and fields without much fuzz.

    If the member that is annotated with this annotation does not collide with a member of the target class, an exception will be thrown during transformation.

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.String[] aliases
      The spongeian implementation (and therefore the standard Micromixin implementation) does not support aliases on static methods. This behaviour is subject to change in future versions of micromixin-transformer.
      java.lang.String prefix
      The spongeian implementation (and therefore the standard Micromixin implementation) does not support prefixes on static methods. This behaviour is subject to change in future versions of micromixin-transformer.

    • Element Detail

      • prefix

        java.lang.String prefix

        The spongeian implementation (and therefore the standard Micromixin implementation) does not support prefixes on static methods. This behaviour is subject to change in future versions of micromixin-transformer.

        A prefix that can be added to the name of the member. The name of the member is not necessarily required to start with the prefix though. But if the prefix is present, it will be removed allowing the member to match with the proper name.

        The main reason to use prefixes is to avoid issues that can be caused with methods having the same name. The JVMS allows the existence of multiple methods with the same arguments and the same name, as long as the return type differs. However the JLS does not allow the existence of such methods.

        While micromixin-transformer and micromixin-remapper permits it, the spongeian mixin implementation do not allow the usage of prefixes on fields. Doing so will cause the transformer to refuse apply under the spongeian implementation. Under micromixin, a warning is printed out instead, indicating that there are compatibility concerns that arise from such usage of prefixes. According to the spongeian documentation, the core point of prefixes have no application on fields. Why exactly that is the case is a bit beyond me as it is very well possible for fields to have the same name but different descriptors. In any case, use of aliases() may be an appropriate workaround.

        Returns:
        The prefix to use
        Default:
        "shadow$"

      • aliases

        java.lang.String[] aliases

        The spongeian implementation (and therefore the standard Micromixin implementation) does not support aliases on static methods. This behaviour is subject to change in future versions of micromixin-transformer.

        The aliases of the method. Only one alias is selected from the given list, if none match an exception is thrown during transformation. The actual name of the method is discarded and will not play a role once aliases are defined.

        Aliases are not affected by the prefix.

        The spongeian Mixin specification advises against the usage of aliases. According to them aliases should only be used if the name of the target has changed. (The behaviour of aliases does not allow much more usecases anyways)

        Unlike prefixes, aliases are completely acceptable when the @Shadow-Annotation targets a field in both micromixin and standard mixin.

        In the spongeian mixin implementation, aliases are not supported on non-private members (for this, the access modifier of the target member is being used, not the one of the member in the mixin class). The cited reason for this is that other mixins could add fields that would match the alias and thus invalidate caches. It is unclear why this is an issue in the spongeian implementation, but for compatibility reasons it is recommended to ensure that shadowed members with aliases are private. While micromixin-transformer and micromixin-remapper support the usage of aliases on non-private members, it will log a warning at application time when doing so and may in the future refuse to apply such mixins. Proceed with care.

        Returns:
        The aliases to use.
        Default:
        {}