developer's documentation

Developers' Documentation to Work with (and maybe Break) xEcon

Main xEcon API

0. Make sure you know what you want to do.

You want to take money? You want to create organizations that have accounts named under the organization (instead of the owner of the organization)? Or do you want to let players save money in hardware (like chests) instead of software (like banks)?

1. Check if you need and have xEcon

You have to add xEcon to your plugin dependencies if your plugin won't work without xEcon. Example:

name: MoneyExample
depend: [xEcon] # You can add more dependency plugins in the format of an array too

In most cases, if you are not too lazy, you can make your plugin work safely with or without xEcon. If so, instead of depend, put it at softdepend.

If you use depend, your plugin will not load without xEcon loaded first. If you use softdepend, if xEcon is there it will get loaded first; otherwise your plugin will still load. Therefore, to check if xEcon is loaded and enabled, use this code (all example codes in this wiki assume that your code is at the main class extending PluginBase and will not specify the namespaces unless necessary):

$xEcon = $this->getServer()->getPluginManager()->getPlugin("xEcon");
$canUseXEcon = ($xEcon instanceof Plugin) and $xEcon->isEnabled();

If $canUseXEcon === true, you can do the code you want to do. Otherwise, errors will come out popping under your keyboard. Therefore, always remember to include your xEcon-related code inside an if-clause that checks if it is enabled, unless you use depend instead of softdepend. There are several cases where it is very hard to check, but you will know it when you come into them. :P

2. Transactions with a player

Now, assume you want to make an operation where Alice has to pay Bob $10. In real life, what do you have to do? Obviously, you have to find Alice and Bob themselves first.

In xEcon, there are objects responsible for managing economic accounts (a.k.a. economic entities, EconEnt for short in this wiki, which refer to anything, real or virtual, hard or soft, that can earn money, save money and spend money). This means, you will have to get an object $econEntity, and you will go through some operations with it by $econEntity->functionName().

Back to our case. A player called Alice is online on the server. Another player called Bob is online too. I don't know what your plugin wants to do; maybe Alice lost a gamble? We will leave this to your imagination. But anyway, you have to get the EconEnt of Alice and Bob. Here's how you do it:

$xEcon = $this->getServer()->getPluginManager()->getPlugin("xEcon");
// if necessary, do some checks for whether $xEcon is an instance of a plugin and whether it is enabled.
$aliceEconEnt = $xEcon->getPlayerEnt("alice"); // $xEcon->getSession($player) returns the session of the player used to work internally in xEcon. You can safely ignore this part (and possible changes in it) because this is not part of the API, but just a technical path in the plugin structure. $session->getEntity() will directly return the EconEnt from the session.
$bobEconEnt = $xEcon->getPlayerEnt("bob"); // same for Bob

Note that if the player is not online and there is no valid instance of the PlayerEnt object given by the object, a new instance will be created, so there is always an object returned by this function. However, if the player had never been registered with xEcon, it will not receive the default money given to every new player/IP.

At this place, you need to decide from what account should the players pay from and receive at. The two default accounts in xEcon are bank and cash, but other plugins (or yourself) may have added some other too. In the following example, we will make Alice pay $10 from her cash directly into the bank account of Bob.

Note: the following paragraphs are not important if you don't plan to let the player get things out of vacuum or lose things into nowhere. If you only want to know how to make a player pay another, skip to here.

Accounts are objects too. In xEcon, it is recommended that you always have a double entry. In economics, capital never disappears from the world (unless they burn the money). When someone (namely A) pays $10, maybe the other (B) only gets $9, but there must be a third person (C) who gets $1 (maybe got it because he helped them?). In accounting, we will break down this transaction into two transactions, of A paying $9 to B for the first transaction and A paying $1 to C for the second transaction. In this case, every transaction has an equal +/- on each side, and there are only two sides. This is the definition of double entry.

Back to the topic, you are strongly encouraged to have double entry every time a transaction occurs, since it would be easier for the server owner to keep track of things. Look at the following example for why it is good:

We have three players namely Cindy, David and Elvin. They are going to purchase at three shops, namely X, Y and Z today. After the end of today, if we look at the transaction records of Cindy, David and Elvin only, it would be hard to check what time of the day are there most players at shop X. Therefore, if we have an EconEnt named "Server" and each shop is an account of its, it will be much cleaner and easier to study these. This is one of the basic features of xEcon that make it different from others.

Transactions between accounts

Anyway, if you want to transfer money from one account to another, you have to get the account object first. A few paragraphs above, we have obtained the economic entity objects of Alice and Bob. Now, we have to get the bank account of Alice and the cash account of Bob.

As a matter of fact, after so much talk, it is just so simple to get the named account of a player. According to the constant PlayerEnt::ACCOUNT_CASH and PlayerEnt::ACCOUNT_BANK, we can obtain the accounts like this:

$aliceBank = $aliceEconEnt->getAccount(PlayerEnt::ACCOUNT_BANK);
$bobCash = $bobEconEnt->getAccount(PlayerEnt::ACCOUNT_CASH);

Now, we have two objects of class \xecon\account\Account. We have developed a convenient way for two accounts to transact:

$aliceBank->pay($bobCash, 10);

It just sounds so easy! Alice's bank pays Bob cash 10 dollars! Isn't that English?

3. Registering services

As mentioned in 2., it is a good idea to let a player pay the server instead of vapourizing the money. For how to register events, we will add this part of documentation later.

4. Defining new EconEnt classes

In xEcon, since xEcon works the same whether it knows you have a new EconEnt type or not, it is not necessary (and you won't find a function for that) to register your class to xEcon.

EconEnt classes are classes that extend/implement the \xecon\entity\Entity trait. (Therefore xEcon won't work below PHP 5.4 since traits are newly added) An EconEnt class must implement these methods:

• public function getAbsolutePrefix(); This function should return a group of words that can represent your plugin, while they must match the syntax of a correct filename. This value must be constant and must not contain the following token of characters continuously: @#@!%. This token is the magic token that separates the prefix (type of entity) and the entity name.
• public function getName(); This function's return value should also be constant. It is the identifier of that single entity in that entity class. For example, the player name is a unique value among all player EconEnts.
• public function sendMessage($msg); This function should send a message to a human/humans who is/are in charge of this EconEnt. For example, the player clients are in charge of their own client, the console is in charge of services and the highest-ranked official in a faction is in charge of that faction. (Yes, in PocketFactions, each Faction is an EconEnt.)

Warnings

• It is an easy mistake to confuse \pocketmine\entity\Entity and \xecon\entity\Entity. Use aliases (like use pocketmine\entity\Entity as PmEntity; and use xecon\entity\Entity as EconEnt;) to avoid this bug.
• Remember to disable your services when your plugin is unloaded. Otherwise, your plugin might not be approved on the PocketMine forums plugin repository.
• Remember that xEcon could be disabled in the middle of the server run. You must check if xEcon is enabled very time you work with it.