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}