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 cpw.mods.fml.common.event.FMLInterModComms;
022    import cpw.mods.fml.common.event.FMLInterModComms.IMCMessage;
023    
024    import net.minecraft.src.ItemBlock;
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         * Mark the designated method as being called at the "pre-initialization" phase
105         * @author cpw
106         *
107         */
108        @Retention(RetentionPolicy.RUNTIME)
109        @Target(ElementType.METHOD)
110        public @interface PreInit {}
111        /**
112         * Mark the designated method as being called at the "initialization" phase
113         * @author cpw
114         *
115         */
116        @Retention(RetentionPolicy.RUNTIME)
117        @Target(ElementType.METHOD)
118        public @interface Init {}
119        /**
120         * Mark the designated method as being called at the "post-initialization" phase
121         * @author cpw
122         *
123         */
124        @Retention(RetentionPolicy.RUNTIME)
125        @Target(ElementType.METHOD)
126        public @interface PostInit {}
127        /**
128         * Mark the designated method as being called at the "server-starting" phase
129         * @author cpw
130         *
131         */
132        @Retention(RetentionPolicy.RUNTIME)
133        @Target(ElementType.METHOD)
134        public @interface ServerStarting {}
135        /**
136         * Mark the designated method as being called at the "server-started" phase
137         * @author cpw
138         *
139         */
140        @Retention(RetentionPolicy.RUNTIME)
141        @Target(ElementType.METHOD)
142        public @interface ServerStarted {}
143        /**
144         * Mark the designated method as being called at the "server-stopping" phase
145         * @author cpw
146         *
147         */
148        @Retention(RetentionPolicy.RUNTIME)
149        @Target(ElementType.METHOD)
150        public @interface ServerStopping {}
151        /**
152         * Mark the designated method as the receiver for {@link FMLInterModComms} messages
153         * Called between {@link Init} and {@link PostInit}
154         * @author cpw
155         *
156         */
157        @Retention(RetentionPolicy.RUNTIME)
158        @Target(ElementType.METHOD)
159        public @interface IMCCallback {}
160        /**
161         * Populate the annotated field with the mod instance.
162         * @author cpw
163         *
164         */
165        @Retention(RetentionPolicy.RUNTIME)
166        @Target(ElementType.FIELD)
167        public @interface Instance {
168            /**
169             * The mod object to inject into this field
170             */
171            String value() default "";
172        }
173        /**
174         * Populate the annotated field with the mod's metadata.
175         * @author cpw
176         *
177         */
178        @Retention(RetentionPolicy.RUNTIME)
179        @Target(ElementType.FIELD)
180        public @interface Metadata {
181            /**
182             * The mod id specifying the metadata to load here
183             */
184            String value() default "";
185        }
186        /**
187         * Populate the annotated field with an instance of the Block as specified
188         * @author cpw
189         *
190         */
191        @Retention(RetentionPolicy.RUNTIME)
192        @Target(ElementType.FIELD)
193        public @interface Block {
194            /**
195             * The block's name
196             */
197            String name();
198            /**
199             * The associated ItemBlock subtype for the item (can be null for an ItemBlock)
200             */
201            Class<?> itemTypeClass() default ItemBlock.class;
202        }
203        /**
204         * Populate the annotated field with an Item
205         * @author cpw
206         *
207         */
208        @Retention(RetentionPolicy.RUNTIME)
209        @Target(ElementType.FIELD)
210        public @interface Item {
211            /**
212             * The name of the item
213             */
214            String name();
215            /**
216             * The type of the item
217             */
218            String typeClass();
219        }
220    }