Package com.blamejared.crafttweaker.api.action.base

Interface IAction

All Known Subinterfaces:
IRuntimeAction, IUndoableAction
All Known Implementing Classes:
ActionAddDataReceiver, ActionAddRecipe, ActionAddShiftedTooltip, ActionAddTooltip, ActionAddTrade, ActionAddWanderingTrade, ActionBatchReplacement, ActionClearTooltip, ActionKnownTag, ActionKnownTagAdd, ActionKnownTagClear, ActionKnownTagCreate, ActionKnownTagModify, ActionKnownTagRemove, ActionLootModifier, ActionModifyAttribute, ActionModifyShiftedTooltip, ActionModifyTooltip, ActionRecipeBase, ActionRegisterEvent, ActionRegisterLootModifier, ActionRemoveAll, ActionRemoveAllGenericRecipes, ActionRemoveGenericRecipe, ActionRemoveGenericRecipeBase, ActionRemoveGenericRecipeByModId, ActionRemoveGenericRecipeByName, ActionRemoveGenericRecipeByOutput, ActionRemoveGenericRecipeByRegex, ActionRemoveLootModifier, ActionRemoveRecipe, ActionRemoveRecipeByModid, ActionRemoveRecipeByName, ActionRemoveRecipeByOutput, ActionRemoveRecipeByOutputInput, ActionRemoveRecipeByRegex, ActionRemoveRegexTooltip, ActionRemoveTrade, ActionRemoveWanderingTrade, ActionReplaceRecipe, ActionSetBlockProperty, ActionSetBurnTime, ActionSetCauldronInteraction, ActionSetCompostable, ActionSetItemProperty, ActionTag, ActionTooltipBase, ActionTradeBase, ActionUnknownTag, ActionUnknownTagAdd, ActionUnknownTagClear, ActionUnknownTagCreate, ActionUnknownTagModify, ActionUnknownTagRemove, ActionWholeRegistryBase, CraftTweakerAction
public interface IAction
Represents an action that is to be executed through a ZenCode script.

All methods that are exposed to ZenCode should use classes that implement this interface or one of its sub-interfaces as required by semantics to ensure proper logging and rollback if necessary.

If an action should be executed on every game reload and not only during the first run of a loader, refer to IRuntimeAction instead. If the action requires some additional code to be run to correctly rollback changes, refer to IUndoableAction.

Since:
9.1.0

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    apply()
    Applies the action, executing all code necessary.
    default boolean
    assertLoader(IScriptLoader loader, org.apache.logging.log4j.Logger logger)
    Ensures that an action is only applied on a certain loader.
    String
    describe()
    Gets a human-readable description of the action.
    default CodePosition
    getDeclaredScriptPosition()
    Retrieves the position in the script file where the action was created.
    default org.apache.logging.log4j.Logger
    logger()
    Obtains the Logger instance that can be used to log messages for this action.
    default boolean
    shouldApplyOn(IScriptLoadSource source, org.apache.logging.log4j.Logger logger)
    Determines whether an action should be applied for scripts loading in the given IScriptLoadSource.
    String
    systemName()
    Gets the name of the system that is responsible for the execution of the action.
    default boolean
    validate(org.apache.logging.log4j.Logger logger)
    Validates the action, ensuring no erroneous information is present.

  • Method Details

    • apply

      void apply()
      Applies the action, executing all code necessary.
      Since:
      9.1.0

    • describe

      String describe()
      Gets a human-readable description of the action.

      This message is used for logging and to surface information to the user when something goes wrong. It is thus customary to describe the action as accurately as possible without being too verbose.

      It is not allowed to return a null or otherwise empty description for the action: doing so will raise an error at runtime.

      Returns:
      A description of the current action.
      Since:
      9.1.0

    • systemName

      String systemName()
      Gets the name of the system that is responsible for the execution of the action.

      The system usually corresponds to the name of the mod that created the action and is thus attempting to apply it. For example, adding a recipe is done through CraftTweaker, so the system name is "CraftTweaker". Mods that have various components or would like to separate various integrations from each other can return more complex strings. In other words, if the class that implements this interface belongs to mod Foo, then the system name should be "Foo" (or "Foo-Bar" where Bar is the name of the subsystem) in almost all cases.

      Note that the system name will be used for logging, therefore it is suggested to avoid overly verbose names or acronyms that are not widely known. Returning null or an empty name is disallowed.

      Returns:
      The name of the system that is responsible for this action.
      Since:
      11.0.0

    • validate

      default boolean validate(org.apache.logging.log4j.Logger logger)
      Validates the action, ensuring no erroneous information is present.

      Implementations should validate all action information and log errors using the provided Logger if anything is incorrect. It is highly suggested to specify exactly what is wrong in the most precise yet brief way possible, to ensure script writers know why their actions are not being applied.

      If validation fails for whatever reason, apply() will not be called.

      Parameters:
      logger - Logger object on which to log errors or warnings.
      Returns:
      Whether the action is valid (true) or not (false).
      Since:
      9.1.0

    • shouldApplyOn

      default boolean shouldApplyOn(IScriptLoadSource source, org.apache.logging.log4j.Logger logger)
      Determines whether an action should be applied for scripts loading in the given IScriptLoadSource.
      Parameters:
      source - The IScriptLoadSource responsible for loading the scripts.
      logger - The Logger instance that should be used to log error messages if needed.
      Returns:
      If the action should be applied.
      Since:
      11.0.0

    • getDeclaredScriptPosition

      @Nonnull default CodePosition getDeclaredScriptPosition()
      Retrieves the position in the script file where the action was created.

      The created CodePosition will always be a virtual position, meaning that its contents cannot be accessed.

      Returns:
      The CodePosition where the action was created on, or CodePosition.UNKNOWN if the information cannot be retrieved.
      Since:
      9.1.0

    • assertLoader

      default boolean assertLoader(IScriptLoader loader, org.apache.logging.log4j.Logger logger)
      Ensures that an action is only applied on a certain loader.

      This method is not meant to be overridden, but rather used as an additional check in shouldApplyOn(IScriptLoadSource, Logger) if needed.

      If the check fails, this method will also log a warning stating the script position where the error occurred if possible (see getDeclaredScriptPosition()) and which loader is the one the action is supposed to be ran on.

      Parameters:
      loader - The IScriptLoader the action should be only applied on.
      logger - The Logger instance that should be used to log a warning in case the loader does not match.
      Returns:
      If this loader matches the one specified as a parameter.
      Since:
      11.0.0

    • logger

      default org.apache.logging.log4j.Logger logger()
      Obtains the Logger instance that can be used to log messages for this action.

      This method is not meant to be overridden, but rather used in methods such as apply() if needed. Overriding this method will have no effect as CraftTweaker ignores the return value of it.

      Returns:
      The logger used to log messages for this action.
      Since:
      11.0.0