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