global_exchange/README.md

#Global Exchange

This mod provides a server-wide trading exchange for items. It is available under GNU GPL version 3 or any later version. lsqlite3 is required by this mod, and can be installed through luarocks. ($ sudo luarocks install lsqlite3)

Nodes

• ATM (global_exchange:atm) - Used by players to withdraw and deposit minegeld bills, transfer money to other players, and to view the history of transactions.
• Exchange (global_exchange:exchange) - Used by players to search and post orders, and to view a summary of current market prices.
• Digital Mailbox (global_exchange:mailbox) - Used by players to claim items sent to buy orders.

Using the Exchange

Main Screen

The first screen you see is where you can search and post new buy/sell orders. Here is an overview of each element:

• Market Summary - Pressing this will take you to the market summary screen.
• Your Orders - This will take you to a screen where you can view and cancel your existing orders.
• Item - This field is for entering the item name (e.g. default:cobble) of the item you want to search or post an order for.
• Amount - This field is for entering how many of the item you want to buy/sell when posting an order. It has no purpose in searches.
• Select Item - This button takes you to a screen for choosing your item graphically, instead of manually typing an item name.
• Rate - This field is for entering the desired price per item when posting an order. For buy orders, this is the maximum price - your order will also accept items that are cheaper. For sell orders, this is the minimum price - your order will also accept buyers that are willing to pay more. The Rate field has no effect on searches
• Search - This button searches existing orders for the selected item. If you have the "Sell" box checked, it will only display buy orders, and will display them in descending rate. If you have the box unchecked, it will show sell orders in order of ascending rate.
• Post Order - This posts a new order for the item with the given amount and rate. If the "Sell" box is checked, this is a sell order, so the exchange will remove the items from your inventory. If it's unchecked, you are making a buy order, so it will deduct credits from your account. If there are already matching orders, it will immediately fill your order up to the amount possible, and the remainder will stay as a new order.
• Sell - This checkbox determines what kind of orders to search for, and also what kind of order you are posting.
• Search Results - This will display the results of your search. Clicking on an element here will automatically fill the "Amount" and "Rate" fields, so that if you click "Post Order", it will match the order you clicked.

Market Summary

This summarizes the various items available on the exchange. From left to right, the columns display the item name, the description (what is shown in inventory), the amount requested by buyers, the maximum rate offered by buyers, the amount offered by sellers, and the minimum rate offered by sellers. It is updated periodically.

Your Orders

This screen lets you see and cancel your orders. To cancel an order, click the order and press the "Cancel" button.

Select Item

This displays a creative-style inventory menu for selecting an item for searches or posting orders. To select an item, drag it from the inventory to the box near the bottom of the form

Buying/Selling

Once you have opened the exchange, you have a few options. If you don't already know what you want to buy or sell, you can look at the Market Summary to get a glance at what people are offering. After you have decided on what you are going to do, return to the exchange page.

If you are selling an item, you should check the "Sell" checkbox. Otherwise, leave it unchecked. Next, you need to select the item you want to deal in. There are two ways: typing the item name (e.g. default:cobble) in manually to the item field, or using the "Select Item" menu. If you haven't already decided on a price, or you want to make sure your order is filled quickly, you can conduct a search. To do this, click the "Search" button. This will give you a list of results. If you checked the "Sell" box, then these will be buy orders, and will show the maximum price per item each buyer is willing to accept. Otherwise, these will be sell orders, displaying the minimum price each seller will accept. If you click on a search result, it will automatically fill your Amount and Rate fields to match.

The Amount and Rate fields are used to decide how much and how expensively you want to make your order. When selling, the Rate field is the minimum price you will accept. When buying, it is the maximum. Once everything is filled out how you want it, press the "Post Order" button. If there are matching offers (when you post a buy/sell offer, there are one or more sell/buy offers with a price at least as good), then that part of your offer will immediately be filled. For example, if you post a buy order for 10 cobblestone at 5 credits each, and there is a sell offer for 5 cobblestone 3 credits each, it will give you 5 cobble immediately, and leave an order on the exchange for 5 more cobblestone.

Once your offer is on the exchange, you can view or cancel it from the "Your Orders" menu.