Dealer

---
name: dealer
description: Use when writing, editing, debugging, or reviewing dealer language code in btn, dlr, or script files. Provides the complete dealer DSL syntax reference for bridge hand generation constraints.
---

# Dealer Language Reference

You are helping write or edit dealer language code for bridge hand generation. Dealer is a DSL that defines constraints on bridge hands so that only hands matching the constraints are produced.

## File Types

- **btn files** (`btn/`): Master scenario files with metadata headers + dealer code + `#include` directives
- **dlr files** (`dlr/`): Extracted dealer code (generated from btn by the pipeline — do NOT edit directly)
- **script files** (`script/`): Reusable dealer code fragments included via `#include "script/NAME"`

Always edit **btn files**, never dlr files directly.

## BTN File Structure

```
# alias: ScenarioName
# button-text: Display Name
# gib-works: true
# bba-works: true
# auction-filter: REGEX_PATTERN
# convention-card-ns: 21GF-DEFAULT
# convention-card-ew: 21GF-GIB

/*@chat
Description text for BBO display.
Use plain regular commas here; the pipeline converts them to wide commas (，) downstream. Do NOT hand-type wide commas in .btn files.
@chat*/

dealer south|west|north|east

#include "script/TP"
# Defines tpWest, tpNorth, tpEast, tpSouth

# ... dealer constraints ...

produce 30

action
average "label" 100 * variable,
```

## Core Syntax

### Variables and Assignment
```
x = expression
```
Variable names are case-sensitive. No declaration needed.

### Comments
```
# full line comment (must start at column 0 / start of line)
// everything after // is a comment (can appear at end of a line)
/* multi-line comment */
```

**IMPORTANT:** `#` is a comment marker **only at the start of a line**.
Inline / end-of-line comments must use `//`. Writing `x = 5 # comment`
is a syntax error — the parser does not treat `#` as a mid-line
comment marker. (`#include "..."` at the start of a line is the only
non-comment use of `#`.)

### Boolean Operators
```
and    or    not
```

### Comparison Operators
```
==  !=  <  >  <=  >=
```

### Arithmetic
```
+  -  *  /  %
```

### Ternary (Conditional)
```
condition ? value_if_true : value_if_false
```

### Grouping
```
(expression)
```

## Built-in Functions

### Suit Length
```
spades(PLAYER)      # Number of spades (0-13)
hearts(PLAYER)      # Number of hearts (0-13)
diamonds(PLAYER)    # Number of diamonds (0-13)
clubs(PLAYER)       # Number of clubs (0-13)
```
PLAYER is: `north`, `south`, `east`, `west`

### High Card Points
```
hcp(PLAYER)              # Total HCP for hand (A=4, K=3, Q=2, J=1)
hcp(PLAYER, SUIT)        # HCP in a specific suit
```
SUIT is: `spades`, `hearts`, `diamonds`, `clubs`

### Shape Patterns
```
shape(PLAYER, PATTERN)
```
Pattern format: `SHDc` where each position is a digit (exact count) or `x` (any).

Each position is a digit for an exact count, or `x` for any count (0-13).

Examples:
```
shape(south, 4432)           # Exactly 4 spades, 4 hearts, 3 diamonds, 2 clubs
shape(south, 5xxx)           # Exactly 5 spades, any others
shape(south, x5xx)           # Exactly 5 hearts
shape(south, xx44)           # Exactly 4 diamonds, exactly 4 clubs
shape(south, 44xx)           # Exactly 4 spades, exactly 4 hearts
```

To express "4 or more", use suit length functions instead:
```
spades(south)>3              # 4+ spades
spades(south)>3 and hearts(south)>3   # 4+ in both majors
```

Combining patterns with `+` (union) and `-` (exclusion):
```
shape(south, any 4432 + any 4333)           # Any permutation of 4-4-3-2 OR 4-3-3-3
shape(south, any 5xxx - any 55xx)           # 5-card suit but not two 5-card suits
shape(south, any 5332 + any 5422 - 5xxx - x5xx)  # Balanced with 5-card minor
```

The `any` keyword means any permutation of the pattern:
- `any 4432` matches 4432, 4342, 4324, 4243, 3442, etc. (any hand with a 4-4-3-2 distribution)
- `5xxx` without `any` means: exactly 5 spades, any H, any D, any C
- `any 5xxx` means: any suit has exactly 5 cards (with any other distribution)

### Top Honor Counting
```
top2(PLAYER, SUIT)    # Count of A, K in suit (0-2)
top3(PLAYER, SUIT)    # Count of A, K, Q in suit (0-3)
top4(PLAYER, SUIT)    # Count of A, K, Q, J in suit (0-4)
top5(PLAYER, SUIT)    # Count of A, K, Q, J, T in suit (0-5)
```

### Specific Card Check
```
hascard(PLAYER, CARD)
```
CARD format: rank + suit letter. Examples: `AS` (ace of spades), `KH` (king of hearts), `QD`, `JC`, `TD` (ten of diamonds)

### Controls
```
controls(PLAYER)     # A=2, K=1
```

### Losers
```
losers(PLAYER)       # Losing trick count
```

## Control Flow

### The Final Constraint
The last expression in the file (before `produce` / `action`) is the master boolean — only hands where this evaluates to true are produced.

```
# Build up conditions
westOpens and northOvercalls and eastRaises and southDoubles

produce 30
```

### Produce
```
produce N    # Generate N hands (typically 30 for btn, pipeline overrides to 500)
```

### Action Block (Statistics)
```
action
average "LABEL" 100 * booleanVar,    # Percentage of hands where var is true
```
Note: each `average` line except the last ends with a comma.

## Include Directives

```
#include "script/TP"
```
Includes the file at `script/TP`. Common includes:

| Script | Provides |
|--------|----------|
| `script/TP` | `tpNorth`, `tpEast`, `tpSouth`, `tpWest`, `tpNS`, `tpEW` (Total Points = HCP + short-suit points - penalty points) |
| `script/Predict-Opening-1-Bid` | `oS`, `oH`, `oD`, `oC`, `openingSuit` for South |
| `script/Predict-Opening-1-Bid-East` | Same but for East |
| `script/Predict-Response-to-1-Bid` | Response predictions: `nS`, `nH`, `nD`, `nC`, `nN` + auction combos `CD`, `CH`, `CS`, etc. |
| `script/Calm-Opponents` | `calmOpps`, `calmEast`, `calmWest` — opponents who won't interfere |
| `script/GIB-1N` | `gibNT` — predicts South's 1NT opening (15-17) |
| `script/GIB-1N-East` | Same for East |
| `script/Leveling` | Leveling constraints for balanced hand distribution |

## Common Patterns

### Predict Opening Suit (for any player)
```
s = spades(west)
h = hearts(west)
d = diamonds(west)
c = clubs(west)
oS = s>4 and s>=h and s>=d and s>=c
oH = not oS and h>4 and h>=d and h>=c
oD = not (oS or oH) and ((d>3 and d>=c) or c<3)
oC = not (oS or oH or oD)
```

### East's Simple Raise (major suit)
```
eH = oH and hearts(east)==3 and hcp(east,hearts)>1
eS = oS and spades(east)==3 and hcp(east,spades)>1
```

### East's Simple Raise (minor suit)
```
eD = oD and diamonds(east)==4 and hcp(east,diamonds)>2 and spades(east)<4 and hearts(east)<4
eC = oC and clubs(east)==4 and hcp(east,clubs)>3 and spades(east)<4 and hearts(east)<4
```
Minor raises require avoiding negative double shapes (no 4-card major).

### HCP and TP Range Constraints
```
westOpens = hcp(west)>10 and tpWest>11 and hcp(west)<15
northDoubles = tpNorth>11 and hcp(north)<15
```

### Suit Quality
```
goodSuit = spades(south)>4 and top3(south,spades)>1    # 2 of top 3
solidSuit = clubs(south)>6 and top3(south,clubs)==3     # All top 3
```

### GIB Stoppers (from BBO documentation)

GIB classifies stoppers using `length + HCP` (4-3-2-1 count). Dealer code equivalents:

| GIB term | Definition | Example holdings | Dealer code (for spades) |
|----------|-----------|-----------------|--------------------------|
| unstopped | none of the below | xx, xxx | `spades(p) + hcp(p,spades) < 4` |
| partial stop | length+HCP = 4 | Qx, Jxx | `spades(p) + hcp(p,spades) > 3` |
| likely stop | length+HCP ≥ 5 | Kx, Qxx | `spades(p) + hcp(p,spades) > 4` |
| stop | A, QJx, 5+ HCP, or length+HCP ≥ 7 | Ax, Kxx, AJx | `hcp(p,spades) > 4 or spades(p) + hcp(p,spades) > 6` |
| two stops | length+HCP ≥ 8 | Axx, KJx, KQx | `spades(p) + hcp(p,spades) > 7` |

Note: `p` = player (`north`, `south`, etc.). Replace `spades`/`spades` with the target suit.

Example — North has a partial stop or better in each unbid suit (after 1C opening):
```
nStopD = diamonds(north) + hcp(north,diamonds) > 3
nStopH = hearts(north)   + hcp(north,hearts)   > 3
nStopS = spades(north)   + hcp(north,spades)   > 3
```

### GIB Suit Quality (from BBO documentation)

GIB classifies suit quality as follows (useful when modeling what GIB will bid):

| GIB term | Definition | Dealer code approximation |
|----------|-----------|--------------------------|
| 3-card | exactly 3 cards | `spades(p) == 3` |
| 4-card | exactly 4 cards | `spades(p) == 4` |
| biddable | 5+ cards, or 4 cards with 3 of top 5 honors | `spades(p) > 4 or (spades(p) == 4 and top5(p,spades) > 2)` |
| rebiddable | biddable + 1 card | `spades(p) > 5 or (spades(p) == 5 and top5(p,spades) > 2)` |
| solid 6-card | AKQTxx or AKQJxx | `spades(p) > 5 and top4(p,spades) > 2 and top3(p,spades) == 3` |

## Tips for Writing Dealer Code

1. **Start broad, then constrain**: Begin with shape/HCP requirements, then add specific conditions
2. **Predict what BBA will bid**: Model each player's likely action based on standard bidding
3. **Avoid over-constraining**: Too many constraints → low produce rate → slow generation
4. **Use `tpEast<10` or similar caps**: Prevents responder from having too many points (avoids jump raises instead of simple raises)
5. **Minor raises need 4 trumps**: GIB/BBA raises minors with 4+ cards, not 3
6. **Major raises need 3 trumps**: GIB/BBA raises majors with 3 cards
7. **Block negative doubles**: When modeling simple raises, add `spades(east)<4 and hearts(east)<4` for minor raises to prevent East from making a negative double instead
8. **Test with `produce 30`**: Quick iteration; the pipeline overrides to 500 for full runs
9. **Check filter rate**: After running the pipeline, a filter rate above 10% is good; below 5% needs work