DynamicMarket - Dynamic Global Shop Plugin Version: 0.4.8 Built against: Bukkit 0.0.1 build #412 Works with: CraftBukkit 0.0.1 builds #440-480 or thereabouts. Requires: Permissions 2.5 Very recommended, but now optional! See "DynamicMarket.settings" below. iConomy 4.1 Either of: SQLite (easiest to set up, reccomended) MySQL (more troublesome, more powerful) Buy items, sell items, admins set prices, et cetera. However, there's a lot going on under the hood... READ THIS BEFORE PROCEEDING. Seriously. (Move your mouse to reveal the content) Seriously. (open) Seriously. (close) This plugin has a great deal of flexibility, but the price of more flexibility is more command options to control that flexibility. Computers just aren't very psychic. While in-game help exists for commands, the output from /shop help (<topic>) is intended to be a quick reference, not exhaustive documentation. Full instructions simply won't fit on the MineCraft client's tiny text display. You should read and understand the following sections before installing this plugin and setting up your shop. If not, you should at least read and understand the following sections while you are setting up your shop items. The big feature: Dynamic pricing. Items can be set to increase in price as they are purchased from the shop, and decrease in price as they are sold back, simulating open market conditions. The initial prices of items are just considered a starting point - user transactions will eventually adjust an item's price to a near-ideal level, based on actual value vs. rarity. However, as of 0.4.5, the configuration fields are now flexible enough to allow a range of behaviours, from fixed pricing with no stock limits, to fully-dynamic pricing with finite stock levels. This is by no means "complete" in the sense of "finished adding features", but it is complete enough to be functional and usable. Current Features (Move your mouse to reveal the content) Current Features (open) Current Features (close) New & Current Features: Buying and selling of items: Item prices can be set to dynamically adjust according to supply and demand. This is highly adjustable, including the rate of price increase/decrease per transaction, optional hard overstock/understock limits, price ceilings/floors, etc. Leaving all the extra features turned off makes an item's price fixed and always-in-stock, like a basic "flat rate" shop. Subtypes of items are fully supported. List of items in the shop is broken into pages, accessible by number. Partial-name searching! "/shop list wood" shows everything with "wood" in the name. Item names for buy/sell/info also use partial substring matches. A dynamically-priced item might cost more for 10 items than the cost of 1 item multiplied by 10, due to stock depletion. So, the "/shop <id>" command now takes an optional ":<count>" parameter, so you can get a quote for the actual buy/sell price of larger numbers of items. Administration: Shop items are edited via a "tag" system, so you don't have to re-enter every field for each small change. Plus there's a few utility tags which do other things to an item's record... Item names are now editable, and will persist (independent of items.db) until the item's record is deleted. This also makes items.db a convenience instead of a necessity, since items can be added by ID and then immediately renamed. A "Default" item exists in the shop, which cannot be bought or sold, but serves as the base data for any new items you add to the shop. Any tags not supplied when you add an item will be copied from whatever you put into "Default". Basic sanity-checking on input data has been added. Also, adjusting an item's bundle-size will rescale its price automatically. Items can be set to be purchasable but not sellable, or vice versa. (Set either price to -1 to disable that transaction type for that item.) Tags like "canbuy:n" and "nosell" can now be used. An extended in-game help system. "/shop help" lists available commands and help topics. "/shop help <topic>" gives help on a shop command or other shop-related topic listed in the main help. The list of commands displayed is filtered by the user's current permission level. Shortcuts for all commands (except for database reset). All commands except for "/shop buy" and "/shop sell" can be accessed through the Bukkit console. No need to log in to add or update items! Access to the entire shop is now restrictable by permission. Highly informative error messages, to help reveal why your database exploded. (Which really shouldn't happen, but you never know...) The shop DB can now be exported to a .csv file, edited in your favorite spreadsheet, and re-imported back into the database, making large-scale changes easier. NEW: The revenue/cost of transactions can now be transferred to another account. With the basic plugin, this can be an admin's iConomy account, or a dummy "GovernmentBank" account. (Don't use that name, or some bright spark will register that username and exploit you.) With a wrapper plugin, this can be set to link a shop's funds directly to an owning player's iConomy balance. NEW: Transaction logging to a comma-delimited file, ready to import into a spreadsheet for nefarious financial analysis! Market Mechanics (Move your mouse to reveal the content) Market Mechanics (open) Market Mechanics (close) Quick Market Mechanics Description: Instead of a "buy price" and a "sell price", items now have a "base price" and a "sales tax". The "buy price" is based on the base price (adjusted by stock, if set to do so), and the "sell price" is based on (<buy price> - <sales tax%>). So if the sales tax is set to 25, then an item's selling price will be 75% of its purchase price. (The sales tax is entered as a number from 0 to 100, representing 0% to 100% tax.) Using the old "/shop add <id> <buyprice> <sellprice>" format still works - the plugin just calculates the base price and sales tax, so that the buying and selling prices come out right. Shop items have a "stock level", which is not necessarily a literal count of items in stock. By default, the stock level is considered an offset from baseline, rather than an absolute count. Items with stock near zero are considered to be in "average" supply, and will be priced at their base price. Items with a positive stock are considered "in surplus", and will be priced below their base price. Items with a negative stock are considered "understocked", and will be priced above their base price. This interpretation of stock levels can be made to behave like literal counted stock, by setting an item's StockFloor to zero, which prohibits negative stock. Items have a "volatility", which indicates how quickly the price changes based on changes in stock level. It represents the percent increase in an item's price per item purchased, multiplied by 10000. V=1 (the lowest level) means that 100 items would have to be purchased to raise the price by 1%. V=10000 (the highest level) means that 1 item purchased would raise the price by 100% (doubling the price). (More examples in tags.txt) There is also "inverse volatility", which represents the number of items needed to be bought in order to double the buying price (or halve it, if selling). This is more convenient for some people's mindsets, and is converted into volatility when entered. The "sell price" is actually calculated from the buy price at the current stock level + 1, rather than the current stock level. This is to prevent gaining endless money by buying an item (driving the price up) then immediately selling it back (dropping the price) - if <sales tax> = 0, then buying-then-selling like this produces zero net gain/loss (as it should). The tag presets "fixed", "float", "finite", and "flat" allow you to quickly set up common options. If used with the "Default" item before adding items to your shop, this will allow you to set the overall behaviour of the shop easily. See Tag Reference for further details. Commands (Move your mouse to reveal the content) Commands (open) Commands (close) Commands: <Angle Brackets> denote parameters. (Round Brackets) denote optional sections. The brackets themselves are not part of the command; they are just used to describe syntax. Brackets should not be typed. If executing shop commands through the Bukkit console, leave off the initial slash. /shop - Shows the main help page. Lists commands and shortcuts. /shop help - Ditto. /shop help <topic> - Shows help on the given command or subject. /shop help tag <tagName> - Shows help on the given item tag. /shop <id>( :<count>) - Shows current buy/sell information on the given item. <id> can be an item name or a type number with an optional subtype: <id> = <itemName> | <itemID> | <itemID>,<subtypeID> | DefaultIf <count> is used, shows the total price for the given number of items/bundles./shop list (<partname>) (<pageNum>) - Lists a page of items in the shop. Default page = 1. If <partname> is used, lists only items with <partname> as part of their name./shop buy <id>( :<quantity>) - Purchases an item. Default quantity is 1 bundle. /shop sell <id>( :<quantity>) - Sells an item. Default quantity is 1 bundle. /shop add <id>( :<bundleSize>) (<buyPrice> (<sellPrice>)) <tagList> - Adds an item to the shop list. <buyPrice> and <sellPrice> are accepted for convenience, and are internally converted to BasePrice and SalesTax.Unused tags will have their data copied from the Default item.Transactions will be in multiples of <bundleSize>. Default quantity is 1 item per bundle (unless overriden with the Default record)/shop info <id> - Shows much more detailed information about an item in the shop, such as stock level, volatility, etc. /shop update <id>( :<bundleSize>) (<buyPrice> (<sellPrice>)) <tagList> - Edits an item's shop data record. Data is first copied from the old record, then tags are applied in order of entry.NEW! <id> can be "all", applying changes to all items in the shop list./shop remove <id>- Removes an item from the shop list. /shop reload - Reboots the plugin, reloading the configuration file and items.db. /shop reset - Deletes and recreates the shop database from scratch. Asks for an extra confirmation before doing so. /shop exportdb - Exports the shop database to a .csv file. The name and location are configured in SimpleMarket.settings. (Default: Plugins/DynamicMarket/shopDB.csv) /shop importdb - Imports a .csv file into the shop database. Same file location as used by the exportdb command. Note that the previous contents of the database are NOT cleared out before importing, so you may want to do a "/shop reset" before importing. The file's format MUST match the format of the exported file (except for quote marks, which are stripped out on import). Tag Reference Tag Usage Examples Permissions (Move your mouse to reveal the content) Permissions (open) Permissions (close) Permissions: 'dynamicmarket.access' : Grants basic access to the root /shop command. 'dynamicmarket.buy' : Grants purchase rights. 'dynamicmarket.sell' : Grants selling rights. 'dynamicmarket.items.add' : Grants the ability to add new items to the shop. 'dynamicmarket.items.update' : Grants the ability to edit items in the shop. 'dynamicmarket.items.remove' : Grants the ability to remove items from the shop. 'dynamicmarket.admin' : Grants the ability to delete-and-rebuild the shop database, and to reboot the plugin. Installation/Setup (Move your mouse to reveal the content) Installation/Setup (open) Installation/Setup (close) Installation/Setup: If you haven't already done so, install Permissions and iConomy, and ensure they work. Copy DynamicMarket.jar into your Plugins/ folder. NEW: Copy items.db into Plugins/DynamicMarket/ (or whichever directory you specify in DynamicMarket.settings) (DynamicMarket will work with other plugins' items.db files, but not all plugins will handle the extra subtype data in the items.db linked below.) NEW: Copy either the SQLite connector or the MySQL connector into your main MineServer/Bukkit folder. Or, if you have a MySQL server running, edit DynamicMarket.settings to specify the MySQL server, login, and password. Edit plugins/Permissions/config.yml, and give everybody the appropriate permissions. Most users would get 'dynamicmarket.access', 'dynamicmarket.buy', and 'dynamicmarket.sell', unless you want to restrict such commands to registered/VIP users. Mods would probably get 'dynamicmarket.items.*' Admins should get 'dynamicmarket.admin', if they don't already have '*'. (Re)Start your MineCraft server. Errors may be thrown to the console, but the file Plugins/DynamicMarket/DynamicMarket.settings should be created. Edit DynamicMarket.settings. Particularly, the setting "database-type". "database-type=sqlite" : Use the SQLite connector. This is the simpler option. No further database access configuration should be needed. "database-type=mysql" : Use the MySQL connector. You will need to set the options "mysql-user", "mysql-pass", and "mysql-db", as well as having a working MySQL server installation set up already. NEW: Log in to MineCraft as someone with 'simpleMarket.admin' permission, or use the Bukkit console. Use "/shop reload" to load the edited config file. Use /shop add to fill the market with tasty blocks at scandalous prices. You WILL want to use "/shop update default" to set up some sensible default values for the items you will be adding, so you don't have to do so much typing for every item. (Or at least inspect the Default entry, to be sure you agree with it.) If you want to make all of the items in the shop use dynamic pricing, set up the parameters in the Default item FIRST, so you don't have to go back and modify 100+ items to support variable pricing. DynamicMarket.settings Reference Downloads: DynamicMarket 0.4.8.1 (.jar) (.7z) (iConomy 4.1, Permissions 2.5) DynamicMarket 0.4.8 (.jar) (.7z) (iConomy 3.0, Permissions 2.1) DynamicMarket 0.4.6.1 (.jar) (.7z) (iConomy 2.1 / Cookies+iConomy Wrapper) DynamicMarket Source on GitHub items.db <-- Contains subtypes. Put this in /Plugins/DynamicMarket/. SQLite Connector (reccomended) Put this in your MineCraft server/Bukkit root. MySQL Installation Guide (not so easy, probably not recommended for SQL server beginners) Sample shopDB.csv Many (but not all) items, set up for floating-stock+floating-prices. Edit it if you like, then put this in your Plugins/DynamicMarket folder and use /shop importdb to load the items into your shop. DynamicMarket Wrapper Plugins: DMWrapper: Restricts shop access to specific regions. Outdated. Want to integrate DynamicMarket's shop functions into your own plugin? Read this! To Do List(s) (Move your mouse to reveal the content) To Do List(s) (open) To Do List(s) (close) To Do for v.0.5: Logging of transactions. Done. Global messages to alert to price changes. Item classes: Use Permissions to control access to certain types of items, i.e. make safe items (gravel, stone, iron) available to anyone, but limit traffic in dangerous items (TNT, lava buckets, monster spawners) to VIPs. (For example.) Customizable interface/highlight colours. Done. Clean up the d*** out-of-date comments in the code. (Working on it.) To Do before 1.0: Optional auto-transactions triggered by price disparities in raw/processed materials. Possible migration of the new help system to a separate plugin, unless the expanded features needed become available in MCDocs or Bukkit. Migrate config file handler to Yaml. Random fluctuations of stock levels (would make the market more lively on a low-population server) Stock levels drift back to rolling averages (smoothes out short-term price spikes, allows for long-term price drifting) Recent Changes: 0.4.8.1: Migrated to Permissions 2.5, iConomy 4.1. 0.4.8: shopLabel moved from a table name suffix to a table field. Using "all" as the item name now applies the given tags to all items with the current shopLabel. Altering an item's bundleSize now changes its stock level, as well as its basePrice. New stock level is rounded down, to stave off future item duplication issues. Sanity-check behaviour changed to make database queries more efficient and fend off future exploits: stockHighest/stockLowest set to stock if lower/higher than stock. stockCeil/stockFloor is set to stockFloor if lower/higher than stock. priceCeil is raised to priceFloor if priceCeil<priceFloor. Previous behaviours: Swap if order wrong, range-crop stock if outside highest/lowest/floor/ceil. Fixed bug: Adding items without specifying count did not import count from default record. 0.4.7: Upgraded to iConomy 3.0. 0.4.6.1: Rolled back iConomy calls to 2.x style, to be compatible with Cookies' iConomy wrapper. 0.4.6: Support for transaction funds to be backed by an iConomy account. Account link parameters added to wrapper-call messages. Wrapper calls streamlined. Added basic transaction logging. 0.4.5: Volatility can now go as low as 0. In this way, stock can still be counted without affecting price. CSV import/export now uses +INF / -INF as shorthand for min/max values in applicable fields. Message colours now customizable in DynamicMarket.settings. Expanded help on tags/presets. Changed "fixed" tag, splitting its function with "flat". Added tag presets "flat" and "finite". Updated tag "renorm" to accept an optional new stock level other than 0. Full Changelog Credits: Nijikokun: SimpleShop v.1.1, on which this was based. (And for Permissions and iConomy, on which this relies.) AtomicAcidBath: Assistance with tracking down a hard-to-see MySQL syntax error.