# Deck and Bag Search

> Author who may privately look through a deck or bag, what happens to the pile afterwards, and how a deck's own setting overrides the Area zone it sits in.

- Source: https://diceytable.com/docs/editor/workflows/deck-search
- Last verified: 2026-09-04

**Search** lets one player look through a whole pile privately — every card in a deck, every item in a bag —
find what they need, and take it, without any of it becoming public. It is the answer to tutoring in a card
game, to retrieving a specific unit from a bag, to checking a discard pile: the alternative used to be revealing
the pile to everybody, which destroys the hidden information the rest of the table depends on.

Because a search hands one player the contents of a pile, **who may do it is authored, not assumed**. Edit Mode
gives you two places to say so, and one rule for how they combine.

## The deck's own settings

Select a `deck` or a `bag` and the Inspector shows the same two dropdowns — for those two kinds only, the same
pair the runtime allows a search on. They sit in different panels: a deck's are on
[PIECE](https://diceytable.com/docs/editor/inspector/piece#search-deck-pieces-only), a container's on
[CONTAINER](https://diceytable.com/docs/editor/inspector/platform-panels#container), beside the rest of that container's policy.

**Search** — who may open one:

| Option | Who that is |
|---|---|
| **Not set** | Nothing is authored here. The zone decides, and then the default does. |
| **No one** | Search is off for this pile. |
| **Owner seat only** | The holder of the pile's owning seat. An unowned pile means nobody. |
| **Host only** | The host. |
| **Owner seat and host** | Either of the two above. |
| **Anyone** | Everyone at the table. |

**After search** — what happens to the remainder when the session closes:

| Option | What it does |
|---|---|
| **Not set** | Falls through to the zone and then to the default, **Shuffle the rest**. |
| **Shuffle the rest** | The host shuffles what is left. |
| **Keep the order** | The pile is left exactly as it was, minus anything taken. |

**Shuffle the rest** is the default because a player who has just browsed a pile now knows its order. Leaving it
untouched leaks that order for the rest of the game, which is the same reason a physical tutor ends with a
shuffle. **Keep the order** exists for piles whose order is the point — a discard pile, a scripted sequence —
where shuffling would destroy authored state.

## The zone's setting

Select an **Area** seat zone and the Inspector offers a single **Search** dropdown, the same audience list, with
no **After search**. It sets the rule for every searchable pile sitting inside that zone that has not been set
individually.

It is offered on `area` zones only, and for the same reason **Interaction** is: the runtime resolves a pile's
zone rule through the smallest containing *area* zone, so the control on any other zone type would author a
value nothing reads.

## Which one wins

**The pile's own setting overrides the zone's** — an author who set a rule on this particular deck meant this
particular deck.

The precedence runs deck, then zone, then default, and it is resolved **per setting, not per source**:

| The deck says | The zone says | Result |
|---|---|---|
| Search: **Anyone** | Search: **Host only** | **Anyone** — the deck wins. |
| Search: **Not set** | Search: **Host only** | **Host only** — inherited from the zone. |
| After search: **Keep the order**, Search: **Not set** | Search: **Anyone** | Audience **Anyone** from the zone, order **Keep the order** from the deck. |
| Both **Not set** | **Not set** | The kind default (below). |

That last row of behaviour is the one worth remembering: authoring half a policy on the deck does not silently
throw away the other half authored on the zone.

### The unauthored defaults

- **A deck** defaults to **Owner seat and host**. The posture on hidden information here is fail-closed, so an
  unowned deck on an ad-hoc table ends up host-only rather than open to the room.
- **A bag** defaults to **No one**. A bag draws at *random* by design — that randomness is the mechanism — so
  browsing one and choosing is against its nature and has to be turned on deliberately.
- **After search** defaults to **Shuffle the rest** for both.

**The "Not set" label names the kind default, not your zone.** A deck's dropdown reads `Not set (Owner seat and
host)` even when the Area zone it sits in says something else — the label is the fallback for the kind, and the
zone still takes precedence over it at the table. Read the zone's own dropdown to see what an unset pile in it
will actually do.

## What a search looks like at the table

- The searching player gets a private browse of the pile. Nobody else's screen changes.
- The table sees three identity-free lines in the log: the search opening with a **count** and the pile's name,
  a line for each card taken, and a line when the session ends. None of them ever names a card.
- Closing applies **After search**. A pile set to shuffle produces an ordinary public "shuffled" line as well.
- A session that is never closed expires on its own after five minutes, which is the safety net for a player who
  disconnects mid-search.
- **A refused search is refused silently.** Someone without permission sees nothing happen and the table is told
  nothing — announcing the attempt would leak the intent the whole feature protects.

## What scripts can and cannot do with it

A table script can **watch** a search through
[`DeckObject.onSearched`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearched),
[`onSearchPulled`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearchpulled) and
[`onSearchClosed`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearchclosed) — and the matching trio on
[`BagObject`](https://diceytable.com/docs/scripting-api/object-types#bagobject).

It cannot **request** one, and it is never told **which card** was taken. Both limits are deliberate: a script
that could open a search could manufacture a private reveal for itself, and a script that could read the pulled
card would sidestep the redaction that keeps the pile hidden in the first place.

A mod has no search hook at all. Mods observe a search the way they observe anything else public — the three
lines arrive in the ordinary table-event stream, naming the pile and never a card.

## See also

- [`DeckObject.onSearched`](https://diceytable.com/docs/scripting-api/object-types#deckobjectonsearched) — the script side, and the two rules in full.
- [Zones and seats](https://diceytable.com/docs/editor/working/zones-and-seats) — what an Area zone is, and how a pile comes to sit in one.
- [Platform panels](https://diceytable.com/docs/editor/inspector/platform-panels) — the Inspector reference for both controls, field by field.
- [Building a Deck](https://diceytable.com/docs/editor/workflows/build-a-deck) — making the pile this applies to.
- [Action vocabularies](https://diceytable.com/docs/reference/action-vocabularies) — where `search` sits among the engine's actions.