Currency

The currency module implements currencies as a series of transactions, logged in a “pool” where the history is stored.

Every currency must be defined as having a “base coin”. The currency module deals exclusively in “whole number” (Integers) and the base coin represents the indivisible unit. For example, the United States Dollar, sometimes just known as the Dollar, has a “base coin” of a cent ; it is cents that can not be split any further with the dollar being made up of 100 of these.

In GPHUD the base coin must be specified, and additionally coins can be defined as being worth so many of the base coin ; e.g. for Dollars we would define these as being valued as 100 cents. For a traditional D&D style campaign the base coin would be copper, with silver being set as 100 copper and gold being set at 10000 copper.

The current currency module uses a signed 32 bit integer for storing the values, thus the maximum currency a character may hold is 2,147,483,647 of the base coin (copper, cents, etc) (2.1 billion cents ; aka 21 million dollars, or 2.1 billion copper, aka 210 million silver, aka 2.1 million gold). If you have a pressing need for a broader economy, please let me know (with advance notice!)

Currencies are expressed as their base coins and other defined coins, each coin has a short name and a long name, and you are encouraged to keep these unique within the currency system.

For example, the US Dollar would be a Currency attribute named Dollars, with a base coin long name of cents and a short name of c, with one coin, the Dollar (long name) or $ (short name) worth 100 of these. As such values such as 12345 would be displayed as “123$ 45c” in short format or “123 dollars 45 cents” in long format.

Similarly defining a Currency called Gold with a base coin of copper/c, a coin of 100 copper called silver/s and 10000 copper being gold/s, then 12345 becomes “1g 23s 45c” in short form or “1 gold 23 silver 45 copper” in long format.

Currencies are created (and destroyed) through the Configuration/Characters page, they are added as an attribute of type “CURRENCY”, which will only appear if/once the Currency module is enabled. Deleting a currency is a permanent action that will obliterate all users currency of that type. The “Default” value can be used to specify a starting balance, which will be awarded to any players, on login, who have zero transactions for that currency (this will become their first transaction). Note that in some bizzare circumstances a user might receive currency before their initial allowance meaning it would not trigger due to having a transaction. The character's transaction history can be reviewed on their character page.

Administratively, coins can be awarded or removed (called 'created' and 'destroyed' as the currency comes from, or goes to, nowhere), which require an administrative permission

Currencies can further be managed via the Configuration/Currency page, where the names of the base coins may be changed, and coins added/removed (e.g. 1 silver = 100 copper). Note that adding or removing coins will not change anyone's balance - internally they are stored as numbers of “base coins” and are simply converted to more human-friendly forms by the definition of coins. E.g. a user with 10 silver 3 copper actually has 1003 “base coins” (copper). If the silver threshold was then changed to be 1 silver = 100 copper, the player's new balance would be 1 silver 3 copper, which has the same overall “base value”.

A currency can be marked as tradable or not tradable to decide if a character is allowed to give their currency to another user. In most cases, and the default, this would be enabled, however for some special currencies this might not be desirable.

There are also KVs for configuring taxation, which can be modified at various levels (instance, region, zone, character, group, etc).

This is something I spent a while pouring over. I'm prepared to consider adding additional or alternative taxation models, however, please note that in the future there is likely to be “Locations”, i.e. the concept of “on-person” currency as well as currency stored safely in a bank. I considered how to best apply taxation to ammounts stored however it becomes difficult to manage what this means when a character pulls out all their currency moments before the “daily tax calculations” as a tax dodge. Tax could be applied at a finer grained level, however negative balances are possible if tax is applied on a set schedule. Instead a trasaction tax is currently the preferred model, with future “locations” support allowing money to be taxed on entry/exit transfer from a storage vault.

So. Currently (if not set to zero) a TransactionTax is applied to currency /received/, e.g. if this is set to 10% and I send you 100 coins, you will receive 90 coins with 10 removed as the taxation. There are two commands for transferring money, Currency.Transfer<name> which deducts the tax from the ammount the target receives, and Currency.TransferPayTax<name> which causes the sender to pay extra to cover the taxation costs. Such things will be noted in the character's currency log (pool view).

There is also a KV which can be set to determine where taxes go ; if not set or left blank, taxed money is simply “destroyed” and lost from the economy, however if the appropriate KV is set to a character then tax will be credited to that account instead and there will be zero net change in the overall economic state.

Currency is always difficult to balance - see any online MMORPG where currency tends to devalue over time and costs inflate relatively, if there is more money coming into your economy than leaving then this is likely to happen. Note that a common MMORPG is to 'restart' the economy during an expansion by changing the values of everything - e.g. if selling trash loot nets you mere silvers in the original game, by changing this to netting you hundreds of silvers in the expansion then all existing hordes of cash are going to become (over time) less valuable as even more money pumps into the economy.

Remember there is a limit on the ammount of currency a player can hold, so inflating the economy is not a repeatable solution. If you consider that you might reach the limit of the currency please get in contact as soon as possible so the data type size can be expanded if necessary to a 64 bit number (this requires some work as it's baked into the tables for Pools currently).

Taxation allows you to remove money from the economy as it is used, and can somewhat be a counter to inflation, however, this is not an easy thing to balance and success in online games has been “limited”.

A couple of new functions exist for querying a balance and converting to and from “human” forms of expression (e.g. 1 gold 5 silver rather than 10005 base currency units)