CoreCoins

CoreCoins by Ture Bentzin

Copied from Wiki Page - may not be up to date - Version 1.0-SNAPSHOT

The CoreCoinsAddon offers a clever way to manage multiple currencies and accounts on a Network. You don't need to take care of manual synchronization or data distribution. All required data management is performed automatically via the JuliGamesCore.

Installation

The Installation of CoreCoins is super intuitive and does not require any configuration or setup. The only thing you need to do is drag the JAR Archive into your plugins folder. Check out our Maven repository to get access to the suitable JAR File. For Velocity Servers you simply download the Velocity Jar and for Paper Servers the Paper Jar! If you need any assistance or encounter any issues with your installation then feel free to open an Issue here on GitHub or write me an email!

You need to run a Core on the Paper / Velocity Server you want to use CoreCoins on!

Creating and getting a Coin

First, you need to make sure that your code executes only if the CoreCoinsCore is ready. You can do this for example by adding depend. entries on Paper or Velocity. If you want to do that, then you can use the information below:

The next step is to make sure that you import the CoreCoinsAPI via Maven (or your desired way of dependency management)

<repository>
  <id>juligames-juligames</id>
  <name>Juligames Maven</name>
  <url>https://maven.juligames.net/juligames</url>
</repository>

<dependency>
  <groupId>net.juligames.core.addons.coins</groupId>
  <artifactId>CoreCoinsAPI</artifactId>
  <version>desired version</version>
</dependency>

Now you are ready to use the CoinsAPI and create your first Coin!

To create (or get one if already created) execute the following code:

        Coin coin = CoreCoinsAPI.get().getCoin("Your Coin Name", "Description for your Coin");

You can also use the shorter method without a description:

        Coin coin = CoreCoinsAPI.get().getCoin("Your Coin Name");

In the case that you created a Coin with a description and the same name earlier then the second method will provide you with a Coin that can provide this description to you! (So you don't need to enter the description every time you want to get your Coin)!

Creating an Account

The CoreCoinsAddon works with Accounts, these accounts have a name and an owner. So every Account can hold one amount of every currency and every owner could have unlimited accounts. It's on you to decide when you want to create accounts. In the future, it will be possible to also add users to accounts, but currently, this is not supported.

You can create Accounts more or less the same way you can create Coins:

        CoinsAccount coinsAccount = CoreCoinsAPI.get().getAccount("AccountName");

This code will get or create an account with the name "AccountName" - notice that every AccountName is unique and is used to identify the Accounts! In the case that you did not create the Account with the createAccount() method, this will return a new account without an owner (this might cause exceptions) It is suggested to create Accounts as follows:

        UUID uuid = UUID.randomUUID();
        CoinsAccount coinsAccount = CoreCoinsAPI.get().createAccount("AccountName",uuid);

In this case, I used a random UUID but you should use the UUID of your player. This player will be identified as the owner of this Account.

Adding or removing Currency from an Account

If you want to simply add or remove Currency to an Account or to change the amount manually and do not want to transfer Currency between two Accounts then you can use two methods from CoinsAccount:

Setting a new amount:

        coinsAccount.setAmount(coin,700);

Changing the amount based on what is currently the amount in the Account:

        coinsAccount.changeAmount(coin,integer -> integer - 1);

In this case, one of the given "coin" (Currency) would be removed. Make sure you know that you don't exceed the maximal Integer value: 2147483647 or to bring an Account below 0. In both cases it is very likely you will cause unwanted exceptions and issues!

Transfering Currency between two Accounts

If you want to move Currency between two accounts I suggest using the CoreCoinsAPI#transact() method. This will ensure that the money is moved and will help you prevent duplication glitches.

Here is an example of how to transfer 100 Coins of one currency from one Account to another:

       CoreCoinsAPI.get().transact(coin,coinsAccount,coinsAccount1,100,uuid);

The UUID you set as the last parameter is called "initiator" and can be used to store who (a player?) caused the transfer. You can read this value later. If no player caused the transaction, then enter null here!

If you want to know if the transaction was successful then you can use the CoinsTransaction that is returned by the CoreCoinsAPI#transactmethod:

        CoinTransaction transaction = CoreCoinsAPI.get().transact(coin, coinsAccount, coinsAccount1, 100, uuid);
        Date timestamp = transaction.timestamp();
        boolean successful = transaction.successful();
        Collection<TransactionException> failures = transaction.failures();

The CoinTransaction provides you with some additional information to the ones you entered into the transact() method. For example, you can read out the failures that caused this transaction to fail.

Exchange between coins

The whole exchange process is currently experimental and may be vulnerable to duplication! Please report any issues here on GitHub!

If you want to change between two currencies it is suggested to use the CoinExchanger. The API provides you with a simple factor-based StaticCoinExchanger that changes money based on a set exchange rate.

        StaticCoinExchanger exchanger = CoreCoinsAPI.get().getExchanger(coin, coin1, 1.5);
        exchanger.exchange(coinsAccount,300);

This code will exchange 300 of "coin" to 1.5*300 = 450of "coin1"!

You can receive a Pair of two Transactions out of the exchange() method. These two CoinTransactions resemble the withdrawal and ingress from and to the account used in the exchange.

You can access them this way:

        Pair<CoinTransaction> exchange = exchanger.exchange(coinsAccount, 300);
        CoinTransaction first = exchange.getFirst();
        CoinTransaction second = exchange.getSecond();

You can also implement your own Exchanger with the CoinExchanger interface or with the ´SimpleCoinExchanger` abstract class. The Interface allows you to develop your completely custom exchange algorithm, the abstract class allows you to build your custom rate-based exchanger!

Aditional Features

The API provides you of course lot of methods that are not discussed here like listing Accounts and Coins:

        Collection<CoinsAccount> allAccounts = CoreCoinsAPI.get().getAllAccounts();
        Collection<Coin> allCoins = CoreCoinsAPI.get().getAllCoins();
        Collection<Coin> allCoinsStartingWithA = CoreCoinsAPI.get().getAllCoins(c -> c.getName().startsWith("a"));
        Collection<CoinsAccount> allAccountsOwnedByUUID = CoreCoinsAPI.get().getAllAccounts(a -> a.getOwner().equals(uuid));

I suggest just exploring the features of the CoreCoinsAddon a bit! And don't forget if you encounter any issues, bugs, or problems you can always open an Issue or contact me via my email!