001 package org.bukkit.entity;
002
003 import java.net.InetSocketAddress;
004
005 import org.bukkit.Achievement;
006 import org.bukkit.ChatColor;
007 import org.bukkit.Effect;
008 import org.bukkit.Instrument;
009 import org.bukkit.Location;
010 import org.bukkit.Material;
011 import org.bukkit.Note;
012 import org.bukkit.OfflinePlayer;
013 import org.bukkit.Sound;
014 import org.bukkit.Statistic;
015 import org.bukkit.WeatherType;
016 import org.bukkit.command.CommandSender;
017 import org.bukkit.conversations.Conversable;
018 import org.bukkit.map.MapView;
019 import org.bukkit.plugin.messaging.PluginMessageRecipient;
020 import org.bukkit.scoreboard.Scoreboard;
021
022 /**
023 * Represents a player, connected or not
024 */
025 public interface Player extends HumanEntity, Conversable, CommandSender, OfflinePlayer, PluginMessageRecipient {
026
027 /**
028 * Gets the "friendly" name to display of this player. This may include
029 * color.
030 * <p>
031 * Note that this name will not be displayed in game, only in chat and
032 * places defined by plugins.
033 *
034 * @return the friendly name
035 */
036 public String getDisplayName();
037
038 /**
039 * Sets the "friendly" name to display of this player. This may include
040 * color.
041 * <p>
042 * Note that this name will not be displayed in game, only in chat and
043 * places defined by plugins.
044 *
045 * @param name The new display name.
046 */
047 public void setDisplayName(String name);
048
049 /**
050 * Gets the name that is shown on the player list.
051 *
052 * @return the player list name
053 */
054 public String getPlayerListName();
055
056 /**
057 * Sets the name that is shown on the in-game player list.
058 * <p>
059 * The name cannot be longer than 16 characters, but {@link ChatColor} is
060 * supported.
061 * <p>
062 * If the value is null, the name will be identical to {@link #getName()}.
063 * <p>
064 * This name is case sensitive and unique, two names with different casing
065 * will appear as two different people. If a player joins afterwards with
066 * a name that conflicts with a player's custom list name, the joining
067 * player's player list name will have a random number appended to it (1-2
068 * characters long in the default implementation). If the joining player's
069 * name is 15 or 16 characters long, part of the name will be truncated at
070 * the end to allow the addition of the two digits.
071 *
072 * @param name new player list name
073 * @throws IllegalArgumentException if the name is already used by someone
074 * else
075 * @throws IllegalArgumentException if the length of the name is too long
076 */
077 public void setPlayerListName(String name);
078
079 /**
080 * Set the target of the player's compass.
081 *
082 * @param loc Location to point to
083 */
084 public void setCompassTarget(Location loc);
085
086 /**
087 * Get the previously set compass target.
088 *
089 * @return location of the target
090 */
091 public Location getCompassTarget();
092
093 /**
094 * Gets the socket address of this player
095 *
096 * @return the player's address
097 */
098 public InetSocketAddress getAddress();
099
100 /**
101 * Sends this sender a message raw
102 *
103 * @param message Message to be displayed
104 */
105 public void sendRawMessage(String message);
106
107 /**
108 * Kicks player with custom kick message.
109 *
110 * @param message kick message
111 */
112 public void kickPlayer(String message);
113
114 /**
115 * Says a message (or runs a command).
116 *
117 * @param msg message to print
118 */
119 public void chat(String msg);
120
121 /**
122 * Makes the player perform the given command
123 *
124 * @param command Command to perform
125 * @return true if the command was successful, otherwise false
126 */
127 public boolean performCommand(String command);
128
129 /**
130 * Returns if the player is in sneak mode
131 *
132 * @return true if player is in sneak mode
133 */
134 public boolean isSneaking();
135
136 /**
137 * Sets the sneak mode the player
138 *
139 * @param sneak true if player should appear sneaking
140 */
141 public void setSneaking(boolean sneak);
142
143 /**
144 * Gets whether the player is sprinting or not.
145 *
146 * @return true if player is sprinting.
147 */
148 public boolean isSprinting();
149
150 /**
151 * Sets whether the player is sprinting or not.
152 *
153 * @param sprinting true if the player should be sprinting
154 */
155 public void setSprinting(boolean sprinting);
156
157 /**
158 * Saves the players current location, health, inventory, motion, and
159 * other information into the username.dat file, in the world/player
160 * folder
161 */
162 public void saveData();
163
164 /**
165 * Loads the players current location, health, inventory, motion, and
166 * other information from the username.dat file, in the world/player
167 * folder.
168 * <p>
169 * Note: This will overwrite the players current inventory, health,
170 * motion, etc, with the state from the saved dat file.
171 */
172 public void loadData();
173
174 /**
175 * Sets whether the player is ignored as not sleeping. If everyone is
176 * either sleeping or has this flag set, then time will advance to the
177 * next day. If everyone has this flag set but no one is actually in bed,
178 * then nothing will happen.
179 *
180 * @param isSleeping Whether to ignore.
181 */
182 public void setSleepingIgnored(boolean isSleeping);
183
184 /**
185 * Returns whether the player is sleeping ignored.
186 *
187 * @return Whether player is ignoring sleep.
188 */
189 public boolean isSleepingIgnored();
190
191 /**
192 * Play a note for a player at a location. This requires a note block
193 * at the particular location (as far as the client is concerned). This
194 * will not work without a note block. This will not work with cake.
195 *
196 * @param loc The location of a note block.
197 * @param instrument The instrument ID.
198 * @param note The note ID.
199 * @deprecated Magic value
200 */
201 @Deprecated
202 public void playNote(Location loc, byte instrument, byte note);
203
204 /**
205 * Play a note for a player at a location. This requires a note block
206 * at the particular location (as far as the client is concerned). This
207 * will not work without a note block. This will not work with cake.
208 *
209 * @param loc The location of a note block
210 * @param instrument The instrument
211 * @param note The note
212 */
213 public void playNote(Location loc, Instrument instrument, Note note);
214
215
216 /**
217 * Play a sound for a player at the location.
218 * <p>
219 * This function will fail silently if Location or Sound are null.
220 *
221 * @param location The location to play the sound
222 * @param sound The sound to play
223 * @param volume The volume of the sound
224 * @param pitch The pitch of the sound
225 */
226 public void playSound(Location location, Sound sound, float volume, float pitch);
227
228 /**
229 * Play a sound for a player at the location.
230 * <p>
231 * This function will fail silently if Location or Sound are null. No
232 * sound will be heard by the player if their client does not have the
233 * respective sound for the value passed.
234 *
235 * @param location the location to play the sound
236 * @param sound the internal sound name to play
237 * @param volume the volume of the sound
238 * @param pitch the pitch of the sound
239 * @deprecated Magic value
240 */
241 @Deprecated
242 public void playSound(Location location, String sound, float volume, float pitch);
243
244 /**
245 * Plays an effect to just this player.
246 *
247 * @param loc the location to play the effect at
248 * @param effect the {@link Effect}
249 * @param data a data bit needed for some effects
250 * @deprecated Magic value
251 */
252 @Deprecated
253 public void playEffect(Location loc, Effect effect, int data);
254
255 /**
256 * Plays an effect to just this player.
257 *
258 * @param loc the location to play the effect at
259 * @param effect the {@link Effect}
260 * @param data a data bit needed for some effects
261 */
262 public <T> void playEffect(Location loc, Effect effect, T data);
263
264 /**
265 * Send a block change. This fakes a block change packet for a user at a
266 * certain location. This will not actually change the world in any way.
267 *
268 * @param loc The location of the changed block
269 * @param material The new block
270 * @param data The block data
271 * @deprecated Magic value
272 */
273 @Deprecated
274 public void sendBlockChange(Location loc, Material material, byte data);
275
276 /**
277 * Send a chunk change. This fakes a chunk change packet for a user at a
278 * certain location. The updated cuboid must be entirely within a single
279 * chunk. This will not actually change the world in any way.
280 * <p>
281 * At least one of the dimensions of the cuboid must be even. The size of
282 * the data buffer must be 2.5*sx*sy*sz and formatted in accordance with
283 * the Packet51 format.
284 *
285 * @param loc The location of the cuboid
286 * @param sx The x size of the cuboid
287 * @param sy The y size of the cuboid
288 * @param sz The z size of the cuboid
289 * @param data The data to be sent
290 * @return true if the chunk change packet was sent
291 * @deprecated Magic value
292 */
293 @Deprecated
294 public boolean sendChunkChange(Location loc, int sx, int sy, int sz, byte[] data);
295
296 /**
297 * Send a block change. This fakes a block change packet for a user at a
298 * certain location. This will not actually change the world in any way.
299 *
300 * @param loc The location of the changed block
301 * @param material The new block ID
302 * @param data The block data
303 * @deprecated Magic value
304 */
305 @Deprecated
306 public void sendBlockChange(Location loc, int material, byte data);
307
308 /**
309 * Send a sign change. This fakes a sign change packet for a user at
310 * a certain location. This will not actually change the world in any way.
311 * This method will use a sign at the location's block or a faked sign
312 * sent via {@link #sendBlockChange(org.bukkit.Location, int, byte)} or
313 * {@link #sendBlockChange(org.bukkit.Location, org.bukkit.Material, byte)}.
314 * <p>
315 * If the client does not have a sign at the given location it will
316 * display an error message to the user.
317 *
318 * @param loc the location of the sign
319 * @param lines the new text on the sign or null to clear it
320 * @throws IllegalArgumentException if location is null
321 * @throws IllegalArgumentException if lines is non-null and has a length less than 4
322 */
323 public void sendSignChange(Location loc, String[] lines) throws IllegalArgumentException;
324
325 /**
326 * Render a map and send it to the player in its entirety. This may be
327 * used when streaming the map in the normal manner is not desirable.
328 *
329 * @param map The map to be sent
330 */
331 public void sendMap(MapView map);
332
333 /**
334 * Forces an update of the player's entire inventory.
335 *
336 * @deprecated This method should not be relied upon as it is a temporary
337 * work-around for a larger, more complicated issue.
338 */
339 @Deprecated
340 public void updateInventory();
341
342 /**
343 * Awards the given achievement and any parent achievements that the
344 * player does not have.
345 *
346 * @param achievement Achievement to award
347 * @throws IllegalArgumentException if achievement is null
348 */
349 public void awardAchievement(Achievement achievement);
350
351 /**
352 * Removes the given achievement and any children achievements that the
353 * player has.
354 *
355 * @param achievement Achievement to remove
356 * @throws IllegalArgumentException if achievement is null
357 */
358 public void removeAchievement(Achievement achievement);
359
360 /**
361 * Gets whether this player has the given achievement.
362 *
363 * @return whether the player has the achievement
364 * @throws IllegalArgumentException if achievement is null
365 */
366 public boolean hasAchievement(Achievement achievement);
367
368 /**
369 * Increments the given statistic for this player.
370 * <p>
371 * This is equivalent to the following code:
372 * <code>incrementStatistic(Statistic, 1)</code>
373 *
374 * @param statistic Statistic to increment
375 * @throws IllegalArgumentException if statistic is null
376 * @throws IllegalArgumentException if the statistic requires an
377 * additional parameter
378 */
379 public void incrementStatistic(Statistic statistic) throws IllegalArgumentException;
380
381 /**
382 * Decrements the given statistic for this player.
383 * <p>
384 * This is equivalent to the following code:
385 * <code>decrementStatistic(Statistic, 1)</code>
386 *
387 * @param statistic Statistic to decrement
388 * @throws IllegalArgumentException if statistic is null
389 * @throws IllegalArgumentException if the statistic requires an
390 * additional parameter
391 */
392 public void decrementStatistic(Statistic statistic) throws IllegalArgumentException;
393
394 /**
395 * Increments the given statistic for this player.
396 *
397 * @param statistic Statistic to increment
398 * @param amount Amount to increment this statistic by
399 * @throws IllegalArgumentException if statistic is null
400 * @throws IllegalArgumentException if amount is negative
401 * @throws IllegalArgumentException if the statistic requires an
402 * additional parameter
403 */
404 public void incrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
405
406 /**
407 * Decrements the given statistic for this player.
408 *
409 * @param statistic Statistic to decrement
410 * @param amount Amount to decrement this statistic by
411 * @throws IllegalArgumentException if statistic is null
412 * @throws IllegalArgumentException if amount is negative
413 * @throws IllegalArgumentException if the statistic requires an
414 * additional parameter
415 */
416 public void decrementStatistic(Statistic statistic, int amount) throws IllegalArgumentException;
417
418 /**
419 * Sets the given statistic for this player.
420 *
421 * @param statistic Statistic to set
422 * @param newValue The value to set this statistic to
423 * @throws IllegalArgumentException if statistic is null
424 * @throws IllegalArgumentException if newValue is negative
425 * @throws IllegalArgumentException if the statistic requires an
426 * additional parameter
427 */
428 public void setStatistic(Statistic statistic, int newValue) throws IllegalArgumentException;
429
430 /**
431 * Gets the value of the given statistic for this player.
432 *
433 * @param statistic Statistic to check
434 * @return the value of the given statistic
435 * @throws IllegalArgumentException if statistic is null
436 * @throws IllegalArgumentException if the statistic requires an
437 * additional parameter
438 */
439 public int getStatistic(Statistic statistic) throws IllegalArgumentException;
440
441 /**
442 * Increments the given statistic for this player for the given material.
443 * <p>
444 * This is equivalent to the following code:
445 * <code>incrementStatistic(Statistic, Material, 1)</code>
446 *
447 * @param statistic Statistic to increment
448 * @param material Material to offset the statistic with
449 * @throws IllegalArgumentException if statistic is null
450 * @throws IllegalArgumentException if material is null
451 * @throws IllegalArgumentException if the given parameter is not valid
452 * for the statistic
453 */
454 public void incrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
455
456 /**
457 * Decrements the given statistic for this player for the given material.
458 * <p>
459 * This is equivalent to the following code:
460 * <code>decrementStatistic(Statistic, Material, 1)</code>
461 *
462 * @param statistic Statistic to decrement
463 * @param material Material to offset the statistic with
464 * @throws IllegalArgumentException if statistic is null
465 * @throws IllegalArgumentException if material is null
466 * @throws IllegalArgumentException if the given parameter is not valid
467 * for the statistic
468 */
469 public void decrementStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
470
471 /**
472 * Gets the value of the given statistic for this player.
473 *
474 * @param statistic Statistic to check
475 * @param material Material offset of the statistic
476 * @return the value of the given statistic
477 * @throws IllegalArgumentException if statistic is null
478 * @throws IllegalArgumentException if material is null
479 * @throws IllegalArgumentException if the given parameter is not valid
480 * for the statistic
481 */
482 public int getStatistic(Statistic statistic, Material material) throws IllegalArgumentException;
483
484 /**
485 * Increments the given statistic for this player for the given material.
486 *
487 * @param statistic Statistic to increment
488 * @param material Material to offset the statistic with
489 * @param amount Amount to increment this statistic by
490 * @throws IllegalArgumentException if statistic is null
491 * @throws IllegalArgumentException if material is null
492 * @throws IllegalArgumentException if amount is negative
493 * @throws IllegalArgumentException if the given parameter is not valid
494 * for the statistic
495 */
496 public void incrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
497
498 /**
499 * Decrements the given statistic for this player for the given material.
500 *
501 * @param statistic Statistic to decrement
502 * @param material Material to offset the statistic with
503 * @param amount Amount to decrement this statistic by
504 * @throws IllegalArgumentException if statistic is null
505 * @throws IllegalArgumentException if material is null
506 * @throws IllegalArgumentException if amount is negative
507 * @throws IllegalArgumentException if the given parameter is not valid
508 * for the statistic
509 */
510 public void decrementStatistic(Statistic statistic, Material material, int amount) throws IllegalArgumentException;
511
512 /**
513 * Sets the given statistic for this player for the given material.
514 *
515 * @param statistic Statistic to set
516 * @param material Material to offset the statistic with
517 * @param newValue The value to set this statistic to
518 * @throws IllegalArgumentException if statistic is null
519 * @throws IllegalArgumentException if material is null
520 * @throws IllegalArgumentException if newValue is negative
521 * @throws IllegalArgumentException if the given parameter is not valid
522 * for the statistic
523 */
524 public void setStatistic(Statistic statistic, Material material, int newValue) throws IllegalArgumentException;
525
526 /**
527 * Increments the given statistic for this player for the given entity.
528 * <p>
529 * This is equivalent to the following code:
530 * <code>incrementStatistic(Statistic, EntityType, 1)</code>
531 *
532 * @param statistic Statistic to increment
533 * @param entityType EntityType to offset the statistic with
534 * @throws IllegalArgumentException if statistic is null
535 * @throws IllegalArgumentException if entityType is null
536 * @throws IllegalArgumentException if the given parameter is not valid
537 * for the statistic
538 */
539 public void incrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
540
541 /**
542 * Decrements the given statistic for this player for the given entity.
543 * <p>
544 * This is equivalent to the following code:
545 * <code>decrementStatistic(Statistic, EntityType, 1)</code>
546 *
547 * @param statistic Statistic to decrement
548 * @param entityType EntityType to offset the statistic with
549 * @throws IllegalArgumentException if statistic is null
550 * @throws IllegalArgumentException if entityType is null
551 * @throws IllegalArgumentException if the given parameter is not valid
552 * for the statistic
553 */
554 public void decrementStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
555
556 /**
557 * Gets the value of the given statistic for this player.
558 *
559 * @param statistic Statistic to check
560 * @param entityType EntityType offset of the statistic
561 * @return the value of the given statistic
562 * @throws IllegalArgumentException if statistic is null
563 * @throws IllegalArgumentException if entityType is null
564 * @throws IllegalArgumentException if the given parameter is not valid
565 * for the statistic
566 */
567 public int getStatistic(Statistic statistic, EntityType entityType) throws IllegalArgumentException;
568
569 /**
570 * Increments the given statistic for this player for the given entity.
571 *
572 * @param statistic Statistic to increment
573 * @param entityType EntityType to offset the statistic with
574 * @param amount Amount to increment this statistic by
575 * @throws IllegalArgumentException if statistic is null
576 * @throws IllegalArgumentException if entityType is null
577 * @throws IllegalArgumentException if amount is negative
578 * @throws IllegalArgumentException if the given parameter is not valid
579 * for the statistic
580 */
581 public void incrementStatistic(Statistic statistic, EntityType entityType, int amount) throws IllegalArgumentException;
582
583 /**
584 * Decrements the given statistic for this player for the given entity.
585 *
586 * @param statistic Statistic to decrement
587 * @param entityType EntityType to offset the statistic with
588 * @param amount Amount to decrement this statistic by
589 * @throws IllegalArgumentException if statistic is null
590 * @throws IllegalArgumentException if entityType is null
591 * @throws IllegalArgumentException if amount is negative
592 * @throws IllegalArgumentException if the given parameter is not valid
593 * for the statistic
594 */
595 public void decrementStatistic(Statistic statistic, EntityType entityType, int amount);
596
597 /**
598 * Sets the given statistic for this player for the given entity.
599 *
600 * @param statistic Statistic to set
601 * @param entityType EntityType to offset the statistic with
602 * @param newValue The value to set this statistic to
603 * @throws IllegalArgumentException if statistic is null
604 * @throws IllegalArgumentException if entityType is null
605 * @throws IllegalArgumentException if newValue is negative
606 * @throws IllegalArgumentException if the given parameter is not valid
607 * for the statistic
608 */
609 public void setStatistic(Statistic statistic, EntityType entityType, int newValue);
610
611 /**
612 * Sets the current time on the player's client. When relative is true the
613 * player's time will be kept synchronized to its world time with the
614 * specified offset.
615 * <p>
616 * When using non relative time the player's time will stay fixed at the
617 * specified time parameter. It's up to the caller to continue updating
618 * the player's time. To restore player time to normal use
619 * resetPlayerTime().
620 *
621 * @param time The current player's perceived time or the player's time
622 * offset from the server time.
623 * @param relative When true the player time is kept relative to its world
624 * time.
625 */
626 public void setPlayerTime(long time, boolean relative);
627
628 /**
629 * Returns the player's current timestamp.
630 *
631 * @return The player's time
632 */
633 public long getPlayerTime();
634
635 /**
636 * Returns the player's current time offset relative to server time, or
637 * the current player's fixed time if the player's time is absolute.
638 *
639 * @return The player's time
640 */
641 public long getPlayerTimeOffset();
642
643 /**
644 * Returns true if the player's time is relative to the server time,
645 * otherwise the player's time is absolute and will not change its current
646 * time unless done so with setPlayerTime().
647 *
648 * @return true if the player's time is relative to the server time.
649 */
650 public boolean isPlayerTimeRelative();
651
652 /**
653 * Restores the normal condition where the player's time is synchronized
654 * with the server time.
655 * <p>
656 * Equivalent to calling setPlayerTime(0, true).
657 */
658 public void resetPlayerTime();
659
660 /**
661 * Sets the type of weather the player will see. When used, the weather
662 * status of the player is locked until {@link #resetPlayerWeather()} is
663 * used.
664 *
665 * @param type The WeatherType enum type the player should experience
666 */
667 public void setPlayerWeather(WeatherType type);
668
669 /**
670 * Returns the type of weather the player is currently experiencing.
671 *
672 * @return The WeatherType that the player is currently experiencing or
673 * null if player is seeing server weather.
674 */
675 public WeatherType getPlayerWeather();
676
677 /**
678 * Restores the normal condition where the player's weather is controlled
679 * by server conditions.
680 */
681 public void resetPlayerWeather();
682
683 /**
684 * Gives the player the amount of experience specified.
685 *
686 * @param amount Exp amount to give
687 */
688 public void giveExp(int amount);
689
690 /**
691 * Gives the player the amount of experience levels specified. Levels can
692 * be taken by specifying a negative amount.
693 *
694 * @param amount amount of experience levels to give or take
695 */
696 public void giveExpLevels(int amount);
697
698 /**
699 * Gets the players current experience points towards the next level.
700 * <p>
701 * This is a percentage value. 0 is "no progress" and 1 is "next level".
702 *
703 * @return Current experience points
704 */
705 public float getExp();
706
707 /**
708 * Sets the players current experience points towards the next level
709 * <p>
710 * This is a percentage value. 0 is "no progress" and 1 is "next level".
711 *
712 * @param exp New experience points
713 */
714 public void setExp(float exp);
715
716 /**
717 * Gets the players current experience level
718 *
719 * @return Current experience level
720 */
721 public int getLevel();
722
723 /**
724 * Sets the players current experience level
725 *
726 * @param level New experience level
727 */
728 public void setLevel(int level);
729
730 /**
731 * Gets the players total experience points
732 *
733 * @return Current total experience points
734 */
735 public int getTotalExperience();
736
737 /**
738 * Sets the players current experience level
739 *
740 * @param exp New experience level
741 */
742 public void setTotalExperience(int exp);
743
744 /**
745 * Gets the players current exhaustion level.
746 * <p>
747 * Exhaustion controls how fast the food level drops. While you have a
748 * certain amount of exhaustion, your saturation will drop to zero, and
749 * then your food will drop to zero.
750 *
751 * @return Exhaustion level
752 */
753 public float getExhaustion();
754
755 /**
756 * Sets the players current exhaustion level
757 *
758 * @param value Exhaustion level
759 */
760 public void setExhaustion(float value);
761
762 /**
763 * Gets the players current saturation level.
764 * <p>
765 * Saturation is a buffer for food level. Your food level will not drop if
766 * you are saturated > 0.
767 *
768 * @return Saturation level
769 */
770 public float getSaturation();
771
772 /**
773 * Sets the players current saturation level
774 *
775 * @param value Saturation level
776 */
777 public void setSaturation(float value);
778
779 /**
780 * Gets the players current food level
781 *
782 * @return Food level
783 */
784 public int getFoodLevel();
785
786 /**
787 * Sets the players current food level
788 *
789 * @param value New food level
790 */
791 public void setFoodLevel(int value);
792
793 /**
794 * Gets the Location where the player will spawn at their bed, null if
795 * they have not slept in one or their current bed spawn is invalid.
796 *
797 * @return Bed Spawn Location if bed exists, otherwise null.
798 */
799 public Location getBedSpawnLocation();
800
801 /**
802 * Sets the Location where the player will spawn at their bed.
803 *
804 * @param location where to set the respawn location
805 */
806 public void setBedSpawnLocation(Location location);
807
808 /**
809 * Sets the Location where the player will spawn at their bed.
810 *
811 * @param location where to set the respawn location
812 * @param force whether to forcefully set the respawn location even if a
813 * valid bed is not present
814 */
815 public void setBedSpawnLocation(Location location, boolean force);
816
817 /**
818 * Determines if the Player is allowed to fly via jump key double-tap like
819 * in creative mode.
820 *
821 * @return True if the player is allowed to fly.
822 */
823 public boolean getAllowFlight();
824
825 /**
826 * Sets if the Player is allowed to fly via jump key double-tap like in
827 * creative mode.
828 *
829 * @param flight If flight should be allowed.
830 */
831 public void setAllowFlight(boolean flight);
832
833 /**
834 * Hides a player from this player
835 *
836 * @param player Player to hide
837 */
838 public void hidePlayer(Player player);
839
840 /**
841 * Allows this player to see a player that was previously hidden
842 *
843 * @param player Player to show
844 */
845 public void showPlayer(Player player);
846
847 /**
848 * Checks to see if a player has been hidden from this player
849 *
850 * @param player Player to check
851 * @return True if the provided player is not being hidden from this
852 * player
853 */
854 public boolean canSee(Player player);
855
856 /**
857 * Checks to see if this player is currently standing on a block. This
858 * information may not be reliable, as it is a state provided by the
859 * client, and may therefore not be accurate.
860 *
861 * @return True if the player standing on a solid block, else false.
862 * @deprecated Inconsistent with {@link
863 * org.bukkit.entity.Entity#isOnGround()}
864 */
865 @Deprecated
866 public boolean isOnGround();
867
868 /**
869 * Checks to see if this player is currently flying or not.
870 *
871 * @return True if the player is flying, else false.
872 */
873 public boolean isFlying();
874
875 /**
876 * Makes this player start or stop flying.
877 *
878 * @param value True to fly.
879 */
880 public void setFlying(boolean value);
881
882 /**
883 * Sets the speed at which a client will fly. Negative values indicate
884 * reverse directions.
885 *
886 * @param value The new speed, from -1 to 1.
887 * @throws IllegalArgumentException If new speed is less than -1 or
888 * greater than 1
889 */
890 public void setFlySpeed(float value) throws IllegalArgumentException;
891
892 /**
893 * Sets the speed at which a client will walk. Negative values indicate
894 * reverse directions.
895 *
896 * @param value The new speed, from -1 to 1.
897 * @throws IllegalArgumentException If new speed is less than -1 or
898 * greater than 1
899 */
900 public void setWalkSpeed(float value) throws IllegalArgumentException;
901
902 /**
903 * Gets the current allowed speed that a client can fly.
904 *
905 * @return The current allowed speed, from -1 to 1
906 */
907 public float getFlySpeed();
908
909 /**
910 * Gets the current allowed speed that a client can walk.
911 *
912 * @return The current allowed speed, from -1 to 1
913 */
914 public float getWalkSpeed();
915
916 /**
917 * Request that the player's client download and switch texture packs.
918 * <p>
919 * The player's client will download the new texture pack asynchronously
920 * in the background, and will automatically switch to it once the
921 * download is complete. If the client has downloaded and cached the same
922 * texture pack in the past, it will perform a quick timestamp check over
923 * the network to determine if the texture pack has changed and needs to
924 * be downloaded again. When this request is sent for the very first time
925 * from a given server, the client will first display a confirmation GUI
926 * to the player before proceeding with the download.
927 * <p>
928 * Notes:
929 * <ul>
930 * <li>Players can disable server textures on their client, in which
931 * case this method will have no affect on them.
932 * <li>There is no concept of resetting texture packs back to default
933 * within Minecraft, so players will have to relog to do so.
934 * </ul>
935 *
936 * @param url The URL from which the client will download the texture
937 * pack. The string must contain only US-ASCII characters and should
938 * be encoded as per RFC 1738.
939 * @throws IllegalArgumentException Thrown if the URL is null.
940 * @throws IllegalArgumentException Thrown if the URL is too long.
941 * @deprecated Minecraft no longer uses textures packs. Instead you
942 * should use {@link #setResourcePack(String)}.
943 */
944 @Deprecated
945 public void setTexturePack(String url);
946
947 /**
948 * Request that the player's client download and switch resource packs.
949 * <p>
950 * The player's client will download the new resource pack asynchronously
951 * in the background, and will automatically switch to it once the
952 * download is complete. If the client has downloaded and cached the same
953 * resource pack in the past, it will perform a quick timestamp check
954 * over the network to determine if the resource pack has changed and
955 * needs to be downloaded again. When this request is sent for the very
956 * first time from a given server, the client will first display a
957 * confirmation GUI to the player before proceeding with the download.
958 * <p>
959 * Notes:
960 * <ul>
961 * <li>Players can disable server resources on their client, in which
962 * case this method will have no affect on them.
963 * <li>There is no concept of resetting resource packs back to default
964 * within Minecraft, so players will have to relog to do so.
965 * </ul>
966 *
967 * @param url The URL from which the client will download the resource
968 * pack. The string must contain only US-ASCII characters and should
969 * be encoded as per RFC 1738.
970 * @throws IllegalArgumentException Thrown if the URL is null.
971 * @throws IllegalArgumentException Thrown if the URL is too long. The
972 * length restriction is an implementation specific arbitrary value.
973 */
974 public void setResourcePack(String url);
975
976 /**
977 * Gets the Scoreboard displayed to this player
978 *
979 * @return The current scoreboard seen by this player
980 */
981 public Scoreboard getScoreboard();
982
983 /**
984 * Sets the player's visible Scoreboard.
985 *
986 * @param scoreboard New Scoreboard for the player
987 * @throws IllegalArgumentException if scoreboard is null
988 * @throws IllegalArgumentException if scoreboard was not created by the
989 * {@link org.bukkit.scoreboard.ScoreboardManager scoreboard manager}
990 * @throws IllegalStateException if this is a player that is not logged
991 * yet or has logged out
992 */
993 public void setScoreboard(Scoreboard scoreboard) throws IllegalArgumentException, IllegalStateException;
994
995 /**
996 * Gets if the client is displayed a 'scaled' health, that is, health on a
997 * scale from 0-{@link #getHealthScale()}.
998 *
999 * @return if client health display is scaled
1000 * @see Player#setHealthScaled(boolean)
1001 */
1002 public boolean isHealthScaled();
1003
1004 /**
1005 * Sets if the client is displayed a 'scaled' health, that is, health on a
1006 * scale from 0-{@link #getHealthScale()}.
1007 * <p>
1008 * Displayed health follows a simple formula <code>displayedHealth =
1009 * getHealth() / getMaxHealth() * getHealthScale()</code>.
1010 *
1011 * @param scale if the client health display is scaled
1012 */
1013 public void setHealthScaled(boolean scale);
1014
1015 /**
1016 * Sets the number to scale health to for the client; this will also
1017 * {@link #setHealthScaled(boolean) setHealthScaled(true)}.
1018 * <p>
1019 * Displayed health follows a simple formula <code>displayedHealth =
1020 * getHealth() / getMaxHealth() * getHealthScale()</code>.
1021 *
1022 * @param scale the number to scale health to
1023 * @throws IllegalArgumentException if scale is <0
1024 * @throws IllegalArgumentException if scale is {@link Double#NaN}
1025 * @throws IllegalArgumentException if scale is too high
1026 */
1027 public void setHealthScale(double scale) throws IllegalArgumentException;
1028
1029 /**
1030 * Gets the number that health is scaled to for the client.
1031 *
1032 * @return the number that health would be scaled to for the client if
1033 * HealthScaling is set to true
1034 * @see Player#setHealthScale(double)
1035 * @see Player#setHealthScaled(boolean)
1036 */
1037 public double getHealthScale();
1038 }