Difference between revisions of "API Implementation"

From Feudal Wiki
Jump to: navigation, search
(New API)
Line 1: Line 1:
 
Feudal is not limited to just itself.  Feudal can be used as an API when developing plugins for Spigot or Bukkit.  This page will explain how to use Feudal's API and provide information on how to use parts of Feudal which are not explained here.
 
Feudal is not limited to just itself.  Feudal can be used as an API when developing plugins for Spigot or Bukkit.  This page will explain how to use Feudal's API and provide information on how to use parts of Feudal which are not explained here.
  
It is recommended that you add the following to your plugin yml when using Feudal as an API:
+
It is recommended that you add the following to your plugin yml when using Feudal as an API. This will make Feudal enable before your plugin:
 
<pre>softdepend: [Feudal]</pre>
 
<pre>softdepend: [Feudal]</pre>
  
Line 10: Line 10:
  
  
==Accessing the Feudal Class==
+
==Accessing Feudal==
The Feudal class is the heart of the Feudal.
+
First make sure Feudal.jar is setup as a library for your project. It is done the same way you use Spigot.jar or Bukkit.jar as a library.
  
 
When accessing any parts of Feudal you should always make sure that Feudal is running.  To do so use the following code:
 
When accessing any parts of Feudal you should always make sure that Feudal is running.  To do so use the following code:
Line 18: Line 18:
 
}</pre>
 
}</pre>
  
If that returns true, then you know Feudal is on the server and running.  Now you can get the Feudal class with the following code:
+
If that returns true, then you know Feudal is on the server and running.  Now you can get the FeudalAPI class with the following code:
<pre>Feudal feudal = Feudal.getPlugin();</pre>
+
<pre>FeudalAPI feudal = Feudal.getAPI();</pre>
  
 +
You should not have any Feudal code or imports included inside of any of your classes which have code doing other things (unless you require Feudal to always be on the server). You should have a class or a few classes dedicated to running any Feudal methods you need. This will allow a user to use your plugin with OR without Feudal. Just every time you make a call to that feudal handling class, make sure Feudal is enabled. You do not need to check if it is enabled every time, so you could use the code above to set a boolean in your main class and just check that variable.
 +
 +
To be sure you did it this right, temporarily remove Feudal.jar as a library and refresh your project. If there are any errors in classes which are essential to run your plugin, then you should move the code which has those errors into another class otherwise a person using your plugin will have to have Feudal installed.
  
 
==Get a User==
 
==Get a User==
When getting a user we need to check that Feudal is running just like before.  Then to get a user you can use the following code:
+
In this example `player` is a Bukkit Player.
<pre>User user = Feudal.getUser(player.getUniqueId().toString());</pre>
+
<pre>User user = Feudal.getAPI().getUser(player.getUUID());</pre>
 +
OR
 +
<pre>User user = Feudal.getAPI().getUser(player.getName());</pre>
  
 
This will return null if this player has no user data or if the user has never joined before or if they have joined, but have not created their character yet.
 
This will return null if this player has no user data or if the user has never joined before or if they have joined, but have not created their character yet.
  
  
==Get an Offline Player's UUID==
+
==Get a Player's Kingdom==
If a player has joined the server in the past and they are offline, you may need to get their uuid.  Instead of looking it up with the server or pinging a service for this information, you can use the following code to do this through Feudal.
+
You can get a player's kingdom from their Bukkit Player, their name, their UUID, or their Feudal User.
<pre>Feudal.getPlayerData().getConfig().getString(username);</pre>
+
  
 +
Getting their kingdom from their UUID:
 +
<pre>Kingdom kingdom = Feudal.getAPI().getKingdom(player.getUniqueId())</pre>
  
==Get a Player's Kingdom==
+
Getting a kingdom from a Feudal User.
To get a player's kingdom you either need their UUID or their User.  We will fist start with their UUID.
+
<pre>Kingdom kingdom = Feudal.getAPI().getKingdom(user)</pre>
<pre>for(Kingdom kingdom : Feudal.getKingdoms()){
+
 
if(kingdom.isMember(uuid)){
+
Getting a kingdom from an OfflinePlayer (Can also use Bukkit Player).
//This player is in this kingdom
+
<pre>Kingdom kingdom = Feudal.getAPI().getKingdom(offlinePlayer)</pre>
}
+
}</pre>
+
This method is not suggested because data corrupt on either the Kingdom's end or User's end will result in problems.
+
Getting a kingdom from a User will check both ends.
+
<pre>Kingdom king = null;
+
if(user != null && !user.getKingdomUUID().equals("")){
+
king = Feudal.getKingdom(user.getKingdomUUID());
+
}</pre>
+
 
Note that a kingdom can be null.
 
Note that a kingdom can be null.
  
Line 53: Line 51:
 
Use the following code to get a kingdom from a location.
 
Use the following code to get a kingdom from a location.
 
This kingdom can be null since not all land is claimed.
 
This kingdom can be null since not all land is claimed.
<pre>Land land = new Land(player.getLocation());
+
<pre>Kingdom kingdom = Feudal.getAPI().getKingdom(location)</pre>
Kingdom king = Feudal.getLandKingdom(land);</pre>
+
The `location` variable is a Bukkit Location.
 +
 
 +
 
 +
==Custom Feudal Command==
 +
Perhaps you need to add a sub command to Feudal. To learn how to do that, click here to read about [Custom Feudal Commands].
 +
 
 +
 
 +
==Feudal Events==
 +
There are also some Feudal events which can be used just like all other Bukkit events, but they are triggered when a specific think in Feudal happens.
 +
Read about [Feudal Events] here.
 +
 
 +
 
 +
==Get a Challenge==
 +
If you need to get an active challenge/war, you can also use this API.
 +
 
 +
If you want to get all active challenges for a specific kingdom, use the following:
 +
<pre>List<Challenge> challenges = Feudal.getAPI().getChallenges(kingdom);</pre>
 +
 
 +
If you want to get ALL active challenges, use the following:
 +
<pre>List<Challenge> challenges = Feudal.getAPI().getChallenges();</pre>
 +
 
 +
If you want to get the challenge between two kingdoms, use the following:
 +
<pre>Challenge challenge = Feudal.getAPI().getChallenge(attacker, defender);</pre>
  
  
 
==Language File==
 
==Language File==
 
While using the Feudal API you might want to use some of the strings from the language file.  To do so use the following code:
 
While using the Feudal API you might want to use some of the strings from the language file.  To do so use the following code:
<pre>Feudal.getMessage("configField");</pre>
+
<pre>Feudal.getAPI().getMessage("configField");</pre>
 
If the config field is missing this won't return null, but it will return "§4§lLANGUAGE INFORMATION MISSING", and an error will be sent to console.
 
If the config field is missing this won't return null, but it will return "§4§lLANGUAGE INFORMATION MISSING", and an error will be sent to console.
 
When the config field exists then the message will be returned, but & will be replaced with the color code and §§ will be replaced with &.
 
When the config field exists then the message will be returned, but & will be replaced with the color code and §§ will be replaced with &.

Revision as of 01:41, 16 July 2017

Feudal is not limited to just itself. Feudal can be used as an API when developing plugins for Spigot or Bukkit. This page will explain how to use Feudal's API and provide information on how to use parts of Feudal which are not explained here.

It is recommended that you add the following to your plugin yml when using Feudal as an API. This will make Feudal enable before your plugin:

softdepend: [Feudal]

JavaDoc

Feudal has java documentation, but the definitions for returns and param are currently not explained. However, Feudal JavaDocs will still be very useful when using Feudal as an API.

Feudal JavaDoc


Accessing Feudal

First make sure Feudal.jar is setup as a library for your project. It is done the same way you use Spigot.jar or Bukkit.jar as a library.

When accessing any parts of Feudal you should always make sure that Feudal is running. To do so use the following code:

private boolean isUsingFeudal(){
	return Bukkit.getPluginManager().getPlugin("Feudal") != null && Bukkit.getPluginManager().getPlugin("Feudal").isEnabled();
}

If that returns true, then you know Feudal is on the server and running. Now you can get the FeudalAPI class with the following code:

FeudalAPI feudal = Feudal.getAPI();

You should not have any Feudal code or imports included inside of any of your classes which have code doing other things (unless you require Feudal to always be on the server). You should have a class or a few classes dedicated to running any Feudal methods you need. This will allow a user to use your plugin with OR without Feudal. Just every time you make a call to that feudal handling class, make sure Feudal is enabled. You do not need to check if it is enabled every time, so you could use the code above to set a boolean in your main class and just check that variable.

To be sure you did it this right, temporarily remove Feudal.jar as a library and refresh your project. If there are any errors in classes which are essential to run your plugin, then you should move the code which has those errors into another class otherwise a person using your plugin will have to have Feudal installed.

Get a User

In this example `player` is a Bukkit Player.

User user = Feudal.getAPI().getUser(player.getUUID());

OR

User user = Feudal.getAPI().getUser(player.getName());

This will return null if this player has no user data or if the user has never joined before or if they have joined, but have not created their character yet.


Get a Player's Kingdom

You can get a player's kingdom from their Bukkit Player, their name, their UUID, or their Feudal User.

Getting their kingdom from their UUID:

Kingdom kingdom = Feudal.getAPI().getKingdom(player.getUniqueId())

Getting a kingdom from a Feudal User.

Kingdom kingdom = Feudal.getAPI().getKingdom(user)

Getting a kingdom from an OfflinePlayer (Can also use Bukkit Player).

Kingdom kingdom = Feudal.getAPI().getKingdom(offlinePlayer)

Note that a kingdom can be null.


Get a Kingdom From Location

Use the following code to get a kingdom from a location. This kingdom can be null since not all land is claimed.

Kingdom kingdom = Feudal.getAPI().getKingdom(location)

The `location` variable is a Bukkit Location.


Custom Feudal Command

Perhaps you need to add a sub command to Feudal. To learn how to do that, click here to read about [Custom Feudal Commands].


Feudal Events

There are also some Feudal events which can be used just like all other Bukkit events, but they are triggered when a specific think in Feudal happens. Read about [Feudal Events] here.


Get a Challenge

If you need to get an active challenge/war, you can also use this API.

If you want to get all active challenges for a specific kingdom, use the following:

List<Challenge> challenges = Feudal.getAPI().getChallenges(kingdom);

If you want to get ALL active challenges, use the following:

List<Challenge> challenges = Feudal.getAPI().getChallenges();

If you want to get the challenge between two kingdoms, use the following:

Challenge challenge = Feudal.getAPI().getChallenge(attacker, defender);


Language File

While using the Feudal API you might want to use some of the strings from the language file. To do so use the following code:

Feudal.getAPI().getMessage("configField");

If the config field is missing this won't return null, but it will return "§4§lLANGUAGE INFORMATION MISSING", and an error will be sent to console. When the config field exists then the message will be returned, but & will be replaced with the color code and §§ will be replaced with &.


Is More Information Needed?

Does this page not cover enough information? If so, message "forseth11" on spigotmc.org.