Definition Metadata
JSON objects that make it easier to Web3 interfaces and webapps to parse and make sense of the "craftable" tokens and Crafting Rulel.
Last updated
JSON objects that make it easier to Web3 interfaces and webapps to parse and make sense of the "craftable" tokens and Crafting Rulel.
Last updated
For illustrative purposes, every example will follow from the clothes.sol showcased in Craftable Token.
Providing definition metadata allows applications like Craftware to display crafting info for registered tokens and perform crafting operations. Craftable game tokens on a given smart contract will store attribute values as lists. a definition will allow us for example to know what each value stands for in terms of game environments.
To associate the URI to a given contract, the contract must be initialized with the correct URI at deploy time in the token constructor.
Once deployed, the definition URI is accessible through the defUri()
function.
The purpose of the metadata is to describe the classes and their attributes for each ERC1155 token.
Here is an example for the clothes.sol
contract.
Here's how each of these properties work:
To be able to craft multiple categories of items in one contract, we define a list of acceptable classes of tokens to be part of the contract. All tokens of the same class have the same set of attributes but not the same attribute values.
Here is an example of the class attributes
Here is how each of the class properties work:
In the contract, we recommend to define the IDs as constants in the start of the contract.
uint256 public HAT_CLASS = 1;
The order of attributes in the definition must match the order of attributes when we interact with the contract. In other words, the attribute at position 1 in the definition has a value in the contract that can be read at token.attributes[1]
and so on.
Inside the smart contract, the attribute values are strictly integers (uint256
to be specific). This means that we need to develop smart ways to represent floats, dropdown fields, ...
The attribute definition helps parties decipher and translate the on-chain integer value to the intended game value. It might look something like this.
So depending on this definition we can translate the attributes of a pants token
The fixed properties for any attribute definition are:
Depending on the type
of the attribute, each attribute might have different properties. For now, we support three types of attributes that can be expanded later on:
Categorical Attribute
Numerical Attribute
Boolean Attribute
type: "categorical"
A categorical attribute is any attribute for a game item that accepts a value from a finite set of choices that can be in text or numbers.
The only extra property to add to the definition is the list options: [...]
. Each option has a name and value. value is the on-chain integer, while name is the game-specific value.
type: "numerical"
A numerical attribute is an approximation for any floating value attribute. Since, we can use integers only on-chain, it means that we can represent specific points in the range of values. For example, if we are using 2 bits of resolution, we can represent 2^2 = 4 values. for the range [1, 3] we can represent the following intermediate values spread out uniformly:
Hence the properties are:
type: "boolean"
A boolean attribute is simple as the name suggests. It is an attribute than can be either True or False. The corrsponding integer value can be respectively 0 or 1. No extra propreties are needed if you define a boolean attribute.
Integer value | Bits representation | In-game value |
---|---|---|
name
Name of the ERC1155 contract providing the various tokens
classes
These are the various classes of tokens that can be minted in this contract. for example, for clothes
that would be 2 classes: hats and pants.
name
Name of the class
class
The class ID for this class. All tokens of the same class must have this value for the classes(_id)
in the contract.
attributes
A list of attribute definitions for this class.
name
Name of the attribute
type
an attribute can be of many types. each type tells the web-app to translate the integer value differently.
0
00
1
1
01
5/3 ~ 1.66666667
2
10
7/3 ~ 2.33333333
3
11
3
min
The minimum possible value. Lower end of the interval.
max
The maximum possible value. Higher end of the interval.
res
The resolution. The number of possible value points in the interval [min
, max
] is 2 to the power of res
. The larger the resolution, the more accurate you can be in representing intermediate values.