Pages

Main - Backup

This page is going to be changed, currently we are working on a Wiki page

Incoming update v1.9! See changes

Introduction

CitizensTrader is a character plugin for Citizens 2.0 Beta.

You should be able to use it without much problem but as it is still a work in progress I cannot give any guarantees. Use at your own risk.

Features

  1. User friendly - you don't need to use commands to buy/sell items.
  2. Admin friendly - you also don't need commands to setup available goods.
  3. Customizable - NPCs can be as complex as you choose. From simple vendors to traders offering items in multiple stack sizes, limits in their inventory, and advanced economy options.
  4. Transaction logging - for when your players insist they 'accidentaly' sold that stack of diamonds.

Installation

Dependencies:

  1. Citizens 2.0
  2. Vault
  3. economy plugin

Note: When using permissions keep in mind that only plugins using SuperPerms are supported.

Commands

- [] - optional argument - <> - required argument

How to view a list of available items

Use the following command to check what a trader has in his stock: 

/trader sell list [page]

And to view a list of items he will accept: 

/trader buy list [page]

Note: Commands will be executed on the currently selected NPC.

Trader ownership

To check the current owner use:

/trader owner [new_owner]

Supplying the argument sets the owner to the specified player.

Creating traders - the easy way

You can create a trader by simply using:

/trader create <name> [t:type] [w:wallet] [e:entity]
  • "w:" defines the wallet type
  • "t:" defines the trader type
  • "e:" defines the entity type

Supported wallet types: - infinite/bank/npc-wallet/owner-wallet

see the NPC Wallet section for explanation

Supported trader types: - server/player/player-banker

see the Trader types section for explanation

Supported entity types (superperms side support): - pig/wolf/sheep/blaze/zombie/skeleton

Note: You can't use whitespaces in the name of the npc by using this method. A fix is on the way.

The trader name is created by adding anny argument that has not a "w:", "t:" or "e:" on the begining so 

/trader create My t:player Npc

will create an trader with the name "My Npc" with the trader type "player"

so it doesn't matters where you put the traders name :)

Creating traders

To create a trader use the following command:

/npc create "displayed name" --char trader

Alternatively, if the npc already exists you can just select it, and convert it using: 

/trait trader

By default you are in the user mode. To be able to modify the trader you have to switch to manager mode by right clicking the npc with a stick (item id: 280)

NPC Wallet

Wallets are a way to make the merchants seem more realistic by giving them a predefined amount of money to trade with. It also allows you better control over your server economy. In addition they are the only way players can manage account balance of the traders they created themselves.

Four wallet types are currently supported:

  • infinite (admin only) - The trader has limitless money
  • bank - Hooks the trader to the specified bank account. You must be a bank member/owner to use this feature.
  • npc-wallet - The trader has his own separate wallet and can't buy items unless he can afford it.
  • owner-wallet - Allows the trader to directly use his owner's in-game money. Any transactions performed by the trader will affect that player's balance.

To set the wallet type use: 

/trader wallet [walet-type] [bank-name]

When no arguments are supplied it shows the current wallet type

To manage a trader with the npc-wallet wallet type use the following commands: 

/trader balance
/trader withdraw <amount>
/trader deposit <amount>

Note: Commands will be executed on the currently selected NPC.

Trader types

To set the type use:

/trader type [type]

When no arguments are supplied it shows the current trader type

server - admin shop player - trader belonging to a player player-bank - an npc allowing to display the players bank account money-bank - a npc that allows to show the players money in a choosen item, and manage the amount in adding/removing items from the bank (money <=> item)

Using the trader

1. With an empty hand right click the NPC

2. To toggle between buying/selling click the lime/cyan wool in the lower right corner.

3. Buy menu

  • Clicking once on an item shows the price or brings up the amount selection menu.
  • Clicking the item a second time buys it.

4. When in the amount selection menu you can click the red wool to go back to the trader's main inventory.

5. Sell menu

  • Clicking once on an item shows how much you will get for it.
  • Clicking the item a second time sells it.

Note: NPCs will not buy anything unless you set up the accepted items and their prices.

Inventory management (Server trader)

1. Be sure to enable the manager mode first, then open the trader's inventory.

2. Options:

  1. To add an item drag and drop it from your inventory
  2. To remove an item drag and drop it to your inventory
  3. You can move added items around to set their desired slot
  4. right clicking with an 'empty' cursor changes between applying the price to the whole stack (so it becomes the final price) or a single item (final price = price * number of items in the stack)
  5. To set item prices click the black wool (it should change it's color to white)
    1. change in the price value is dependent on:
    2. item used
      1. wood counts as * 0.01
      2. log counts as * 0.1
      3. dirt counts as * 10
      4. cobblestone counts as * 100
      5. items not listed above count as * 1
    3. type of interaction
      1. right click decreases the price
      2. left click increases the price
    4. Examples:
      1. A single click with a block of drit increases the price by 10
      2. Ten clicks with a block of soul sand increase the price by 10
      3. One right click with 10 blocks of dirt deacreases the price by 100
    5. Note:
      1. you can't change the price using 'empty' cursor
      2. using AIR will show the current price
      3. to exit the price editing mode click on the white wool
  6. To set up the amount selection menu shift click the item
    1. using this function you can set multiple stack sizes that the player will be allowed to buy
    2. when editing available sizes you are only able to add items with the same id/data as the item that opens the menu
    3. set values are saved by returning to the trader's main inventory (red wool) or exiting the window
    4. Note:
      1. Amount selection menu won't work if you enable the stack price option
  7. To place limits on the number of offered items click the blue wool (it should change it's color to /?/)
    1. right click lowers the limit
    2. left click raises the limit
    3. shift right click decreases the time it takes for the limit to reset back to its original value
    4. shift left click increases the time it takes for the limit to reset back to its original value

Note: Only the global limits are working at this time, player limits will be added soon(tm).

Inventory management (Player trader)

"Player trader" inventory management is a little different than "server trader", but I hope it's still easy to understand :)

Sell tab management

  1. To add an item, you need to l.click it in you'r inventory, and it will apprear in the traders inventory (it's not duped)
  2. to remove an item shift l.click it in the traders inventory,
  • (it will dissapear and return back all item's you have given the trader for sell)

after adding an item in the inventory it can be named a "ghost" item, cose people can't buy from it and it's only there to show that this trader sells that item it's like a template

to add items to sell you need to shift r.click the whole stack will dissapear and it will be transfered to the trader stock, allowing others to buy that amount you've transeferd to the trader

to set prices it's the same way like teh "server trader"

  1. To set item prices click the black wool (it should change it's color to white)
    1. change in the price value is dependent on:
    2. item used
      1. wood counts as * 0.01
      2. log counts as * 0.1
      3. dirt counts as * 10
      4. cobblestone counts as * 100
      5. items not listed above count as * 1
    3. type of interaction
      1. right click decreases the price
      2. left click increases the price
    4. Examples:
      1. A single click with a block of drit increases the price by 10
      2. Ten clicks with a block of soul sand increase the price by 10
      3. One right click with 10 blocks of dirt deacreases the price by 100
    5. Note:
      1. you can't change the price using 'empty' cursor
      2. using AIR will show the current price
      3. to exit the price editing mode click on the black wool

Buy tab management

So all steps are the same like in the sell tab just the system how we define how many items wewan't to buy is a little differen

So in this tab we got a brown wool for "Buy limits" so we can limit how many items we wan't to buy.

It's all the same like in the "server traders" Limit management, with that change that you start here with a "0" limit, so no1 can sell to this trader anything. If you set the amount to -1 ppl can sell items to the trader until, he doesn't has enough gold to trader with.

!NOTE! Limit 0 means, "nothing I wan't to buy"

!NOTE! Limit -1 means, "I will buy any amount"

  1. To place limits on the number of offered items click the brown wool (it should change it's color to white)
    1. right click lowers the limit
    2. left click raises the limit

to get items the trader has in stock you just shift r.click the item and he give you the items (without deleting the item in the stock)

Multiple amounts management Coming in version 1.8.0!

To set multiple choice amounts for a player traders, it's similar to the price management, but instead of the prices we are increasing/decreasing the amounts

to open the "Amount management" shift r.click the item you want to set

after that it will appear an empty inventory with only 1 item, it's the base amount to but, and also teh displayed amount when you'r opening a trader.

to add an amount just click on in the inventory in any place, so there will appear a new item with.

  1. l.click will increase it's amount (if you got anyitem in you'r hand it will increase this amount by the items amount)
  2. r.click will decrease it's amount or if amoutn reaches 0 delete it (if you got anyitem in you'r hand it will decrease this amount by the items amount)

Localisation support

Basic message support is complete. You can fully customize them to suit your needs.

Dynamic messages were added. You can use keywords like {price} to display the cost of the item. Full list of available keywords will be added at a later date.

I'm looking for people who can translate plugin messages from english to another language. Contact me if you are willing to help.

Permissions

  • dtl.trader.* - all permissions (default: op)
  • dtl.trader.user.default - default permissions to use traders (default: all)
  • dtl.trader.user.manager - default permissions for managing player traders (default: op)
  • dtl.trader.bypass.* - bypass permissions (default: op)
  • dtl.trader.bypass.drop-item - allows to drop items when clicking outside the inventory
  • dtl.trader.bypass.creative: - allows to bypass the creative restriction when managing/using a trader
  • dtl.trader.options.manager-mode-bypass - allows to manage any trader
  • dtl.trader.options.* - options which needs to be allowed to use centrain features when using a trader or command (default: op)
  • dtl.trader.options.sell - it's needed to use a trader (default: all)
  • dtl.trader.options.buy - it's needed to use a trader (default: all)
  • dtl.trader.options.simple-mode - allows to open a trader shop for sell/buy transactions (default: all)
  • dtl.trader.options.manager-mode - allows to open a trader for managing his content
  • dtl.trader.options.type.* - allows to use specific trader types
  • dtl.trader.options.type.server - allows to create/set/manage/use a server trader (default: all)
  • dtl.trader.options.type.player - allows to create/set/manage/use a player trader (default: all)
  • dtl.trader.options.type.player-bank - allows to create/use a player bank (default: none)
  • dtl.trader.options.type.money-bank - allows to create/use a money bank (default: none)
  • dtl.trader.options.wallet.* - allows to use specific wallet types
  • dtl.trader.options.wallet.infinite - allows to set an infinite wallet
  • dtl.trader.options.wallet.bank - allows to hook the trader into a bank account
  • dtl.trader.options.wallet.owner-wallet - allows to hook the trader to his owners wallet
  • dtl.trader.options.wallet.npc-wallet - allows to give the trader his own wallet
  • dtl.trader.commands.* - allows to use all commands (default: op)
  • dtl.trader.commands - allows to use /trader command
  • dtl.trader.commands.list - allows to use /trader list command
  • dtl.trader.commands.wallet - allows to use /trader wallet command
  • dtl.trader.commands.type - allows to use /trader type command
  • dtl.trader.commands.owner - allows to use /trader owner command
  • dtl.trader.commands.balance - allows to use /trader balance command
  • dtl.trader.commands.withdraw - allows to use /trader withdraw command
  • dtl.trader.commands.deposit - allows to use /trader deposit command
  • dtl.trader.commands.create - allows to use /trader create command

Alfa features

  • player traders - at the moment they can only sell items and buy, and they are still a alfa version, incoming multiple amounts management :)
  • locazization support - a basic locazization support is available, i will update it in the next releases
  • Bankers (added multiple tabs support!) (DO NOT CHANGE THE CONFIG FOR THEM!)

Upcoming features

  • player traders Done!
  • more commands (... item add/remove/edit, ... lang)
  • entity support by using the /trader create command done
  • bankers (lets make a trader being a bank!) Alpha version
  • auction house (in the planning stage right now)
  • enchant trader (so you choose what enchant you want to buy!)
  • localization support Done!
  • simple clans/faction wallets are a possibility
  • Custon managing and switch navigation items (idea by MajorVictory) Done!
  • Money bankers (displaying economy money as items) (idea by Instinx) Done! Was easier I've thought, lol
  • contact me if you wish to add anything to this list

Issues

If you'd like to let me know of any bugs, improvements or whishes regarding the plugin you can reach me at [email protected] or on GitHub - DtlTrader Issues

You can allso join my IRC channel on "irc.esper.net". ChennelName DtlTraders

Thanks to

  • Lethe - for helping me a lot and still listening me
  • Wreyth - for feedback
  • Instinx - for feedback
  • silentassasin - for feedback
  • Gizmoholm - for feedback
  • tehbeard - for helping me improve my programming skills

Comments

Posts Quoted:
Reply
Clear All Quotes