Bukkit

SUBJECT TO CHANGE

This was written at a certain stage in the development of this plugin and there is no guarantee that the information in the page will be kept up to date with each and every change to the plugin. It may become too much hassle to maintain this page through all future changes, and if it does I may drop it.

The data format of config.yml

The typical user or even admin of this plugin does not need to know this. This page is provided for admins who may find it easier to edit the config file directly to cause changes rather than to manipulate it through commands. Be warned that if you edit it incorrectly it may mess things up. As always keep a copy of it saved before editing it.

Justification

Often plugins use SQL to store their data. Although that is much faster for things that need to constantly update many times a second, that does come with a bit of overhead admin work though because then the admin has to set up the database server. If SQL is not needed that I figure it's better to keep it simple and just store the data in the config file. This plugin only needs to write to the config file when a user changes the configuration of a container. Once a dedicated container is configured with its item exceptions the plugin does not need to write the config file to just operate and use the dedicated container.

The file is written to any time someone makes a change

If you are going to edit the config.yml file directly be aware that the file is written to every time someone makes a change. It may be a good idea to only edit the file while the plugin isn't active, or set the permissions to prevent others from using it while you edit the file.

Now the format

• Because the file is written to by the plugin, and because the config.yml API in bukkit does not provide a way to remember the comments and write them back out, any comments you write in the file will be deleted, unfortunately.
• As always, be aware of tabs when edting config.yml or indeed any YAML file. YAML files should have no tab characters in them.

nextPut

nextPut:
  Playername1: [true/false]
  Playername2: [true/false]
  ... etc ...

This is a list of players that have a /dedicate next command still pending (who have not yet placed their container for it). If the parameter says true then the player's next container is a default disallow container. If the parameter says false then the player's next container is a default allow container. If the player has no pending command their name is removed form the list. If no player has a pending /dedicate next command then nextPut will have an empty list "{}" as its value.

A dedicated container section (container id)

The id key for defining which container is being talked about consists of the following string:

• "Container_in_" + name of world + "_at_x=" + x coord + ",y=" + y coord + ",z=" + z coord.

Example:

• Container_in_world_nether_at_x=-140,y=60,z=231:

This was chosen over using the internal unique id for the container specifically to make the config.yml file human-readable. You can tell from reading the file which container it is, and go look at it in the world.

Here is a typical config section from version 0.3.3 and earlier:

Container_in_world_at_x=-620,y=116,z=-100:
  default: false
  owner: Dunbaratu
  SAND: false
  BREAD: true
  REDSTONE_LAMP_OFF: true

And here is the same section from version 0.3.4 or later:

Container_in_world_at_x=-620,y=116,z=-100:
  default: false
  owner: Dunbaratu
  SAND:
    exception_type: false
  BREAD:
    exception_type: true
  REDSTONE_LAMP_OFF:
    exception_type: true

Breaking it down it looks like this:

default

  default: [true/false]

Stores whether the container is a whitelist or blacklist container. If false then the container refuses items by default, if true then it allows items by default.

owner

  owner: PlayerNameHere

Remembers who the player was who placed the container. Only this player is allowed to alter the rules for this container. If you set it to a bogus name string then no players can edit the rules for the container.

Material Name

The rest of the container section is a list of all the materials that have special rules, listed one at a time by material name. The material names are taken from the bukkit API names given here: You should make sure to spell them in ALL CAPS like they are shown on that page. The exact format is a bit different depending on whether you are using version 1.0.0 of this plugin or higher, versus using an earlier version:

If using version 0.3.3:

  SOME_MATERIAL_NAME_HERE:  [true/false]

If using version 0.3.4 or above:

  SOME_MATERIAL_NAME_HERE:
    exception_type: [true/false]

In both cases, the [true/false] parameter says what the override is for that particular kind of item. If it's "true" then it's overridden to be allowed, and if it's "false" then it's overridden to be disallowed. Note that yes it is possible for a container to hold redundant rules that override a specific item to be what the container's default was anyway. (i.e. a container allows all items by default, and there's a rule that says it also allows iron ingots, which is redundant since it already allowed them anyway as part of its default behavior.) The reason this is allowed is so that the container can still remember the settings it had before if it gets flipped from default: false to default: true or visa versa.

The 'dmg' subsection for storing the "exact|better|worse" parameters

This bit applies only to versions 0.3.4 and above of this plugin.

If the rule for an item exception depends on the damage value or subtype of the material, then the "dmg" key will be in the container section and have another key under it called either 'exact', 'better', or 'worse'. These correspond exactly to the command line parameters of the same name.

exact:

To state that exact damage values or subtype matters, it looks like this:

    dmg:
      exact:
        - NUM
        - NUM
        - NUM

Where the NUMs are integer numbers for the damage values or subtype ids. The rule will apply to all numbers in the list. Note that it must be presented as a YAML list even when there's only one item in the list. In other words don't do this:

      exact: NUM

Instead do this:

      exact:
        - NUM

better and worse : To state that the rule applies to items of this type with any damage value equal to or less than a number (better) or any with damage values equal to or higher than a number (worse), the format looks like this:

    dmg:
      better: NUM

or

    dmg:
      worse: NUM

where NUM is the number in question. Note that it's an amount of damage, so zero means 100% undamaged. The max damage an item can take varies from item to item making it hard to say what the max sane value for NUM is.

Finally, here's an example of a 1.0.1 file fully using all the above things, for reference:

nextPut:
  Dunbaratu: false
Container_in_world_at_x=-620,y=116,z=-98:
  default: false
  owner: Dunbaratu
  BREAD:
    exception_type: true
  REDSTONE_LAMP_OFF:
    exception_type: true
Container_in_world_at_x=-620,y=116,z=-100:
  default: false
  owner: Dunbaratu
  SAND:
    exception_type: false
  BREAD:
    exception_type: true
  REDSTONE_LAMP_OFF:
    exception_type: true
Container_in_world_at_x=-620,y=115,z=-98:
  default: true
  owner: Dunbaratu
  BREAD:
    exception_type: false
Container_in_world_at_x=-212,y=63,z=58:
  default: false
  owner: Dunbaratu
  DIAMOND_SPADE:
    exception_type: true
  DIAMOND_PICKAXE:
    exception_type: true
    dmg:
      better: 37
  WOOL:
    exception_type: true
    dmg:
      exact:
      - 1
      - 3