Let's talk Token Definition Scheme!
As an example of the full scheme I'm made up a hypothetical COLOR token. It's values are not "correct" as dwarf fortress actually uses COLO, but this is for example purposes only.
<token name="COLOR">
<allowedOn type="BUILDING" subType="BUILDING_WORKSHOP" />
<allowedOn type="CREATURE" subType="CREATURE" />
<allowedOn type="ENTITY" subType="ENTITY" />
<usage type="ALL" subType="ALL">
<description>Controls the color</description>
</usage>
<usage type="CREATURE" subType="CREATURE">
<description>Controls the display color of the creature.</description>
<argument name="foreground" type="integer" typeData="1 100">Foreground color of the creature</argument>
<argument name="background" type="colorNumber">Background color of the creature</argument>
<argument name="foregroundBright" type="bit">Is the foreground "bright"? (adds 8 to the color value)</argument>
</usage>
<usage type="BUILDING" subType="BUILDING_WORKSHOP" flags="1">
<description></description>
</usage>
</token>
This token's name is "COLOR", it is allowed to be used on custom workshops, creatures, and entities.
Each "usage" defines token's description and arguments depending on which object type it is placed on. The usage with the type and subtype of "ALL" is a default usage, and the CREATURE CREATURE Usage is a specific usage. In Raw Explorer, if I were to place this token on an Item (even though it isn't allowed there), it would pick up the ALL ALL usage since none of the specific usages match. It always looks from most specific to least specific. A single usage entry of type of ALL:ALL will be the most common.
The CREATURE usage has a textual description that explains what the token does in a general way. It has 3 arguments named foreground, background and foregroundBright.
Foreground is of type "integer", which is a numeric data type. This particular integer must be a number from 1 to 100. Raw explorer will give a warning if you try to use 200 as the first argument in this token on a creature. If you leave out the typeData attribute any integer will be accepted.
The 2nd argument is named background. It's is of type "color", which means when raw Explorer lets you edit this argument it will display a color picker. There is no typeData on this argument, but types of "color" can be restricted to the 8 dark colors, or allow all 16 colors (default if none is specified).
The 3rd param, "foregroundBright", is a bit. This means it can only have 2 values, on or off. By default Raw Explorer will show this as a checkbox, but though the use of the typeData it can be made to display as yes / no, on / off, 1 / 0, etc...
You will notice that the usage for BUILDING has as the "flag" attribute on it with a value of 1. This value means that the usage doesn't use standard arguments. In this case when color is used on the building the number of arguments varies with the number of columns and rows in the custom building. Currently Raw Explorer will only let you edit this type of value directly as a string
I've gone through the raws and looked at the different tokens and tried to break their arguments down in to types. I've explained the integer, color, and bit types. So far I've come up with the following types. I've sure that there are some that I've missed, if you know of any, let me know.
- string - Textual data
- integer - numeric data, whole numbers only
- number - numeric data with decimal places
- bit - true of false data
- colorNumber - 1 of DF's 16 colors
- degreesUrist - a temperature
- lookup - an argument that's value comes from other places in the raws. The typeData will define where this comes from. For example, if the type is "lookup", and the typeData is "ITEM:ITEM_TOOL", Raw Explorer will display a drop down list of all the tools defined in your raws when editing this argument.
- list - an item from a predefined list of options
- filename - a filename on the hard drive
- charCode - a single character or ASCII number
Each of these types will be able to be controlled in different ways via the typeData attribute. The website will have all the documentation once I've figured it all out.
Speaking of which, the website is almost ready for some limited beta testing. If anyone wants to volunteer to test it just let me know. The website will allow anyone to view tokens. Editing a token will require an account. All edits will go in to a queue for approval before they show up live. I hope to have a few trusted people who can help me as moderators approving submissions once the site is running.
Stay tuned, exciting things are happening!
Author
Topic: Modding Tool: Raw Explorer - Beta 13 - Updated 4/25/2013 - (It's BACK!) (Read 166054 times)