    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     */
    014    package cpw.mods.fml.common;
    015
    016    import java.lang.annotation.ElementType;
    017    import java.lang.annotation.Retention;
    018    import java.lang.annotation.RetentionPolicy;
    019    import java.lang.annotation.Target;
    020
    021    import net.minecraft.item.ItemBlock;
    022
    023    import cpw.mods.fml.common.event.FMLInterModComms;
    024    import 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)
    034    public @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-starting" phase
    149         * @author cpw
    150         *
    151         */
    152        @Retention(RetentionPolicy.RUNTIME)
    153        @Target(ElementType.METHOD)
    154        public @interface ServerStarting {}
    155        /**
    156         * Mark the designated method as being called at the "server-started" phase
    157         * @author cpw
    158         *
    159         */
    160        @Retention(RetentionPolicy.RUNTIME)
    161        @Target(ElementType.METHOD)
    162        public @interface ServerStarted {}
    163        /**
    164         * Mark the designated method as being called at the "server-stopping" phase
    165         * @author cpw
    166         *
    167         */
    168        @Retention(RetentionPolicy.RUNTIME)
    169        @Target(ElementType.METHOD)
    170        public @interface ServerStopping {}
    171        /**
    172         * Mark the designated method as the receiver for {@link FMLInterModComms} messages
    173         * Called between {@link Init} and {@link PostInit}
    174         * @author cpw
    175         *
    176         */
    177        @Retention(RetentionPolicy.RUNTIME)
    178        @Target(ElementType.METHOD)
    179        public @interface IMCCallback {}
    180        /**
    181         * Populate the annotated field with the mod instance.
    182         * @author cpw
    183         *
    184         */
    185        @Retention(RetentionPolicy.RUNTIME)
    186        @Target(ElementType.FIELD)
    187        public @interface Instance {
    188            /**
    189             * The mod object to inject into this field
    190             */
    191            String value() default "";
    192        }
    193        /**
    194         * Populate the annotated field with the mod's metadata.
    195         * @author cpw
    196         *
    197         */
    198        @Retention(RetentionPolicy.RUNTIME)
    199        @Target(ElementType.FIELD)
    200        public @interface Metadata {
    201            /**
    202             * The mod id specifying the metadata to load here
    203             */
    204            String value() default "";
    205        }
    206        /**
    207         * Populate the annotated field with an instance of the Block as specified
    208         * @author cpw
    209         *
    210         */
    211        @Retention(RetentionPolicy.RUNTIME)
    212        @Target(ElementType.FIELD)
    213        public @interface Block {
    214            /**
    215             * The block's name
    216             */
    217            String name();
    218            /**
    219             * The associated ItemBlock subtype for the item (can be null for an ItemBlock)
    220             */
    221            Class<?> itemTypeClass() default ItemBlock.class;
    222        }
    223        /**
    224         * Populate the annotated field with an Item
    225         * @author cpw
    226         *
    227         */
    228        @Retention(RetentionPolicy.RUNTIME)
    229        @Target(ElementType.FIELD)
    230        public @interface Item {
    231            /**
    232             * The name of the item
    233             */
    234            String name();
    235            /**
    236             * The type of the item
    237             */
    238            String typeClass();
    239        }
    240    }