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 can you disguise player as a mobtype, like a kind of village
@mcat95
What?
@Devil_Boy
for example, disguise to a player like a BlackSmit Villager
@mcat95
Using the API or commands? o.o
With commands, it's: /d blacksmith villager
With the API I believe it's:
new Disguise(dcAPI.getNewEntityID(), "blacksmith", MobType.Villager);
However, the API is being changed, so it may become:
new Disguise(dcAPI.getNewEntityID(), "blacksmith", DisguiseType.Villager);
Is it compatible with TagAPI?
@TheOneMadHawk
If TagAPI uses ProtocolLib, then DisguiseCraft shouldn't interfere with it o.o
mbaxter, lishid, and I chose to use ProtocolLib as common ground between our plugins.
Its posible to disguise as a green Villager (profession 5)?
@mcat95
I remember implementing it, but don't recall documenting it.
We named it the: generic villager
Hey :)
I guessed that a disguise of wool may be done by the following:
However this gives a subtype of "35" and the block id of 19 (No idea where that comes from).
How can you do this so I can set the id of the block i want a player to be disguised as? Thanks!
@Tomskied
Very close :O
19 is just a default for when a block ID subtype isn't detected.
The actual subtype for you is:
blockID:35
For more info: https://gitorious.org/disguisecraft/disguisecraft/blobs/master/src/pgDev/bukkit/DisguiseCraft/disguise/Disguise.java#line470
@Devil_Boy
Perfect! I'm pretty much done with my first version of the plugin I'm using with this. There is some short info here if you are interested (http://dev.bukkit.org/server-mods/tomskiesprophunt/). Ill obviously be pointing in your direction when I have a file to upload, I hope this is ok with you.
I have one last bug to iron out though;
When players are killed, people that have been disguised as a block appear invisible to them, is there a way to refresh the packets sent to the player that was killed, or is there something else going on that I would need to do?
Cheers!
@Tomskied
The invisibility thing is a bug on my end. I need to rewrite the respawn-handling code of DisguiseCraft :/
If it's too much of an issue for you right now, you can listen for PlayerResawn (at low priority) and undisguise and redisguise the player. This should fix the issue as far as I know.
Also, have you played around with the "blocklock" metadata yet? ;)
@Devil_Boy
I fixed that bug by just refreshing all players on a delayed task after respawn. Which is no hassle really.
What is the blocklock meta?! I've just put out my first betas, going really well now, its great fun!
@Tomskied
Try disguising as a block, then typing: /d blocklock
When people see your, you'll be locked to the block grid properly. This makes it much harder for people to tell that you're the block.
@Devil_Boy
Edit: disguise.addSingleData("blocklock"); This is the way to do this? Haven't tested it yet.
@Tomskied
That should be it :)
I'm currently using DisguiseCraft for my Dwarves vs Zombies plugin(Link)
But I have a question: Is there a way using the api to disguise Players that don't have the Permission to disguise?
@And_S
Yes, using disguisePlayer() and changeDisguise() in the API will disguise a player regardless of permissions.
@Devil_Boy
But it still says: You've been undidguised because you do not have permissions to wear that disguise in this world.
This may be related to the fact that all Players are in a custom world named DvZ_Main
This is my Code:
But using this in PlayerJoinEvent works:
@And_S
Are the players changing world while disguised? o.o
Either, they don't have the permissions for the disguise in the new world, or DisguiseCraft has old permission checks.