    001/*
    002 * The FML Forge Mod Loader suite.
    003 * Copyright (C) 2012 cpw
    004 *
    005 * This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free
    006 * Software Foundation; either version 2.1 of the License, or any later version.
    007 *
    008 * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
    009 * A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
    010 *
    011 * You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51
    012 * Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
    013 */
    014package cpw.mods.fml.common;
    015
    016import java.lang.annotation.ElementType;
    017import java.lang.annotation.Retention;
    018import java.lang.annotation.RetentionPolicy;
    019import java.lang.annotation.Target;
    020
    021import net.minecraft.item.ItemBlock;
    022
    023import cpw.mods.fml.common.event.FMLInterModComms;
    024import cpw.mods.fml.common.event.FMLInterModComms.IMCMessage;
    025
    026/**
    027 * The new mod style in FML 1.3
    028 *
    029 * @author cpw
    030 *
    031 */
    032@Retention(RetentionPolicy.RUNTIME)
    033@Target(ElementType.TYPE)
    034public @interface Mod
    035{
    036    /**
    037     * The unique mod identifier for this mod
    038     */
    039    String modid();
    040    /**
    041     * A user friendly name for the mod
    042     */
    043    String name() default "";
    044    /**
    045     * A version string for this mod
    046     */
    047    String version() default "";
    048    /**
    049     * A simple dependency string for this mod (see modloader's "priorities" string specification)
    050     */
    051    String dependencies() default "";
    052    /**
    053     * Whether to use the mcmod.info metadata by default for this mod.
    054     * If true, settings in the mcmod.info file will override settings in these annotations.
    055     */
    056    boolean useMetadata() default false;
    057
    058    /**
    059     * The acceptable range of minecraft versions that this mod will load and run in
    060     * The default ("empty string") indicates that only the current minecraft version is acceptable.
    061     * FML will refuse to run with an error if the minecraft version is not in this range across all mods.
    062     * @return A version range as specified by the maven version range specification or the empty string
    063     */
    064    String acceptedMinecraftVersions() default "";
    065    /**
    066     * An optional bukkit plugin that will be injected into the bukkit plugin framework if
    067     * this mod is loaded into the FML framework and the bukkit coremod is present.
    068     * Instances of the bukkit plugin can be obtained via the {@link BukkitPluginRef} annotation on fields.
    069     * @return The name of the plugin to load for this mod
    070     */
    071    String bukkitPlugin() default "";
    072    /**
    073     * Mods that this mod will <strong>not</strong> load with.
    074     * An optional comma separated string of (+|-)(*|modid[@value]) which specify mods that
    075     * this mod will refuse to load with, resulting in the game failing to start.
    076     * Entries can be prefixed with a + for a positive exclusion assertion, or - for a negative exclusion
    077     * assertion. Asterisk is the wildcard and represents <strong>all</strong> mods.
    078     *
    079     * The <strong>only</strong> mods that cannot be excluded are FML and MCP, trivially.
    080     * Other special values:
    081     * <ul>
    082     * <li>+f indicates that the mod will accept a minecraft forge environment.</li>
    083     * <li>-* indicates that the mod will not accept any other mods.</li>
    084     * </ul>
    085     *
    086     * Some examples:
    087     * <ul>
    088     * <li><em>-*,+f,+IronChest</em>: Will run only in a minecraft forge environment with the mod IronChests.
    089     * The -* forces all mods to be excluded, then the +f and +IronChest add into the "allowed list".</li>
    090     * <li><em>+f,-IC2</em>: Will run in a minecraft forge environment but will <strong>not</strong> run if
    091     * IndustrialCraft 2 (IC2) is loaded alongside.</li>
    092     * <li><em>-*</em>: Will not run if <strong>any</strong> othe mod is loaded except MCP/FML itself.</li>
    093     * </ul>
    094     *
    095     * If a mod is present on the excluded list, the game will stop and show an error screen. If the
    096     * class containing the {@link Mod} annotation has a "getCustomErrorException" method, it will be
    097     * called to retrieve a custom error message for display in this case. If two mods have a declared
    098     * exclusion which is matched, the screen that is shown is indeterminate.
    099     *
    100     * @return A string listing modids to exclude from loading with this mod.
    101     */
    102    String modExclusionList() default "";
    103    /**
    104     * Specifying this field allows for a mod to expect a signed jar with a fingerprint matching this value.
    105     * The fingerprint should be SHA-1 encoded, lowercase with ':' removed. An empty value indicates that
    106     * the mod is not expecting to be signed.
    107     *
    108     * Any incorrectness of the fingerprint, be it missing or wrong, will result in the {@link FingerprintWarning}
    109     * method firing <i>prior to any other event on the mod</i>.
    110     *
    111     * @return A certificate fingerprint that is expected for this mod.
    112     */
    113    String certificateFingerprint() default "";
    114    /**
    115     * Mark the designated method as to be called at if there is something wrong with the certificate fingerprint of
    116     * the mod's jar, or it is missing, or otherwise a problem.
    117     * @author cpw
    118     *
    119     */
    120    @Retention(RetentionPolicy.RUNTIME)
    121    @Target(ElementType.METHOD)
    122    public @interface FingerprintWarning {}
    123    /**
    124     * Mark the designated method as being called at the "pre-initialization" phase
    125     * @author cpw
    126     *
    127     */
    128    @Retention(RetentionPolicy.RUNTIME)
    129    @Target(ElementType.METHOD)
    130    public @interface PreInit {}
    131    /**
    132     * Mark the designated method as being called at the "initialization" phase
    133     * @author cpw
    134     *
    135     */
    136    @Retention(RetentionPolicy.RUNTIME)
    137    @Target(ElementType.METHOD)
    138    public @interface Init {}
    139    /**
    140     * Mark the designated method as being called at the "post-initialization" phase
    141     * @author cpw
    142     *
    143     */
    144    @Retention(RetentionPolicy.RUNTIME)
    145    @Target(ElementType.METHOD)
    146    public @interface PostInit {}
    147    /**
    148     * Mark the designated method as being called at the "server-about-to-start" phase
    149     * @author cpw
    150     *
    151     */
    152    @Retention(RetentionPolicy.RUNTIME)
    153    @Target(ElementType.METHOD)
    154    public @interface ServerAboutToStart {}
    155    /**
    156     * Mark the designated method as being called at the "server-starting" phase
    157     * @author cpw
    158     *
    159     */
    160    @Retention(RetentionPolicy.RUNTIME)
    161    @Target(ElementType.METHOD)
    162    public @interface ServerStarting {}
    163    /**
    164     * Mark the designated method as being called at the "server-started" phase
    165     * @author cpw
    166     *
    167     */
    168    @Retention(RetentionPolicy.RUNTIME)
    169    @Target(ElementType.METHOD)
    170    public @interface ServerStarted {}
    171    /**
    172     * Mark the designated method as being called at the "server-stopping" phase
    173     * @author cpw
    174     *
    175     */
    176    @Retention(RetentionPolicy.RUNTIME)
    177    @Target(ElementType.METHOD)
    178    public @interface ServerStopping {}
    179    /**
    180     * Mark the designated method as being called at the "server-stopped" phase
    181     * @author cpw
    182     *
    183     */
    184    @Retention(RetentionPolicy.RUNTIME)
    185    @Target(ElementType.METHOD)
    186    public @interface ServerStopped {}
    187    /**
    188     * Mark the designated method as the receiver for {@link FMLInterModComms} messages
    189     * Called between {@link Init} and {@link PostInit}
    190     * @author cpw
    191     *
    192     */
    193    @Retention(RetentionPolicy.RUNTIME)
    194    @Target(ElementType.METHOD)
    195    public @interface IMCCallback {}
    196    /**
    197     * Populate the annotated field with the mod instance.
    198     * @author cpw
    199     *
    200     */
    201    @Retention(RetentionPolicy.RUNTIME)
    202    @Target(ElementType.FIELD)
    203    public @interface Instance {
    204        /**
    205         * The mod object to inject into this field
    206         */
    207        String value() default "";
    208    }
    209    /**
    210     * Populate the annotated field with the mod's metadata.
    211     * @author cpw
    212     *
    213     */
    214    @Retention(RetentionPolicy.RUNTIME)
    215    @Target(ElementType.FIELD)
    216    public @interface Metadata {
    217        /**
    218         * The mod id specifying the metadata to load here
    219         */
    220        String value() default "";
    221    }
    222    /**
    223     * Populate the annotated field with an instance of the Block as specified
    224     * @author cpw
    225     *
    226     */
    227    @Retention(RetentionPolicy.RUNTIME)
    228    @Target(ElementType.FIELD)
    229    public @interface Block {
    230        /**
    231         * The block's name
    232         */
    233        String name();
    234        /**
    235         * The associated ItemBlock subtype for the item (can be null for an ItemBlock)
    236         */
    237        Class<?> itemTypeClass() default ItemBlock.class;
    238    }
    239    /**
    240     * Populate the annotated field with an Item
    241     * @author cpw
    242     *
    243     */
    244    @Retention(RetentionPolicy.RUNTIME)
    245    @Target(ElementType.FIELD)
    246    public @interface Item {
    247        /**
    248         * The name of the item
    249         */
    250        String name();
    251        /**
    252         * The type of the item
    253         */
    254        String typeClass();
    255    }
    256}