001 package org.bukkit.entity;
002
003 import org.bukkit.inventory.HorseInventory;
004 import org.bukkit.inventory.InventoryHolder;
005
006 /**
007 * Represents a Horse.
008 */
009 public interface Horse extends Animals, Vehicle, InventoryHolder, Tameable {
010
011 /**
012 * Represents the different types of horses that may exist.
013 */
014 public enum Variant {
015 /**
016 * A normal horse
017 */
018 HORSE,
019 /**
020 * A donkey
021 */
022 DONKEY,
023 /**
024 * A mule
025 */
026 MULE,
027 /**
028 * An undead horse
029 */
030 UNDEAD_HORSE,
031 /**
032 * A skeleton horse
033 */
034 SKELETON_HORSE,
035 ;
036 }
037
038 /**
039 * Represents the base color that the horse has.
040 */
041 public enum Color {
042 /**
043 * Snow white
044 */
045 WHITE,
046 /**
047 * Very light brown
048 */
049 CREAMY,
050 /**
051 * Chestnut
052 */
053 CHESTNUT,
054 /**
055 * Light brown
056 */
057 BROWN,
058 /**
059 * Pitch black
060 */
061 BLACK,
062 /**
063 * Gray
064 */
065 GRAY,
066 /**
067 * Dark brown
068 */
069 DARK_BROWN,
070 ;
071 }
072
073 /**
074 * Represents the style, or markings, that the horse has.
075 */
076 public enum Style {
077 /**
078 * No markings
079 */
080 NONE,
081 /**
082 * White socks or stripes
083 */
084 WHITE,
085 /**
086 * Milky splotches
087 */
088 WHITEFIELD,
089 /**
090 * Round white dots
091 */
092 WHITE_DOTS,
093 /**
094 * Small black dots
095 */
096 BLACK_DOTS,
097 ;
098 }
099
100 /**
101 * Gets the horse's variant.
102 * <p>
103 * A horse's variant defines its physical appearance and capabilities.
104 * Whether a horse is a regular horse, donkey, mule, or other kind of
105 * horse is determined using the variant.
106 *
107 * @return a {@link Variant} representing the horse's variant
108 */
109 public Variant getVariant();
110
111 /**
112 * Sets the horse's variant.
113 * <p>
114 * A horse's variant defines its physical appearance and capabilities.
115 * Whether a horse is a regular horse, donkey, mule, or other kind of
116 * horse can be set using the variant.
117 * <p>
118 * Setting a horse's variant does not change its attributes such as
119 * its owner and its tamed status, but changing a mule or donkey
120 * with a chest to another variant which does not support a chest
121 * will remove the chest and its contents.
122 *
123 * @param variant a {@link Variant} for this horse
124 */
125 public void setVariant(Variant variant);
126
127 /**
128 * Gets the horse's color.
129 * <p>
130 * Colors only apply to horses, not to donkeys, mules, skeleton horses
131 * or undead horses.
132 *
133 * @return a {@link Color} representing the horse's group
134 */
135 public Color getColor();
136
137 /**
138 * Sets the horse's color.
139 * <p>
140 * Attempting to set a color for any donkey, mule, skeleton horse or
141 * undead horse will not result in a change.
142 *
143 * @param color a {@link Color} for this horse
144 */
145 public void setColor(Color color);
146
147 /**
148 * Gets the horse's style.
149 * Styles determine what kind of markings or patterns a horse has.
150 * <p>
151 * Styles only apply to horses, not to donkeys, mules, skeleton horses
152 * or undead horses.
153 *
154 * @return a {@link Style} representing the horse's style
155 */
156 public Style getStyle();
157
158 /**
159 * Sets the style of this horse.
160 * Styles determine what kind of markings or patterns a horse has.
161 * <p>
162 * Attempting to set a style for any donkey, mule, skeleton horse or
163 * undead horse will not result in a change.
164 *
165 * @param style a {@link Style} for this horse
166 */
167 public void setStyle(Style style);
168
169 /**
170 * Gets whether the horse has a chest equipped.
171 *
172 * @return true if the horse has chest storage
173 */
174 public boolean isCarryingChest();
175
176 /**
177 * Sets whether the horse has a chest equipped.
178 * Removing a chest will also clear the chest's inventory.
179 *
180 * @param chest true if the horse should have a chest
181 */
182 public void setCarryingChest(boolean chest);
183
184 /**
185 * Gets the domestication level of this horse.
186 * <p>
187 * A higher domestication level indicates that the horse is closer to
188 * becoming tame. As the domestication level gets closer to the max
189 * domestication level, the chance of the horse becoming tame increases.
190 *
191 * @return domestication level
192 */
193 public int getDomestication();
194
195 /**
196 * Sets the domestication level of this horse.
197 * <p>
198 * Setting the domestication level to a high value will increase the
199 * horse's chances of becoming tame.
200 * <p>
201 * Domestication level must be greater than zero and no greater than
202 * the max domestication level of the horse, determined with
203 * {@link #getMaxDomestication()}
204 *
205 * @param level domestication level
206 */
207 public void setDomestication(int level);
208
209 /**
210 * Gets the maximum domestication level of this horse.
211 * <p>
212 * The higher this level is, the longer it will likely take
213 * for the horse to be tamed.
214 *
215 * @return the max domestication level
216 */
217 public int getMaxDomestication();
218
219 /**
220 * Sets the maximum domestication level of this horse.
221 * <p>
222 * Setting a higher max domestication will increase the amount of
223 * domesticating (feeding, riding, etc.) necessary in order to tame it,
224 * while setting a lower max value will have the opposite effect.
225 * <p>
226 * Maximum domestication must be greater than zero.
227 *
228 * @param level the max domestication level
229 */
230 public void setMaxDomestication(int level);
231
232 /**
233 * Gets the jump strength of this horse.
234 * <p>
235 * Jump strength defines how high the horse can jump. A higher jump strength
236 * increases how high a jump will go.
237 *
238 * @return the horse's jump strength
239 */
240 public double getJumpStrength();
241
242 /**
243 * Sets the jump strength of this horse.
244 * <p>
245 * A higher jump strength increases how high a jump will go.
246 * Setting a jump strength to 0 will result in no jump.
247 * You cannot set a jump strength to a value below 0 or
248 * above 2.
249 *
250 * @param strength jump strength for this horse
251 */
252 public void setJumpStrength(double strength);
253
254 @Override
255 public HorseInventory getInventory();
256 }