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](https://github.com/JuliGames/JuliGamesCore/wiki). ## 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](https://maven.juligames.net/#/juligames/net/juligames/core/addons/coins) 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](mailto://[email protected])! _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: | Platform | Value | Example Entry | |----------|-------------------|---------------------------------------------------------------------| | Paper | PaperCoinsCore | ```depend: - PaperCoinsCore ``` | | Velocity | velocitycoinscore | ```dependencies = @Dependency (id = "velocitycoinscore") ``` | The next step is to make sure that you import the CoreCoinsAPI via Maven (or your desired way of dependency management) ```xml juligames-juligames Juligames Maven https://maven.juligames.net/juligames ``` ```xml net.juligames.core.addons.coins CoreCoinsAPI desired version ``` 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: ```java Coin coin = CoreCoinsAPI.get().getCoin("Your Coin Name", "Description for your Coin"); ``` You can also use the shorter method without a description: ```java 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: ```java 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: ```java 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: ```java coinsAccount.setAmount(coin,700); ``` Changing the amount based on what is currently the amount in the Account: ```java 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: ```java 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#transact`method: ```java CoinTransaction transaction = CoreCoinsAPI.get().transact(coin, coinsAccount, coinsAccount1, 100, uuid); Date timestamp = transaction.timestamp(); boolean successful = transaction.successful(); Collection 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. ```java StaticCoinExchanger exchanger = CoreCoinsAPI.get().getExchanger(coin, coin1, 1.5); exchanger.exchange(coinsAccount,300); ``` This code will exchange 300 of "coin" to `1.5*300 = 450`of "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: ```java Pair 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: ```java Collection allAccounts = CoreCoinsAPI.get().getAllAccounts(); Collection allCoins = CoreCoinsAPI.get().getAllCoins(); Collection allCoinsStartingWithA = CoreCoinsAPI.get().getAllCoins(c -> c.getName().startsWith("a")); Collection 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](mailto://[email protected])!