Package org.spongepowered.asm.mixin.injection

## Annotation Type ModifyConstant

    @Target(METHOD)
    @Retention(RUNTIME)
    public @interface ModifyConstant

Specifies that this mixin method should inject a constant modifier callback to itself in the target method(s) identified by `method()` at the specified LDC (or specialised const opcode) instruction in order to adjust the constant value returned.

`ModifyConstant` callbacks should always take one argument of the appropriate constant type and return the same type. For example a `ModifyConstant` for a local of type `String` should have the signature:

`private String methodName(String variable) { ...`

The callback receives the original value of the constant, and should return the new value.

Like other Redirect injectors, the callback signature can optionally include the target method arguments by simply appending them to the handler method signature.

### Optional Element Summary

Optional Elements
`int` `allow` Injection points are in general expected to match every candidate instruction in the target method or slice, except in cases where options such as `At.ordinal()` are specified which naturally limit the number of results.
`Constant[]` `constant` Discriminator for the constant(s) to match (injection points), if not specified then all constants matching the annotated handler's return type are matched
`java.lang.String` `constraints` Returns constraints which must be validated for this injector to succeed.
`int` `expect` Like `require()` but only enabled if the `mixin.debug.countInjections` option is set to `true` and defaults to 1.
`java.lang.String[]` `method` String representation of one or more `target selectors` which identify the target methods.
`int` `order` By default almost all injectors for a target class apply their injections at the same time.
`boolean` `remap` By default, the annotation processor will attempt to locate an obfuscation mapping for all `ModifyConstant` methods since it is anticipated that in general the target of a `ModifyConstant` annotation will be an obfuscated method in the target class.
`int` `require` In general, injectors are intended to "fail soft" in that a failure to locate the injection point in the target method is not considered an error condition.
`Slice[]` `slice` Array of `Slice` annotations which describe the method bisections used in locating target instructions for this modifier.
`Desc[]` `target` Literal representation of one or more `@Desc` annotations which identify the target methods.

### Element Detail

#### method

    java.lang.String[] method

String representation of one or more `target selectors` which identify the target methods.

Returns:
  target method(s) for this injector

Default:
  {}

#### target

    Desc[] target

Literal representation of one or more `@Desc` annotations which identify the target methods.

Returns:
  target method(s) for this injector as descriptors

Default:
  {}

#### slice

    Slice[] slice

Array of `Slice` annotations which describe the method bisections used in locating target instructions for this modifier.

Returns:
  slices

Default:
  {}

#### constant

    Constant[] constant

Discriminator for the constant(s) to match (injection points), if not specified then all constants matching the annotated handler's return type are matched

Returns:
  the constant discriminator

Default:
  {}

#### remap

    boolean remap

By default, the annotation processor will attempt to locate an obfuscation mapping for all `ModifyConstant` methods since it is anticipated that in general the target of a `ModifyConstant` annotation will be an obfuscated method in the target class. However since it is possible to also apply mixins to non-obfuscated targets (or non- obfuscated methods in obfuscated targets, such as methods added by Forge) 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

#### require

    int require

In general, injectors are intended to "fail soft" in that a failure to locate the injection point in the target method is not considered an error condition. Another transformer may have changed the method structure or any number of reasons may cause an injection to fail. This also makes it possible to define several injections to achieve the same task given expected mutation of the target class and the injectors which fail are simply ignored.

However, this behaviour is not always desirable. For example, if your application depends on a particular injection succeeding you may wish to detect the injection failure as an error condition. This argument is thus provided to allow you to stipulate a minimum number of successful injections for this callback handler. If the number of injections specified is not achieved then an `InjectionError` is thrown at application time. Use this option with care.

Returns:
  Minimum required number of injected callbacks, default specified by the containing config

Default:
  -1

#### expect

    int expect

Like `require()` but only enabled if the `mixin.debug.countInjections` option is set to `true` and defaults to 1. Use this option during debugging to perform simple checking of your injectors. Causes the injector to throw a `InvalidInjectionException` if the expected number of injections is not realised.

Returns:
  Minimum number of expected callbacks, default 1

Default:
  1

#### allow

    int allow

Injection points are in general expected to match every candidate instruction in the target method or slice, except in cases where options such as `At.ordinal()` are specified which naturally limit the number of results.

This option allows for sanity-checking to be performed on the results of an injection point by specifying a maximum allowed number of matches, similar to that afforded by `Group.max()`. For example if your injection is expected to match 4 invocations of a target method, but instead matches 5, this can become a detectable tamper condition by setting this value to `4`.

Setting any value 1 or greater is allowed. Values less than 1 or less than `require()` are ignored. `require()` supercedes this argument such that if `allow` is less than `require` the value of `require` is always used.

Note that this option is not a limit on the query behaviour of this injection point. It is only a sanity check used to ensure that the number of matches is not too high

Returns:
  Maximum allowed number of injections for this

Default:
  -1

#### constraints

    java.lang.String constraints

Returns constraints which must be validated for this injector to succeed. See `ConstraintParser.Constraint` for details of constraint formats.

Returns:
  Constraints for this annotation

Default:
  ""

#### order

    int order

By default almost all injectors for a target class apply their injections at the same time. In other words, if multiple mixins target the same class then injectors are applied in priority order (since the mixins themselves are merged in priority order, and injectors run in the order they were merged). Redirect injectors apply in a later pass.

The default order for redirect injectors is `10000`, and all other injectors use `1000`.

Specifying a value for `order` alters this default behaviour and causes the injector to inject either earlier or later than it normally would. For example specifying `9900` will cause the injector to apply before others, while `11000` will apply later. Injectors with the same `order` will still apply in order of their mixin's `priority`.

Returns:
  the application order for this injector, uses default REDIRECT order (10000) if not specified

Default:
  10000