Introduction
[-]
Introduction return to Line List
Pinochle Notation (PN) is a free, open source standard for expressing pinochle game data. For PN expansion requests, message/email its author mickmackusa. PN enables game hosts and players to record online and offline hand histories for review. Power Pinochle will develop new software to enrich, store, and serve the PN. PN has undergone many waves of refinements and rewrites. While the PN could have taken a variety of functional forms, in the end priority was given to Human-Readability, Parsability, Simplicity, Brevity, and Expandability.
General Specifications
[-]
Notation Structure return to Line List
Annotations are written as plain text and each expression may only occupy one line. Each line consists of a label followed by one or more values. A label must be one or more words; a trailing number may be used when necessary. Each word in a label must start with an uppercase letter and must not contain a space. A space separates a label and its value(s). If a label expects multiple values, each value is separated by a space. Lines are grouped and ordered to improve reading and parsing.
[-]
Lines Groups & Order return to Line List
[-]
Annotation Status return to Line List
Annotations will qualify for one of three statuses: "Invalid" and "Incomplete" and "Complete". Annotations that breech PN specifications will be deemed Invalid, will not be parsed, and will not be used for statistics. Valid annotations that omit expected lines will be deemed Incomplete, will be parsed, but will not be used for statistics. Valid annotations that include all expected lines will be deemed Complete, will be parsed, and may be used for statistics. See individual line specifications for expected lines and default values.
[-]
Special Characters return to Line List
"question mark" (?) is used as a placeholder for a value to be provided by a reader or bot. (For teaching/scripting, not for recording real game data)
"hyphen" (-) is used as a placeholder for a withheld or action-less value.
"space" (\s) is used to separate labels and values in a single line.
"return" (\n) (aka a newline character) is used to mark the end of a line.
"blank line" (\n\n) (aka two newline characters) is used to separate Sections. Use a blank line between a Game Section and the first Hand Section, and before each Hand Section to follow.
"double blank line" (\n\n\n) (aka three newline characters) is used to separate multiple games that exist on the same annotation. Multiple games on a single annotation/file are permitted but not encouraged. All multi-game annotations will be archived individually.
[-]
Game Section Lines return to Line List
Game Section lines express the setup and identities of the game, table, and players before the first hand is annotated. Event-related lines may not be used after Hand lines begin. Some Table-related lines may be changed (overwritten) if necessary after Hand Section lines begin. Multi-games annotations that share Event-related and/or Table-related lines only need to declare lines with new/changed values.
[-]
Hand Section Lines return to Line List
Hand Sections are sequentially ordered collections of lines. Only a few lines may be omitted from a Complete annotation. Exchange lines only need to be used by pinochle variants that include them. FinalScores and Winner lines only need to be used in the final hand of a game.
[-]
Narrative Lines return to Line List
Adding commentary to annotations using Note may be useful in some circumstances to clarify a rule or explain play. Parsers will, at most, provide a plain text area to present the text that is held within Note lines. Note lines have no bearing on whether an annotation qualifies as Complete.
[-]
Multiple-use Lines return to Line List
Some lines (including Team#, Seat#, BidSystem#, Annotator, and Note) may be used more than one time in a single game/hand. Team#, Seat#, BidSystem#, and Annotator, when used more than once, will overwrite the previous value declared by the identical label from that point until the end of the annotation or until the line is redeclared. A Note line, when used more than once, will add the new value to the end of the previous value from that point until the end of the annotation.
Event-related Line Specifications
[-]
Default: PN 1.0
Declares the notation name and version for parsing purposes.
This line may be omitted if the default value is true.
Ex
Notation PN 1.0
[-]
No default
Declares the name of the presenter of the event/game.
Ex 1
Presenter Gaming Safari
Ex 2
Presenter National Pinochle Association
[-]
Default: -
Declares the geological location, website, or application name of the event/game.
Ex 1
Location Valley City, North Dakota, USA
Ex 2
Location worldofcardgames.com
[-]
Default -
Declares the identity of the event/game. This will serve to express the name of a tournament or possibly to distinguish different variants offered by a Presenter. If a Presenter does not have a name for the event, this line may be omitted. If a Presenter offers games with varying rules, then it would be helpful to accurately name the event. *Discuss with mickmackusa for assistance regarding Event identification.
Ex
Event Great Lakes Open Tournament
Table-related Line Specifications
[-]
Default -
Declares the unique identifier for the table, determined by the Presenter.
Ex 1
Table Semi-final Round2 Table3
Ex 2
Table e3b5d123a
[-]
No default
Describes the game's date and time of commencement. Syntax is strictly "yyyy-mm-dd hh:ii:ss".
Ex
DateTime 2015-08-31 13:58:59
[-]
Default -
Declares the time contraints that are imposed on the players.
Ex
TimeControl 15m
[-]
Variant-dependent defaults.
If the game found to have 3 players:
  • Team1 Seat1
  • Team2 Seat2
  • Team3 Seat3
If the game found to have 4 players:
  • Team1 Seat1 Seat3
  • Team2 Seat2 Seat4
If the game found to have 6 players:
  • Team1 Seat1 Seat3 Seat5
  • Team2 Seat2 Seat4 Seat6

Declares the Seats assigned to each team. If the game allows players to change teams, Team# can be used in Hand lines to express the change.
Ex
Team1 Seat1 Seat3
[-]
Variant-dependent defaults.
If the game found to have 3 players:
  • Seat1 North
  • Seat2 Southeast
  • Seat3 Southwest
If the game found to have 4 players:
  • Seat1 North
  • Seat2 East
  • Seat3 South
  • Seat4 West
If the game found to have 6 players:
  • Seat1 North
  • Seat2 Northeast
  • Seat3 Southeast
  • Seat4 South
  • Seat5 Southwest
  • Seat6 Northwest

Declares the name of the player in the relative seat.
The Seat# line can be used in Hand Sections to express the replacement of a player. This line may be repeated as many times as required. Each Seat# value overwrites the previous value from that point forward.
Ex 1
Seat3 mickmackusa
Ex 2
Seat1 English, Ike
[-]
Default -
Declares a team's bidding system.
Ex 1
BidSystem1 Meld-First-Always
Ex 2
BidSystem2 Power Pinochle
[-]
Default -
Declares the person or program that created the record.
Ex 1
Annotator Finemeld, Johnny Q.
Ex 2
Annotator PNbot v2.9
Deal-related Line Specifications
[-]
No default
Declares the current deal number within the game.
This line is the first expected line for each Hand Section in an annotation.
Ex
Deal 2
[-]
No default
Declares the teams' scores prior to the start of the hand. Values start with the Team1 and progress numerically. A space is used to separate team scores.
Ex 1 (2 teams)
GameScores -54 328
Ex 2 (3 teams)
GameScores 26 9 71
[-]
No default
Declares the seat of the player who is the dealer of the hand.
Ex
Dealer Seat4
[-]
No default
Declares a player's held cards. Hand number corresponds with Seat number. A line is expected for each player at the table. If the player's hand is unknown, use a hyphen as the value.
Suit order is always alphabetical and color-alternating (C,D,S,H).
Rank order is always in accordance with pinochle hierarchy (A,T,K,Q,J,9).
Values always (and only) list each suit once, with ranks immediately following their suit letter.
Cards grouped by suit are separated by a space to benefit human readers.
If the variant includes an Exchange phase, after all cards are passed/discarded, redeclare only the Hand# lines where a change has occurred.
Ex
Hand1 CAT DATKKQQJ STKQQ HATTQQQJ
Hand2 CATTQJ DATKQQ SATKKQJJ HAAT
Hand3 CTKQQJJ DAATTKJJ STJJ HAKQJ
Hand4 CAAKKKQJ DJ SAAATKQ HTKKKJJ
Auction-related Line Specifications
[-]
No default
Declares the sequence of bids in an auction.
Bids are listed starting with the seat to the left of the Dealer.
Bids are grouped into rounds of which each player may bid only one time.
The number at the end of the label refers to the round of bidding.
Use - as a placeholder when a player is no longer active in the auction.
In accordance with Pinochle's core rules, bids must be "Pass" or a positive integer.
Ex 1
Bids1 Pass Pass Pass 50
Ex 2
Bids1 Pass 52 59 60
Bids2 - Pass 65 70
Bids3 - - Pass
[-]
No default
Declares the auction winner's seat, winning bid, and declared trump.
When variant rules dictate that no qualifying suit can be declared trump, use a hyphen (-).
Ex 1
Contract Seat4 50 -
Ex 2
Contract Seat1 150 Spades
Exchange-related Line Specifications
[-]
No default

Declares the cards passed by one player to another. Pass number corresponds to Seat number of the passer.
Cards are expressed individually and space-separated.
For variants where the pass receiving seat needs to be annotated (cards are not passed directly across the table), add a space then the seat to the end of the value.
After all cards have been passed, redeclare any Hand# that has changed.
This line may be omitted if the variant does not include passing.
Ex 1
Pass1 DJ SQ SQ
Pass3 CT CK CJ
Ex 2
Pass2 DJ SQ SQ Seat4
Pass4 CA HA HA Seat6
Pass6 SK SK HK Seat2
[-]
Kitty & Kitty# return to Line List
No default
Declares the cards in the kitty also known as the "widow".
If variant rules reveal the kitty with each round in the auction, use Kitty#, otherwise use Kitty to declare all cards in the kitty in a single declaration.
Cards are expressed individually and space-separated.
If expressing multiple cards, maintain card suit and rank ordering.
This line may be omitted if the variant does not include a kitty.
Ex 1
Kitty CT SK H9
Ex 2
Bids1 26 Pass 27
Kitty1 HA
Bids2 28 - 29
Kitty2 CJ
Bids3 Pass
Kitty3 HA
[-]
No default
Declares the cards thrown away by the player who received the Kitty.
Assuming the discard is less than five cards, the cards are expressed individually using suit-letter then rank-letter/number, and separated by a space.
Total discarded points, also known as "counters", are expressed after the cards and a space. If discarded cards are not awarded point value, provide zero as the value.
After all cards have been discarded, redeclare any Hand# that has changed.
This line may be omitted if the variant does not include discarding.
Ex 1
Discard CK DK HK 3
Ex 2
Discard DT SQ SQ 0
Meld-related Line Specifications
[-]
No default
Declares the cards and points that each player tables as meld.
Cards are expressed using grouped card syntax.
To annotate the meld of a player who tables no meld cards, space-separate the four suit letters followed by no rank letters, then a space and the number zero.
These lines may be omitted if the meld phase does not occur.
Ex 1
Meld1 CQQ DKQQ SQQ HQQJJ 94
Meld2 CK DATKQJ SKQ HKQ 27
Meld3 CJ DJ SJ HJ 4
Meld4 CKQ DATKQJ S H 17
Ex 2
Meld3 C D S H 0
Play-related Line Specifications
[-]
No default
Declares the actions in the play, also known as "trick", phase including thrown cards, trick winner, and trick points (counters).
Trick1 thrown cards start with the Declarer and progress clockwise until the trick is completed.
Trick winner and trick counters are expressed at the end of the trick and are space-separated. All tricks after Trick1 start with the Seat# declared at the end of the previous line.
These lines may be omitted if the play phase does not occur.
Ex 1
Trick1 CJ CA CQ CQ Seat1 1
Trick2 SA SJ SK SQ Seat1 2
Ex 2
Trick18 SQ SK SA SQ Seat4 2
Trick19 SQ ST ST HT Seat1 3
Trick20 ST CA HA CJ Seat2 5
Results-related Line Specifications
[-]
No default
Declares the teams' meld scores after pinochle rules have been applied.
This reflects whether there is a minimum score rule.
Teams scores are space-separated and listed numerically.
Ex 1 (2 teams)
MeldScores 21 0
Ex 2 (3 teams)
MeldScores 4 17 10
[-]
No default
Declares the teams' play scores after pinochle rules have been applied.
This reflects whether there is a minimum score rule.
Teams scores are space-separated and listed numerically.
Ex
PlayScores 31 0
[-]
Default -
Declares the score adjustments which come as the result of special rules bonuses or awards/punishments for rules infractions. This line is not to be used to declare the outcome of a unsatisfied contract. Positive/Negative teams points are space-separated and listed numerically.
If necessary, use a Note line to express why the Adjustment line was used.
Ex 1
Adjustments 25 0
Note Team1 declared Shoot-the-moon and won all tricks.
Ex 2
Adjustments 0 -25
Note Team2 declared Shoot-the-moon, but failed.
[-]
No default
Declares the teams' total scores for the current hand. Positive/Negative team scores are space-separated and listed numerically.
Ex 1 (2 teams)
HandScores 0 -75
Ex 2 (2 teams)
HandScores 81 40
Ex 3 (3 teams)
HandScores 23 22 7
[-]
No default
Declares the teams' final scores for the game. Positive/Negative team scores are space-separated and listed numerically.
This line may only occur once per game.
This line must be omitted if the game is not concluded.
Ex 1 (2 teams)
FinalScores 501 -75
Ex 2 (2 teams)
FinalScores 381 540
Ex 3 (3 teams)
FinalScores 155 72 97
[-]
No default
Declares the seat or team that won the game.
This line may only occur once per game.
This line must be omitted if the game is not concluded.
Ex 1
Winner Team1
Ex 2
Winner Seat2
Narrative Line Specifications
[-]
No default
Declares narrative information. The line may be omitted from an annotation or it may be used an unlimited amount of times and occur in any section. Note lines can be used to explain rules or to offer observations/advice during teaching.
Ex 1
Note Bots in Seat1 and Seat 3
Ex 2
Note Team1 did not table meld because they only need 13 points to win.
Ex 3
Note Seat1 has bid Aces Around, what is Seat3's reasonable bid limit?
Examples
[-]
One Hand Where Contract Is Saved return to Line List
This ficticious Incomplete annotation from worldofcardgames.com includes an optional Table reference number and player names for each seat.
[-]
One Hand With Dealer Stuck Without A Marriage return to Line List
This ficticious Incomplete annotation from playok.com includes Location, Table, and TimeControl information. The declarer does not have a marriage, so the Meld and Trick lines are omitted.
[-]
One Hand Where Offense Had Below Minimum Meld return to Line List
This is a ficticious Incomplete annotation of the last hand from a game at Games.com with no player names.
[-]
Two Games Ending In Forfeit return to Line List
This Complete human-annotated record from Steele Game Studios' YouTube Demo of the Double Deck App shows when and how games can be terminated, how narration can be included, and how to handle missing Hand#/Meld# data. Multiple games can be strung together into one record, as shown, but concatenating game records into a single record is discouraged.
[-]
A Screen-captured Video of Double-deck Partnership Pinochle return to Line List
This Incomplete human-annotated record from World of Card Games' YouTube Video entitled "double deck pinochle - I'm too chicken to bid" shows how narration can be included, and how to handle a board set and missing Hand# data. Because this video is not a full game record and doesn't include Deal lines, the annotation is deemed Incomplete. Discussion for this particular video has its own thread: "bidding frustration".
[-]
Single-deck Three-handed Pinochle return to Line List
This Complete human-annotated record from TigreLXIX shows a variant with an Exchange phase (Kitty & Discard actions) and some unique rules that are declared in Note lines in the Game Section.
This annotation is deemed Complete, but it cannot be used for credible statistical analysis because it was a manufactured (not real) game.
A more generous rundown of variant rules is available at TigreLXIX's Three-Handed Single-Deck Pinochle Rules Thread.