dealer

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.

SKILL.md

GitHub

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. 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