How to put together or edit the card_format.yml

Few things you should know:

• In the rest of this HOW TO card_format.yml will be referred to as "cf"
• "Fields:" Must always be in the cf.
• There are limits that constraint the field in game so that you have more control over what your players put in.
• Everything in the cf but be a parent to something or end with a "[]"
• A field by itself will default to a String with no limits.

Getting Started:

When you first use the plugin there will be a default cf that uses everything that is possible, that way you can see how they are used. Every field, under the Fields section is a separate line on the character card. Under each field you can either write in limits, subtypes, or both. In the newest version you can also write childtypes under the subtypes, this is useful for people who want to make races that have classes, or multiple names in one type of category.

Lets start by looking into the default cf and breaking it down...

The Fields section it the parent to everything, and is where the plugin starts as an entry point to read your custom fields. Without it, the plugin won't find anything within the cf.

Every line, or field on the character card is a child to the "Fields" section in the cf. Everyone one of those is a separate command for the players to input information.

Each field has either limits, subtypes, or both. These children of the field define what it is, and how it works ingame.

Limits contain things that constraint a field. They allow you to set things like the max size of a number, for like an age field, or the size to restrict the length of a name.

ChildTypes are similar to subtypes, but they come after subtypes. These can be used to make classes within a race. For example, you make a subtype named Human, you can then create childtypes, such as warrior, or miner, etc.

Everything in the cf must have an ending, or a child. So for a better understanding, lets say you didn't want a size limit on the Name field. You would just remove the limits parent, which would leave name by itself. You can do this, but you must put the "[]" after it. So in the end it would look like "Name: []".

Diving Into The Details:

What can you do with limits?

type: [String/str/integer/int]

• By default the type is a string, meaning it can contain letters, numbers, and spaces.
• The type will define what other limits can be used

min: {number}

• The min is a limit that affects the integer type.
• It controls the minimum number that can be input. If this is set to 3 and a player tries to put in two, it will automatically go up to the minimum of 3.

max: {number}

• The max is a limit that affects the integer type.
• This is the same as the min, but for the higher numbers. If you make this 100, then anything above 100 will be replace with the max value of 100.

size: {number}

• The size limit will affect string types
• Size will limit the amount of characters for the string. If it is set to 10, then you can have no more than 10 characters.

New Limits Here:

color: [&#&#] or [&#]

• Color limit can be used on any field type. It can take up to two color codes, that way you can do a color and a bold or italic or something.
• color: &b&l
  • Above would be a nice blue that has a bold effect.
• Here is a useful guide for colors: Colour Guide

command: ["@c/command", "@p/command2"]

• The command limit can be used for any field type. The commands input here will be executed when the field is set.
• @c = executed by console | @p = executed by player
• {user} = Player name | {field} = Field input | {Sfield} = Field input with no spaces
• Must be in square brackets. If you're doing one command it would be like this: ["@c/command"]
• In the example card_format under races the limit is: command: ["@c/say {user} has become a &b{field}!", "@p/town join {Sfield}_Town"]
  • Here you can see two commands are executed when the player uses /cc race %input%
  • The first command is a console command that broadcasts to the server what the player has become.
  • The second command is done by the player. In this case the player would join the town of whatever creature they became.
  • On top of that, you can see on the first command &b which is a color code for a light aqua. You can safely use color codes in the commands and they will convert.

What Happens if I used a limit such as min/max on a string type limit? If you mix the limits up, it wont do anything in particular. If you have a max/min on a string, or a size on an integer, the plugin will simply ignore those limits. Same goes for a lockCaps limit on a string/integer. NOTE: LockCaps is false by default.

lockCaps limit?

the lockCaps limit is for a field with subtypes. What the lockCaps does is make it so the player's character card section with that field, will match what you put in the cf. For example, if you look at the default cf, you'll see lockCaps: true on the race field. When a player chooses an Orc with "/cc race orc" and lockcaps is off, then it will display as "orc" on the charactercard. Likewise, if lockCaps is off and a player uses "/cc race OrC" then it would display as "OrC". With lockCaps on, a player can type in any verison of it, but it will always display as "Orc" - or how you have it defined in the cf.

More on Subtypes and ChildTypes

To use subtypes instead of a string or integer, you simply put more children in a field. If you look at the default cf under Gender, you'll see three children, "Male, Female, and Other." A subtype cannot be limits, as that is read as limits for a field no matter what. So when using subtypes, the only things a player can choose ingame for the field Gender is Male, Female, or other. If you wanted to make this free for the player to type in a gender, you would write it as "Gender: []" - or Gender with limits. So simply put, a subtype is a child of a field, that acts like a multiple choice answer for the field, just like a drop down menu.

Lets say you have 2 races, Elf and Humans. Elf and Humans would be subtypes to the Race field. But what if you wanted subclass within that race specifcally. Instead of creating an entire new field called Class, you can do childtypes in the race field. This would slow you to separate Elf classes from human classes, preventing a elf miner or something that doesn't seem right. To make these childtypes, you list them after a subtype. There is an example of this in the default cf in the race field, under the creature subtype. But lets do one here, lets make Elves and Humans have three different classes.

Elves: Cleric, Archer, Ranger Humans: Engineer, Doctor, Warrior

Because each race has their own classes, you can't make another field, or players would have Doctor Elves. So to do the above, it would look like this:

Fields:
  Race:
    Elf:
      Cleric: []
      Archer: []
      Ranger: []
    Human:
      Engineer: []
      Doctor: []
      Warrior: []

So that is how to make child types. remeber though, since we didn't specify lockCaps to be true, it defualts to false. So that means players can display races like "CLEriC (eLF)" - when you really might want it to be "Cleric (Elf)". So to lock the caps you would do the following.

Fields:
  Race:
    limits:
      lockCaps: true
    Elf:
      Cleric: []
      Archer: []
      Ranger: []
    Human:
      Engineer: []
      Doctor: []
      Warrior: []

Hope this HOW TO guide helps!

If you have the time/money it would be great to donate to this project. By donating you'll bump this project up on my priority list and it will get updates within days of Bukkit updates! You can donate on the top right, or click the banner below, thank you for your support! This last update took a very long time to make the guide above and add in the new childtype. Look forward for more!