Collection traits

Give every piece its properties and let Zoide work out how rare each one is. How many you can define on your plan, the 1,024-byte limit, importing a whole collection from a file, editing hundreds of pieces at once and what collectors end up seeing.

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:

  1. 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.
  2. Assign them in the Pieces tab: every piece has one selector per trait, saved with Save all like the rest of its form.
%
25 pieces
%
150 pieces
None
%
No value: 75 pieces
Add value Total: 100.00 %

Import from a file

Example template Export the collection
Validate
The Traits tab, with one trait and its three values. A copy of the real one, kept in step with it.

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.

12.png
Suggested: RARE · rank 12 of 250
COMMON · 60.00 %
EPIC · 10.00 %
A piece's form with its two traits and, under its rank, the suggestion

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, rarity and, for each trait, three: its value, trait:<Name>, and its percentage and rarity, trait:<Name>:percentage and trait:<Name>:rarity. Only item_file is 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 with item_file, name, number, rarity and attributes (each attribute a trait_type, a value and, optionally, a percentage and a rarity). 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. Its edition counts as the number and its image as 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.png is 7.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 None leaves 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_file column, 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:

Select the loaded ones Select the 80 in the filter 80 selected Clear selection Renumber 1..N
Apply
Eighty pieces selected through the filter, about to get the value Cap
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:

Rank #12 / 250
Background Night 60.00% COMMON
Hat Crown 10.00% EPIC
The traits block on a piece's page

On the collection page, a filter by trait that says how many pieces carry each value, and sorting by rank:

Clear
Background
Hat
The trait filter of a collection page, with Night ticked

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.