Developer API
This page should give you the basics on obtaining and utilizing the DisguiseCraft API.
Prerequisites
Start off by downloading the latest version of DisguiseCraft. Then, you must add the .jar file to your project's build path. Also make sure to add "depend: [DisguiseCraft]" to your plugin.yml if your plugin needs DisguiseCraft on the server to run. If your DisguiseCraft support is optional, use "softdepend: [DisguiseCraft]" in your plugin.yml.
The API
Here we explain the basics behind the DisguiseCraft API class.
Obtaining the API
The API comes in the form of the DisguiseCraftAPI
class. You obtain it by calling the getAPI() static function in the DisguiseCraft
class.
Here's the recommended function for obtaining and keeping the API variable:
DisguiseCraftAPI dcAPI; public void setupDisguiseCraft() { dcAPI = DisguiseCraft.getAPI(); }
To use it, you just run setupDisguiseCraft() in your onEnable() method.
Using the API
The API contains methods which allow you to obtain and set disguises. We will go over some important ones.
isDisguised(Player player)
This boolean function returns whether or not a player is disguised.
Example usage:
if (dcAPI.isDisguised(player)) { System.out.println(player.getName() + " is disguised!"); } else { System.out.println(player.getName() + " is not disguised!"); }
getDisguise(Player player)
Once you've confirmed that a player is disguised, you can obtain the Disguise
object by using this function.
disguisePlayer(Player player, Disguise disguise)
If a player is not yet disguised, you can disguise him using this function.
A boolean return allows you to tell if the player was disguised. (false means the disguise was cancelled)
changePlayerDisguise(Player player, Disguise newDisguise)
If a player is disguised already, you disguise them using this function.
A boolean return allows you to tell if the player was disguised. (false means the disguise was cancelled)
undisguisePlayer(Player player)
This function allows you to undisguise a disguise player.
A boolean return allows you to tell if the player was undisguised. (false means the undisguise was cancelled)
Disguises
All disguises are represented by the Disguise
class.
There are many packet functions in this class. Unless you know what you are doing, we ask that you avoid using these functions as improper packet creation can crash clients.
Creating a disguise
To create a disguise, you use one of the Disguise
class's constructors.
Mobs
For example, to create a simple mob disguise:
new Disguise(dcAPI.newEntityID(), DisguiseType.Cow)
Players
Player disguises have the players name as the first value of their metadata LinkedList.
This will create a disguise for a player named "PlayerName":
new Disguise(dcAPI.newEntityID(), "PlayerName", DisguiseType.Player);
Notice that we've used the API's newEntityID() function. This gives us a fresh entity ID that shouldn't interfere with other disguises or mobs on the client's end.
Editing a disguise
If a player is already disguised, it is better to clone and edit the disguise than construct a new one.
All the .set methods return the disguise to allow for chaining.
clone()
This function will give you a carbon copy of the Disguise
object that you can freely edit before applying to a player.
isPlayer()
This boolean function allows you to know whether or not a disguise is of another player.
The player's name is stored in the first String of the "data" LinkedList<String>.
setSingleData(String data)
If the disguise is of a player, it is useful to use this method in order to change the name.
setMob(MobType mob)
This method allows you to set the type of mob the Disguise is.
Events
Custom events from DisguiseCraft are handled just like any other event in Bukkit. You create an event-handler which accepts the proper event as an input. There are three basic, cancellable events thrown by DisguiseCraft: Command, Disguise, Undisguise
DCCommandEvent
This event is triggered whenever someone uses a DisguiseCraft command. (e.g. /d Wolf, /undisguise)
When cancelled, the command is not sent to DisguiseCraft's command parser and any output is handled elsewhere.
PlayerDisguiseEvent
This event is triggered whenever a player is to disguise. It is also triggered when a plugin attempts to disguise a player through the API or when a player has successfully used the disguise command.
Cancelling this event prevents the disguising of the player.
PlayerUndisguiseEvent
This event is triggered whenever a player is to be undisguised. However, it is not called when a player is undisguised for leaving the server.
Cancelling this event will prevent the player's undisguise.
Useful Links
- DisguiseCraft JavaDocs <== Always points to the latest generated
- Bukkit JavaDocs
Maven Integreation
If you use maven, here's a link to our Maven repository: http://build.yu8.me:8080/plugin/repository/everything/
Still Need Help?
You'll likely be able to find one of DisguiseCraft's developers in this IRC channel: irc://irc.mibbit.com/pinoygamers
We'd be glad to help you get DisguiseCraft integration working in your plugin.
How Do You Disguise A Player As A Player Using This API
@DrFantasmo2012
This will disguise "player" as "PlayerName":
Player disguises have "null" as their mob type and the player's name in the data area.
@Devil_Boy
Thank You, This Will e Implemented In The New Version Of BeHerobrine.
@DrFantasmo2012
No problem. I should probably document that XD
BTW, I just edited my previous comment to match the code used in DisguiseCraft.
@Devil_Boy
Thx For Making The Plugin First Of All, Also I Just Finished The BeHerobrine Update...You Should Check It Out,
PS: And add it to your utilizes API list.
@DrFantasmo2012
Brilliant! Adding right now.
I did look through your code and found the source of the issue Jong1 reported about using your plugin with MobDisguise. I'll send you a PM about the best way to fix it.
@Devil_Boy
thx
I thought I would share with what I am doing to hook into events! I thought it was pretty cool.
So in my main onEnable() function I run this
Then, I create the new class file called DCListener and setup my events in there!
Oh, hint hint Devil_Boy adding support for your plugin to mine.. :P
@MarkehMe
Awesome. I totally just now realized that I left event-handling out of this tutorial XD
I'll probably write some up when I get time.
So what does your DisguiseCraft support supply? ;)
@Devil_Boy
I created a plugin called FactionsPlus to hook into Factions to add extra features that the original developers haven't added, and I'm adding a feature so that when they enter enemy land it automatically un-disguises them, and when they're in enemy land they can't disguise them-self.
I'll possibly see how much more I can use the API when I have free time :)
@MarkehMe
Brilliant! I've already added you to our list of plugins utilizing the API.
Tell me when you have it added, I always check out how people code their plugins to use our API. You guys tend to have many different ways of handling the API depending on the situation.
@Devil_Boy
Apologies for the late reply! Sure will do, if I remember. In fact I'll add it to my todo list in the code to tell you!
@MarkehMe
I just looked at the code of your 0.4.3 release and there's just a small thing in your DCListener class I want to mention.
The disguise event is triggered when a player attempts to disguise. This means the the player is not actually disguised yet. This merely means that you do not need to unDisguise() the players in this event. Your setCancelled(true) should suffice.
Other than that, it all looks good!
@Devil_Boy
Ah right, I wasn't 100% sure and wanted to push the release out as fast as possible. :P
Thanks though! Excuse the messy code!
@choltfo
You put the
MobType
enum of the mob you want. You can find this enum in DisguiseCraft'sDisguise
class.As for your other question: Are you sure you are handling events correctly? O.o
@choltfo
If you want to see samples of how to properly handle events: https://gitorious.org/+pg-dev-team
Just look at the command handling classes. A method is made that accepts a certain event. The method is registered as a listener in the
onEnable()
method.To disguise a player who ran a command, possible code is:
Of course it was always be more preferable to save the API as a variable and include a check to make sure the command-sender is in fact a player.
Can I use the Event EntityDamageByEntity normaly, when 2 disguised players hit each other? Or do I have to check for their EntityIDs from the disguises? It's hard to explain.
Or like that: If I call getDamager() from the event, do I get the player or the mob from his disguise?
@RayKatz
You can use that event normally. It should give you the player within the disguise.
Is there a way to turn off the permissions checking? I use my own permissions system so this does not work unless your an OP and im not planning on OP'ing every player :)
@Rpgminecraft
I'm assuming with Devil's permission, see if you can edit the api to change the permission effects