A trait is a property a piece has: a Background that is Night or Day, a Hat that is a Crown, a Cap or nothing at all. Traits are inscribed with each piece, in the format the 1Sat indexers read, so they travel with the piece wherever it goes — not only on Zoide.
That is also why they deserve some care: what is inscribed cannot be corrected. Everything on this page happens before you submit, in the Traits tab of the Content step.
Define them, then assign them
Two moves, in two places:
- Define them in the Traits tab: each trait with its values. The tab has its own Save traits button, and tells you how many pieces carry each value.
- Assign them in the Pieces tab: every piece has one selector per trait, saved with Save all like the rest of its form.
Import from a file
A few rules worth knowing before you start:
- Names and values are 1 to 32 characters. Short on purpose — see the 1,024-byte limit.
- No duplicates that only differ in case or accents: Café and cafe are the same value, and saving tells you so next to the second one.
- None is reserved. It means no value, which is what a piece has when you do not assign one. Every piece without a hat counts as None in Hat — and None counts in the percentages like any other value.
- Renaming a value keeps it on the pieces that had it. Removing one leaves those pieces without a value, and it asks first, telling you how many pieces carry it.
- Names and values are yours: they are shown as you wrote them, in every language.
How many you can have
| Traits per collection | Values per trait | Pieces per collection | |
|---|---|---|---|
| Without a subscription | 3 | 10 | 100 |
| With a subscription | 20 | 200 | 2,000 |
When you reach a limit, the tab says so and says what a subscription unlocks. See Subscription.
If your subscription lapses while a draft is above the limits, nothing is lost: you can trim it, but not grow it, and Review blocks the submission until you either trim it or renew.
Percentages and ranks are worked out for you
Zoide counts how many pieces carry each value and turns it into a percentage with two decimals that always adds up to exactly 100: the remainder of the rounding is shared out, so three values that appear a third of the time each come out as 33.34, 33.33 and 33.33.
Each value then gets a rank from its percentage — the first tier its percentage does not exceed:
| A value carried by… | is |
|---|---|
| 1% of the pieces or fewer | EXOTIC |
| 5% or fewer | LEGENDARY |
| 10% or fewer | EPIC |
| 20% or fewer | RARE |
| 40% or fewer | UNCOMMON |
| more than that | COMMON |
You can retouch them
The collection is yours. Next to each value you can fix its percentage, and its rank. Leave the field empty and the calculated one applies — and it is shown next to it either way, as the field's hint and as Auto (EPIC), so you always know what you are departing from. They can also come in the import file, already filled in.
A trait whose percentages no longer add up to 100 blocks the submission: giving one value more means giving another one less.
Each piece's rank, and the suggested one
A piece's rank — EXOTIC to COMMON — is still yours to choose, exactly as in Prepare your items. What traits add is a suggestion. From the traits a piece carries, Zoide gives it a score — the rarer its values, the higher — places it among the others, and suggests the tier, using the same table, together with its position: rank 12 of 250.
Next to each trait selector, the piece also shows how rare that value is: its rarity, in its colour, and its percentage — the calculated ones, or yours if you retouched them. A piece without a value for a trait shows the ones of None.
If the rank you chose is not the suggested one, Review mentions it as a warning. It does not stop you.
The position — rank 1 to N, 1 being the rarest — is what gets inscribed and what collectors sort by, and it is not editable. It is ordered first by the rank you assigned, then by the trait score, then by the piece number. So your decision comes first, and the traits only break the ties.
The 1,024-byte limit
The traits are inscribed in each piece's metadata, and the indexers silently drop any metadata over 1,024 bytes. With it, the piece loses its link to the collection and disappears from it. So:
- A piece whose metadata does not fit blocks the submission. Shorter names or values, or fewer traits, fix it.
- The cover carries the whole trait table, every value with its percentage. If that does not fit, the cover is inscribed without the table and Review warns you — the traits stay on every piece. If it does not fit even without the table, the description is too long, and that blocks.
Before submitting you can see the exact data each piece and the cover will carry, with its size: View on-chain JSON. The collection id shows as zeros, because the real one only exists once the cover has been inscribed.
What Review checks
Once the collection has traits and pieces, Review adds these lines. Each failing one has a View link to where it is fixed: the list of pieces already filtered on the ones in question, or the Traits tab.
| Check | |
|---|---|
| Each trait's percentages add up to 100 | Blocks |
| Each piece fits in 1,024 bytes | Blocks |
| Within your plan's limits | Blocks |
| The cover fits with its trait table | Warns if it only fits without the table; blocks if it does not fit even then |
| Value ranks as Zoide calculates them | Warns if you retouched any |
| Each piece's rank as suggested by its traits | Warns if any is different |
Importing a whole collection from a file
Assigning traits by hand to a thousand pieces is not a plan. If your collection comes out of a generator, upload its file instead. Importing is for subscribers; without a subscription the card is shown disabled, and editing in bulk is the way.
The images still go through the upload area, as always. The file brings the rest — the name, number, rank and traits of each piece — and every row is matched to its image by the name the file had when you uploaded it. Every piece in the Pieces tab shows that original name, read-only, precisely so you can check the match: on our side the file is stored under a random name.
Two downloads, two different things
- Example template — three made-up pieces, only to show the format. Nothing from your collection.
- Export the collection — what your collection has right now, one row per piece, to edit and upload back. It is disabled while there are no pieces. Of the percentages and rarities, it only fills in the ones you retouched: empty means calculated, so uploading it back as it is changes nothing.
Both come as CSV or JSON, and both carry every column, so you always know where each thing goes.
The formats
- CSV — the columns are
item_file,name,number,rarityand, for each trait, three: its value,trait:<Name>, and its percentage and rarity,trait:<Name>:percentageandtrait:<Name>:rarity. Onlyitem_fileis required. Comma, semicolon or tab, it is detected, and the file opens cleanly in Excel. Columns it does not understand are ignored, and the report says which. - JSON — a list under
items, each withitem_file,name,number,rarityandattributes(each attribute atrait_type, avalueand, optionally, apercentageand ararity). JSON cannot have comments, so the explanation of every field travels at the top as_guide, in your language. Keys that start with_are ignored when importing. - A HashLips
_metadata.json, as is. Itseditioncounts as the number and itsimageas the file name.
Inside the file:
item_file— case does not matter, and in a path or a URL only the last part counts:ipfs://…/7.pngis7.png.rarity— one of EXOTIC to COMMON, in any case. Empty leaves the piece's rank as it is, and UNRANKED removes it.- A trait a row does not bring, an empty cell or
Noneleaves the piece without a value for it. - A value's percentage and rarity are optional. Empty, Zoide works them out; filled, they are set as they come, exactly like retouching them in the Traits tab — a percentage from 0 to 100 with two decimals at most, a rarity from EXOTIC to COMMON. They belong to the value, not to the piece: repeat the same ones in every row that has it, or fill them in just one row and leave the rest empty.
- On a row without a value for a trait, the percentage is the one of None. None has no rarity of its own.
- If the file does not carry those columns or keys at all — a HashLips file as it comes, say — the percentages and rarities you retouched are left as they are.
- A trait's percentages, None included, must still add up to 100: if they would not after the import, the report warns you, and Review will block the submission until they do.
Validate, then confirm
Validate changes nothing. It returns a report: how many rows match their image, what would change and what is wrong.
What is in red blocks the whole import — nothing is imported until it is fixed:
- the file cannot be read, has no rows or has no
item_filecolumn, or no row matches an uploaded image; - more rows than your plan allows pieces;
- the same image in two rows;
- trait names or values that are empty or too long, or more of them than your plan allows;
- piece names that are empty or over 50 characters, rarities that do not exist, numbers that are not positive whole numbers, or numbers the file would leave repeated in the collection;
- percentages that are not a number from 0 to 100, value rarities that do not exist, or the same value with a different percentage or rarity in two rows.
What is in yellow is reported but does not stop it: rows with no uploaded image of that name, pieces the file does not mention (they are left as they are), several uploads sharing one name (those rows are skipped), columns it does not understand, rows without a file name, a rarity on a row without a value, and traits whose percentages would not add up to 100.
Confirm import validates again and writes everything at once, or nothing. Before it does, whatever you had pending on the page is saved, so the import neither lands on top of unsaved work nor gets overwritten by it afterwards.
Importing again
The file only decides about what it brings:
- for every trait it carries, each piece it lists ends up with the value in its row, and an empty cell clears it;
- traits it does not carry are not touched;
- name, number and rarity only change where the row has them;
- a value's percentage and rarity only change for the traits whose columns or keys the file carries.
Importing again updates by file name: it never creates pieces — the upload area does that — and never duplicates traits or values. So the round trip is safe: export, edit, import.
A thousand rows import in about a second; there is no queue to wait for.
Editing many pieces at once
Whether you import or not, the Pieces tab is built for working on hundreds of pieces:
- Search by name, number or original file name.
- Filter by trait: one value, or no value in a trait. Several filters at once must all match.
- Select pieces one by one, all the loaded ones, or all the pieces in the filter, loaded or not.
Then apply one action to all of them:
| Action | What it does |
|---|---|
| Set or remove a trait | Puts an existing value on all of them, or clears it. It does not create traits or values, so it cannot take you past your plan's limits |
| Set a rarity | The same tier on all of them. UNRANKED removes it |
| Rename with a pattern | Frog #{n} names each one with its own number. The pattern has to include {n}: without it, they would all be called the same |
| Renumber 1..N | The whole collection, not the selection: from 1 to N, in its current order, with no gaps |
It asks first, with the count — you are about to change 80 pieces — and saves whatever was pending before applying. The list, the chart and Review update without reloading.
The typical use: filter on no value in Hat, select all the pieces in the filter, set Hat: Cap.
What collectors see
On a piece's page, its traits — each with its percentage and the rank of that percentage — and its position in the collection:
On the collection page, a filter by trait that says how many pieces carry each value, and sorting by rank:
Both are read from the chain, not from Zoide's database. That is why they also work for any 1Sat collection that carries traits, not only for those published here. See What a piece page tells you.