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-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 being called at the "server-stopped" phase
173     * @author cpw
174     *
175     */
176    @Retention(RetentionPolicy.RUNTIME)
177    @Target(ElementType.METHOD)
178    public @interface ServerStopped {}
179    /**
180     * Mark the designated method as the receiver for {@link FMLInterModComms} messages
181     * Called between {@link Init} and {@link PostInit}
182     * @author cpw
183     *
184     */
185    @Retention(RetentionPolicy.RUNTIME)
186    @Target(ElementType.METHOD)
187    public @interface IMCCallback {}
188    /**
189     * Populate the annotated field with the mod instance.
190     * @author cpw
191     *
192     */
193    @Retention(RetentionPolicy.RUNTIME)
194    @Target(ElementType.FIELD)
195    public @interface Instance {
196        /**
197         * The mod object to inject into this field
198         */
199        String value() default "";
200    }
201    /**
202     * Populate the annotated field with the mod's metadata.
203     * @author cpw
204     *
205     */
206    @Retention(RetentionPolicy.RUNTIME)
207    @Target(ElementType.FIELD)
208    public @interface Metadata {
209        /**
210         * The mod id specifying the metadata to load here
211         */
212        String value() default "";
213    }
214    /**
215     * Populate the annotated field with an instance of the Block as specified
216     * @author cpw
217     *
218     */
219    @Retention(RetentionPolicy.RUNTIME)
220    @Target(ElementType.FIELD)
221    public @interface Block {
222        /**
223         * The block's name
224         */
225        String name();
226        /**
227         * The associated ItemBlock subtype for the item (can be null for an ItemBlock)
228         */
229        Class<?> itemTypeClass() default ItemBlock.class;
230    }
231    /**
232     * Populate the annotated field with an Item
233     * @author cpw
234     *
235     */
236    @Retention(RetentionPolicy.RUNTIME)
237    @Target(ElementType.FIELD)
238    public @interface Item {
239        /**
240         * The name of the item
241         */
242        String name();
243        /**
244         * The type of the item
245         */
246        String typeClass();
247    }
248}