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 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 }