/loot-collector-guide
Loot Collector Rules
The Loot Collector mod judges every item in the collector against a list of rules you write, and decides what goes, what stays and what you never see. This is the whole grammar - four actions, eight conditions, and the two words that join them - with the example from the mod's own page taken apart line by line.
Get the modThe shape of a rule
A rule is an action and the conditions that decide it. Nothing else. It reads as one line, and that line is exactly what the editor draws as a card:
collect: rarity<=radiant5 & type=gem
Collect is what happens. The two conditions are what has to be true, and the & between them is and, so both have to hold. Read aloud: collect any gem that is Radiant 5 or below.
You never have to type that line. Rules in the window's header opens an editor where every part is a control you press, and a keypad opens under any value box - the game holds on to the keyboard while the window is open, so rules are written with the mouse. The written form matters because it is what this guide can show you, and what the mod stores.
Nothing happens while the editor is open. No item is locked, unlocked or collected until you close it, so a half-written rule can never take anything. The one exception is hide, which filters the list as you write it.
The four actions
Every rule starts with one of these. Three are verdicts about an item; the fourth builds the list itself.
collect
Unlocks the item, and - only if Auto Collect is on - collects it there and then. With Auto Collect off it just unlocks, and Collect All takes it when you press the button.
keep
Locks the item. A locked row is dimmed, carries a no-entry mark, and Collect All walks past it. This is how something survives the sweep.
unlock
Unlocks and stops there. Collect All will take the item when you press it, and Auto Collect leaves it alone - the one way to hand something to the button without it being swept up automatically.
hide
Takes the item out of the list entirely. It gets no lock, no collect and no row. Use it to stop looking at things you do not care about.
collect versus unlock
These two differ in exactly one way, and only when Auto Collect is on. Collect sends the item the moment it lands in the collector. Unlock only clears the lock, so the item waits for you to press Collect All. If you like Auto Collect for gems but want to eyeball your gear before it goes, that is a collect rule for the gems and an unlock rule for the gear.
Unlock is also the only rule that undoes a lock you put on by hand. An item you left-clicked stays locked until something unlocks it, and nothing else in the list will.
The eight conditions
A condition is a field, an operator and a value. Most fields take all six operators; the two that hold words take only = and !=.
| field | what it is | operators | example |
|---|---|---|---|
name | The item's name. A star anywhere loosens it. | = != | name=*Dragonsoul |
type | What kind of thing it is: gem, hat, ring, banner, weapon, ally, tome, flask, block, food and the rest. | = != | type=gem |
rarity | Written as a name, never a number. The whole ladder is below. | all six | rarity>=radiant1 |
power | The Power Rank the game prints on the item. Shortened in the file; it is the same number. | all six | power>=3000 |
stats | How many stats the item rolled - a count, not a value. | all six | stats<=2 |
stars | The star count on a piece of gear, 1 to 5. | all six | stars>=4 |
quality | A gem's roll quality as a percent, 0 to 100. Gems only. | all six | quality<20 |
qty | How many of the item are stacked on that row. | all six | qty>=100 |
The six operators are =, !=, <, <=, > and >=. On rarity they mean what they look like on the ladder: <= is this or worse, >= is this or better.
Four of these arrive late
Name, rarity and quantity are known the moment a row appears. Type, power, stats and quality have to be read off the item itself, so a rule using any of them waits until the window has read the whole list - a few seconds after it opens. Nothing is lost by it; it is only why a rule on power does not decide instantly and a rule on rarity does.
Two gaps are worth knowing about. A few items carry no type at all - crafting materials, placeables and unlockers have no equipment slot for the game to name - so a type rule leaves them alone rather than guessing. And a gem carrying a retired stat has no quality worked out, so a quality rule passes over it too. In both cases the item is not judged false; it is simply not judged.
The rarity ladder
Rarity values are written as names. There are 32 of them and they sit in one ordered ladder, which is what makes <= and >= useful:
1common
2uncommon
3rare
4epic
5legendary
6relic
7resplendent
8shadow1
9shadow2
10shadow3
11shadow4
12shadow5
13radiant1
14stellar1
15radiant2
16stellar2
17radiant3
18stellar3
19radiant4
20stellar4
21radiant5
22stellar5
23crystal1
24crystal2
25crystal3
26crystal4
27crystal5
28mystic1
29mystic2
30mystic3
31mystic4
32mystic5
Radiant and Stellar interleave. They are not two tiers stacked one above the other - each Radiant sits directly below the Stellar of the same number. So rarity<=stellar3 also catches Radiant 1, 2 and 3, but not Radiant 4. If you mean everything below Crystal, write rarity<=stellar5, which is the top of that run.
This is the game's own ordering, read out of the client rather than a list somebody typed. Write the name in lowercase with no space: crystal5, radiant1, resplendent.
Names, and the star
A name matches exactly unless it carries a star. name=Glim is only an item called precisely that. Put a star anywhere and the whole pattern loosens: the pieces either side of it then have to appear in that order, anywhere in the name.
name=*Dragonsoul- anything with Dragonsoul in it, wherever it sits.name=radiant*helmet- a Radiant helmet, whatever the game puts between the two words.name=*Gem Box- every kind of gem box.name=*- anything at all. Useful as the last rule in a list.name!=*standard*- anything without standard in the name.
Case is ignored, so *dragonsoul and *Dragonsoul are the same pattern.
and, or, and blocks
The word between two conditions is a control - press it to swap and for or. Every condition inside one block shares that single word, so a block asks for either all of its conditions or any of them, never a mixture.
To mix them you add a second block with + block, which gets its own word between the two groups. That is one level of grouping, and it is the whole of it:
keep: (type=banner , name!=*standard) & rarity>=radiant1
Read: keep anything that is a banner or is not named standard, as long as it is Radiant 1 or better. In the written form & is and, , is or, and the brackets are what say a rule has blocks at all. A rule with no brackets is one block, however many conditions it carries.
There is no second level. You cannot nest a group inside a group. When a condition needs to apply to several alternatives at once, you repeat it in each block - which is exactly what the worked example below does with type=gem.
A rule with no conditions is ignored rather than matching everything, so a half-built card sitting in your list is harmless.
Order decides
The first rule that matches an item decides it, and the rest are never read for that item. So an exception goes above the sweep it is an exception to. Drag a rule by the handle on its left to move it.
| your list | a Stellar 3 Dragonsoul Helmet |
|---|---|
collect: rarity<=stellar5keep: name=*Dragonsoul | Collected. The sweep matched first, so the keep rule never got a say. |
keep: name=*Dragonsoulcollect: rarity<=stellar5 | Kept. The exception matched first and the sweep was never read. |
Hide is not in that race. It builds the list rather than deciding an item, so a hide rule takes something out wherever it sits - top, bottom, anywhere.
Each card tells you what it decides - will collect 4 items - counted off the list in front of you. A rule sitting below one that already decided an item counts none of it, so those two lists above report their totals differently even though the rules are identical. Click the count and the rule names the items.
The example on the mod's page, read line by line
This is the screenshot on the mod's own page, redrawn. Two rules: a three-block gem sweep, and a folded keep rule underneath it.
rarity<=Crystal Level 5andtype=gemortype=gemandstats<=2ortype=gemandquality<=20name != *standard* and type = banner and rarity <= Epic
nothing to keep
Written out, those two cards are these two lines:
collect: (rarity<=crystal5 & type=gem) , (type=gem & stats<=2) , (type=gem & quality<=20)
keep: name!=*standard* & type=banner & rarity<=epic
The collect rule, block by block
Three blocks joined by or, so an item only has to satisfy one of them. Every block also says type=gem, which means the whole rule only ever touches gems.
rarity <= crystal5and type = gemtype = gemand stats <= 2type = gemand quality <= 20So the rule reads: collect any gem that is Crystal 5 or below, or has two stats or fewer, or rolled at 20% quality or worse. A Mystic gem with three well-rolled stats matches none of the three blocks and is left alone. The card says it will collect 33 items, which is what it would take off the list in front of it the moment the editor closes.
Why type=gem is written three times. Because grouping stops at one level. You cannot write gem and (A or B or C), so instead you write (gem and A) or (gem and B) or (gem and C), which is the same thing said the long way. Any time you find yourself repeating a condition in every block, that is why.
The keep rule
One block, three conditions, all joined by and - so all three have to hold. It is shown folded to a single line, which is what the minus button beside a card does.
name != *standard*type = bannerrarity <= epicTogether: lock any low-rarity banner that is not a standard one, so Collect All walks past it. The card reads nothing to keep because no such banner was in the list at the time. A count of zero is a fact about your loot, not a fault in the rule.
The two rules never argue. The first only matches gems and the second only banners, so their order makes no difference here. That is worth noticing precisely because it is the exception - the moment two rules can match the same item, the one on top wins and the other is never read.
More examples
Each of these is a complete list. Rules are read top to bottom, so the order shown is part of the recipe.
Clear the junk, keep everything else
collect: rarity<=relic
The simplest useful list. Anything Relic or below is unlocked and swept; everything above it is left exactly as you found it. One rule, one condition.
Sweep, but never these
keep: name=*Dragonsoul
collect: rarity<=stellar5
The exception sits above the sweep, so a Dragonsoul is locked before the sweep ever sees it. Flip the two lines and the Dragonsoul goes with everything else - this is the single mistake that catches people out.
Only look at gear
hide: type=block
hide: type=food
hide: type=compostable
Three hide rules and no verdicts at all. Nothing is locked or collected; the list simply stops showing you crafting stock. Hide runs wherever it sits, so these work just as well at the bottom.
Auto Collect for gems, by hand for gear
collect: type=gem & rarity<=stellar5
unlock: rarity<=relic
With Auto Collect on, the gems go on their own as they land. The gear is only unlocked - it sits there until you press Collect All, so you get a look at it first. This is the pairing unlock exists for.
Keep anything with real stats on it
keep: stars>=4 & rarity>=radiant1
collect: rarity<=stellar5
Four or five stars and Radiant 1 or better survives; everything else up to Stellar 5 goes. Both conditions sit in one block sharing the same and, so a four-star Relic is not spared.
Keep the good gems, take the rest
keep: type=gem & quality>=70
collect: type=gem
Quality is the gem's roll as a percent. Anything at 70% or better is locked and every other gem is swept, regardless of rarity - which is the point: a badly rolled Mystic is worth less than a well rolled Stellar.
One rule, two ways in
keep: (stars=5) , (type=gem & quality>=90)
Two blocks joined by or: a five-star piece of gear, or a near-perfect gem. Either one is enough. This is the shape to reach for when one rule should cover two unrelated things instead of writing two rules.
Hoard a stack
keep: qty>=100
collect: rarity<=resplendent
Qty is how many sit on the row. Anything you have a hundred or more of gets locked, and the rest of the low-rarity pile goes.
The full sweep, with a floor
keep: rarity>=crystal1
hide: type=block
collect: name=*
Read top to bottom: lock anything Crystal 1 or better, stop showing blocks, and collect everything that is left - name=* matches any name at all. The keep rule above it is what stops the sweep being total, so the order here is doing all the work.
Where the rules live
They are stored with the mod's other settings, on the rules line, with a | between one rule and the next - which is why every example above can be shown as text. Writing them in the window's editor is the normal way in, and the editor keeps that line in step for you.
rules = keep: name=*Dragonsoul | collect: rarity<=stellar5
Rules are re-read the moment you close the editor and every item is judged again from the top, so a change never leaves half the list decided under the old rules and half under the new ones.