Introduction
[-]
Introduction
Portable Pinochle Notation (PPN) is a free, open source standard for expressing Pinochle game data. Not to be confused with Power Pinochle Notation (an early attempt, currently being used by the Hand Animator program), Portable Pinochle Notation will serve a greater audience and with greater capabilities.
[-]
Motive and Project Goals
PPN is a Power Pinochle initiative and will be championed by mickmackusa. Too long have beginners, teachers, analysts, authors, observers, statisticians, competitors, and game hosts had to operate and express themselves using tedious, long-winded, and often inaccurate accounts of real and hypothetical gameplay. PPN will act as the foundation for a revolutionary project to aid every type of Pinochle enthusiast. Upon the satisfactory completion of PPN, software will be developed to enrich, store, and serve the PPN. Initial plans include: PPN Animator, PPN Archive, and PPN Annotator
[-]
Relationship to PBN and PGN
PPN is mostly built using the guidelines specified for Portable Game Notation (PGN) and Portable Bridge Notation (PBN). While PGN sounds like an inclusive and generalized notation, it is really only used for expressing Chess data. PBN is a largely successful child of PGN. PBN is not only a well documented notation, it also accounts for a large portion of possible gameplay data that exists in Pinochle. Even with all of their similarities, Pinochle requires additional utilities to properly express differences in gameplay.
[-]
Scope of Notation
While project priority will be given to Double-deck Four-handed Pinochle, which proves to be the most popular variant. The scope of the notation shall seek to accommodate every known variant and possible use. This means that the number of players in a game may be as few as two or as many as eight. Cards can potentially be passed/acquired/discarded at a point in the game. Different scoring values and rules may exist. Games may be prematurely terminated by an infraction. Complete and incomplete game data may be expressed. Due to the volume of types of data in a game of Pinochle, the list of tags is long; in reality most games will be wholly express in 20 tags or less.
[-]
Collaboration
These provisional specifications are to be scrutinized, challenged, trialed, and modified until adequatedly refined to form "Portable Pinochle Notation 1.0". To offer constructive feedback regarding this project, please post in the forum or send a PM/Email to mickmackusa.
General Specifications
[-]
Formats: EXPORT versus IMPORT
PPN can be annotated in two formats: EXPORT and IMPORT. EXPORT format is generally used by programmatical annotators. In this format, there is an increase in mandatory values to ease readability and facilitate record archiving at the cost of greater annotator workload. IMPORT format is generally used by human annotators. In this format, mandatory tags to express a complete hand are greatly reduced to ease of annotation at the cost of readability. Regardless of format, only valid notations with adequate identifying values will be eligible for archiving.
[-]
Special Characters
% is used to mark data that is purely to assist parsers in handling data.
* is used to mark the termination of an incomplete section, or missing tag values caused by a termination.
? is used to mark unknown data.
@ is used to mark the start of a Segmental prefix.
- is used to mark the separation of the start segment value and the end segment value of a Segmental prefix.
= is used to mark the end of a Segmental prefix.
() is used to mark vital secondary data within a Tag that contains a different types of values.
[] is used to mark the start and end of a Tag, or the start of a Section.
{} is used to mark comment data which is ignored by parsers and is solely for the benefit of human readers.
" is used to mark the start and end of tag values; if a tag includes a double-quote symbol in the text, it must be escaped using a backslash immediately before the double-quote symbol.
# is used to mark a tag value that the parser should seek in the previous tag with the same name.
## is used to mark a tag value that the parser should use for all subsequent hands until otherwise declared.
[-]
Rules for Tags and Sections
Like the PBN, File Headers begin with the percent ( % ) symbol, a space, then some file identifying values (Notation Header & Format Header). File Headers have a maximum length of 255 characters and cannot contain a new line character.
Like the PBN, Tags begin and end with square brackets ( [ and ] ), and contain a tag name and a token (value). Tags have a maximum length of 255 characters and cannot contain a new line character.
Like the PBN, Sections begin with a Tag and are followed by a sequence of tokens. The Section is ended by the first non-qualifying token, like another tag or a blank line. Sections do not have a maximum length of characters and can contain a new line character.
Unlike the PBN, PPN has created Segmental Tags which exist to express values that are not present for an entire hand (like a player change or a parsable note); not all tags qualify as Segmental Tags. Segmental Tags are like normal Tags, except they are prefixed by a declaration of when the tag should be implemented and for what duration in the hand. Segmental Tags begin with an at ( @ ) symbol, then the start value, then a hyphen ( - ) and an optional end value (if not existing for the entire hand), then an equals ( = ) symbol, then a Tag.
[-]
Pinochle Hand Segments and Prefixing
With the exception of the variant-dependent "Exchange" segment, a complete hand of pinochle has the following segments.
  • Deal (D) - pertains to all players receiving their dealt hands.
  • Auction (A) - pertains to all player bids. Auctions are broken down into Rounds. Rounds are broken down into bids (one bid per player per round).
  • Exchange (X) - pertains to all passed, acquired, and discarded cards. Whether exchanging cards with a kitty or a partner, this segment has two parts.
  • Meld (M) - pertains to the meld cards and the meld scores of all players.
  • Play (P) - pertains to the play segment of the hand. Play is broken down into Tricks. Tricks are broken down into throws (one throw per player per trick).
  • Result (R) - pertains to the contract result and score calculation for the hand.

When using Segmental prefix with a tag, identify the segment by its identifying letter. By only referencing the letter, the parser will assume act on the earliest occurrence of that segment. If declaring with greater specificity, (by using Round number, Bid number, Exchange number, Trick number, or Throw number) use a dot to separate each component. See the Segmental Tag definition and examples below.
[-]
Mandatory Tag Rosters
Considering the myriad of known and unknown Pinochle variants, it is impossible to claim that a PPN parser will be able to consistently apply accurate rules and scoring to all games.
Many tags are mandatory in EXPORT format to allow the parser to handle the PPN with high fidelity, to ensure file identification, and improve human readability.
The mandatory inclusions for the most popular variant (Double-deck Four-handed Pinochle) in order are:
  • Notation Header
  • Format Header
  • a blank escaped Header line
  • [Site]
  • [Date]
  • [North]
  • [East]
  • [South]
  • [West]
  • [Hand]
  • [GameScores]
  • [Dealer]
  • [Deal]
  • [Declarer]
  • [Contract]
  • [Trump]
  • [Melds]
  • [MeldScores]
  • [PlayScores]
  • [Result]
  • [HandScores]
  • [Auction]
  • [Play]

Mandatory Tag Sets for other variants will be announced when their most popular rule and scoring conventions are fully understood.
In the case of a Termination event (a hand stops unexpectedly), all mandatory tags must still be declared, and their values should be an asterisk ( * ), a section which has been truncated should place an asterisk ( * ) in the location when the next action would have been declared to mark the point of termination.
Future software development will seek to expedite the annotation process and for well-known variants assist in fleshing out the game data from minimal input.
For instance, a standard hand of Double-deck Four-handed Pinochle that results in a Save or a Set only truly requires data from: [Dealer], [Auction], [Trump], [Play].
In the same variant, if the hand result is No Trump or No Board, then the only truly required data comes from: [Deal], [Auction].
Because IMPORT format can be used to express incomplete hands, there are no mandatory tags.
Headers, Tags, and Sections
[-]
Annotator Tag
Annotator (Optional, no default value)
Describes the person or program that created the record.
*This tag may be combined with a Segmental prefix.
Ex 1
[Annotator "Finemeld, Johnny Q."]
Ex 2
[Annotator "PPNbot v2.9"]
[-]
Auction Section
Auction (Mandatory in EXPORT)
Describes the sequence of bids.
Bids are listed starting with the seat number designated inside the Auction tag and progress clockwise until the contract is won.
For clarity, a newline character ( ) is used to separate each round of bidding.
Ex
[Auction "E"]
Pass 52 59 60
- Pass 65 70
- - Pass
[-]
BidSystem Tags
BidSystem{TeamNumber} (Optional, no default value)
Describes a team's bidding system.
In the absense of official bidding system names, any textual value will be valid.
Ex 1
[BidSystem1 "Strength-First-Always"]
Ex 2
[BidSystem2 "CABS"]
[-]
Chat Tag
Chat (Optional, no default value)
Describes player dialogue that actually occurred in the game.
This tag can be used multiple times per hand.
*This tag may be combined with a Segmental prefix.
Ex 1
@P.19.3-R=[Chat "N:good game everyone"]
@P.19.4-R=[Chat "E:gga"]
@P.20.1-R=[Chat "S:gg"]
@P.20.2-R=[Chat "W:ty gg"]
Ex 2
@M-P=[Chat "N:Um, p... I bid a DoubleRun, why did you continue to bid!?!"]
[-]
Competition Tag
Competition (Optional, value defaults to "Double-deck Four-handed")
Describes the exact type of Pinochle.
Possible values include: "Single-deck Three-handed", "Triple-deck Six-handed", "Double-deck Passing", and more
For clarity, it is recommended to start the value with the number of decks being used, then specify further details as necessary. In the absense of a standard set of variant names, any textual expression will be valid.
Ex 1
[Competition "Double-deck Four-handed"]
Ex 2
[Competition "Single-deck Two-handed"]
[-]
Contract Tag
Contract (Mandatory in EXPORT)
Describes the winning bid from the Auction.
Ex
[Contract "65"]
[-]
Date Tag
Date (Mandatory in EXPORT)
Describes the game's date of commencement. Syntax is strictly "YYYY.MM.DD".
Ex
[Date "2015.08.31"]
[-]
Deal Tag
Deal (Mandatory in EXPORT)
Describes the cards dealt to each player.
The value syntax begins with the seat letter(s) of the player to the Dealer's left, followed by a colon ( : ). Then a dot separated expression of all cards dealt to the first seat is given. 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). Separated by a space and progressing clockwise each player's cards are given in the same manner.
Ex
[Deal "E:ATTTQQJ.QQJJ.AQQQJ.TKQQ KQQJJ.TKKKKQ.AK.AATKQJJ TKJ.AAAATTJJ.AATTKJJ.KJ AAAKK.TQ.TTKKQJ.AATTKQJ"]
[-]
Dealer Tag
Dealer (Mandatory)
Describes the seat of the player who is the dealer of the hand.
Ex
[Dealer "N"]
[-]
Declarer Tag
Declarer (Mandatory in EXPORT)
Describes the seat of the player who has won the contract.
Ex
[Declarer "W"]
[-]
Discard Tag
Discard (Mandatory if in variant)
Describes the cards thrown away by the player who received the Kitty.
Cards are expressed using dot-separated syntax (like Deal & Meld)
Points (if applicable) in the Kitty are expressed inside parentheses after the cards. If discarded cards are not awarded point value, provide zero as the value.
Ex 1
[Discard "K.K..K (3)"]
Ex 2
[Discard ".T.QQ. (0)"]
[-]
Event Tag
Event (Optional, no default value)
Describes the name of the tournament.
Ex
[Event "Great Lakes Open Tournament"]
[-]
Format Header
Format (Mandatory)
Describes the notation style of the file. The value is either IMPORT OR EXPORT.
IMPORT format is generally used by human annotators. In this format, mandatory tags are greatly reduced to ease of annotation at the cost of readability.
EXPORT format is generally used by automated annotators. In this format, mandatory tags are increased to ease readability at the cost of annotator workload.
Ex 1
% EXPORT
Ex 2
% IMPORT
[-]
GameScores Tag
GameScores (Mandatory in EXPORT, Optional in IMPORT, values default to 0)
Describes the teams' scores prior to the start of the hand. Values start with the team containing the North seat, progress clockwise, and are separated by a colon.
Non-partnership variants shall consider each player to be a team containing one player.
Ex 1 (2 teams)
[GameScores "-54:328"]
Ex 2 (3 teams)
[GameScores "26:9:71"]
[-]
Hand Tag
Hand (Mandatory in EXPORT)
Describes the number of the current hand within the game.
Ex
[Hand "2"]
[-]
HandScores Tag
HandScores (Mandatory in EXPORT, Optional in IMPORT, parser will attempt to calculate values if omitted)
Describes the teams' final scores for the current hand. Values start with the team containing the North seat, progress clockwise, and are separated by a colon.
Three-handed pinochle shall be considered to have 3 teams (1 player on each team).
Ex 1 (2 teams)
[HandScores "0:-75"]
Ex 2 (3 teams)
[HandScores "23:22:7"]
[-]
Holding Tag
Holding (Mandatory if in variant)
Describes the cards held by each player at the completion of the Exchange Segment.
Syntax is identical to the Deal tag.
Ex
[Holding "E:ATTTTKJQQJ.QQJ.AQJ.TKQQ KKQQJJ.TTKKKKQQ.K.TKQJJ .AAAATTJJJ.AATTKQQJJ.KJ AAAK..ATTKKQJ.AAAATTKQJ"]
[-]
ID Header
ID (Optional)
Describes the identifying value set by the annotator for future reference to the file. The value is not quoted, it is terminated by an end-of-line.
Ex
% ID 4a9c345d1e092b
[-]
Kitty Tag
Kitty (Mandatory if in variant)
Describes the cards in the kitty also known as the "widow".
Cards are expressed using SuitRank syntax (like the Play Section).
Ex 1
[Kitty "SK H9 CT"]
Ex 2
[Kitty "HA CJ HA"]
[-]
Language
Language (Optional, value defaults to en-US)
Describes the language used in the notation.
Ex
[Language "pt-BR"]
[-]
Melds Tag
Melds (Mandatory in EXPORT)
Ex
[Melds "N:QQ.KQQ.QQ.QQJJ(94) K.ATKQJ.KQ.KQ(27) J.J.J.J(4) KQ.ATKQJ(17)"]
[-]
MeldScores Tag
MeldScores (Mandatory in EXPORT)
Describes the team meld scores after Pinochle rules have been applied
This reflects whether there is a minimum score rule.
Teams are always ordered clockwise starting with the team containing the North player.
Ex 1 (2 teams)
[MeldScores "21:0"]
Ex 2 (3 teams)
[MeldScores "4:17:10"]
[-]
Notation Header
Notation (Mandatory)
Describes the file's notation name and its version number.
Ex
% PPN 1.0
[-]
Note Tag
Note (Optional, no defalut value)
Describes text that should be parsed and displayed during animation, but does not represent actual game data.
This tag should be used by teachers/narrators that wish to highlight an occurrence via a textual expression.
This tag can be used multiple times per hand.
*This tag may be combined with a Segmental prefix.
Ex 1
@A.3.2-M=[Note "South's partner has communicated Aces Around and 20 meld points, what is South's reasonable bid limit?"]
Ex 2
[Note "Team1 is just 23 points from winning the game, they may consider withholding their meld and coasting out."]
[-]
Partner Tag
Partner (Mandatory if in variant)
Describes the player who was selected as Partner by the Declarer and the requested card that determined the Partner.
Some 5-handed Pinochle discussions
Ex 1
[Partner "SE:HA"]
Ex 2
[Partner "N:SQ"]
[-]
Passed Tag
Passed (Mandatory if in variant)
Describes the cards passed to a Partner.
If all players exchange cards, passing is listed starting with the player on the Dealer's left and progresses clockwise. If not all players pass cards, the Declarer is listed first and progresses clockwise. The tag value begins with the seat of the first passing player, then a colon, then the cards
Cards are expressed using dot-separated syntax (like Deal & Meld). A space separates each players' passed cards.
Ex
[Passed "E:.J.QQ. ..A.AA TKJ... K.TQ.."]
[-]
Play Section
Play (Mandatory in EXPORT)
Describes the sequence of cards thrown in the Play segment.
Thrown cards are listed starting with the seat number designated inside the Play tag and progress clockwise until the trick is completed.
TrickWinner and TrickPoints are expressed at the end of the trick inside of parentheses.
For clarity, a newline character ( ) is used to separate each trick.
Ex
[Play "S"]
CA CJ CK CJ (S2)
DQ DT DJ DT (W2)
HA HJ HK HQ (W2)
HA HJ HK SK (S3)
DQ DA DJ DQ (W1)
CA CK CA CJ (W3)
CA CT CQ CJ (W2)
CK CT CQ CT (N3)
HT HA SJ HJ (S2)
DJ DA DK DJ (W2)
CK CT CQ CQ (N2)
DT ST DK DK (E4)
HT SQ HJ HA (S2)
DK DA ST SA (E4)
SQ ST SK SA (N3)
HQ HT ST HQ (S2)
SA HK SK SJ (S3)
DT DA SK SA (E4)
HT SQ HK HQ (S2)
SQ DQ SJ SJ (S2)
[-]
PlayScores Tag
PlayScores (Mandatory in EXPORT)
Describes the team play scores after Pinochle rules have been applied.
This reflects whether there is a minimum score rule.
Teams are always ordered clockwise starting with the team containing the North player.
Ex
[PlayScores "31:0"]
[-]
Result Tag
Result (Mandatory in EXPORT)
Describes the contract outcome term.
Possible values are: "Saved", "Set", "No Board", "No Trump"
Ex
[Result "Saved"]
[-]
Round Tag
Round (Optional, no default value)
Describes the round of a tournament.
Ex
[Round "3"]
[-]
Room Tag
Room (Optional, no default value)
Describes the room type of a game.
Expected values are either "Open" or "Closed" in expressing whether kibitzing/observing is permitted.
Ex 1
[Room "Open"]
Ex 2
[Room "Closed"]
[-]
Scoring Tag
Scoring (Optional, no default value)
Describes the scoring system in relation to meld points. Possible values may include: "Standard", "National Pinochle Association", "DoubleDeck.com", "GrandPrix Tournaments", "Yahoo.com". The "Standard" value is used to describe the most popular meld scoring system across most modern digital Double-Deck Partnership Pinochle platforms. Known Scoring Charts can be viewed at the Meld Calculator page.
Ex 1
[Scoring "National Pinochle Association"]
Ex 2
[Scoring "Standard"]
[-]
Seat Tags
{Seat} (Mandatory in EXPORT, Optional in IMPORT, value defaults to "{CompassDirection}")
Describes the name of the player in the relative seat.
Regardless of the number of players at the table, there must always be a North seat. Seat naming progresses clockwise.
2-player games must use: North(N),South(S)
3-player games must use North(N),Southeast(SE),Southwest(SW)
4-player games must use North(N),East(E),South(S),West(W)
5-player games must use North(N),Northeast(NE),Southeast(SE),Southwest(SW),Northwest(NW)
6-player games must use: North(N),Northeast(NE),Southeast(SE),South(S),Southwest(SW),Northwest(NW)
7-player games must use: North(N),Northeast(NE),East(E),Southeast(SE),Southwest(SW),West(W),Northwest(NW)
8-player games must use: North(N),Northeast(NE),East(E),Southeast(SE),South(S),Southwest(SW),West(W),Northwest(NW)
*This tag may be combined with a Segmental prefix to describe the changing of a player in a specific seat.
Ex 1
[East "mickmackusa"]
Ex 2
[South "English, Ike"]
[-]
SeatType Tags
{Seat}Type (Optional, value defaults to "human")
Describes the player as "human" or "program" in the relative seat.
Regardless of the number of players at the table, there must always be a North seat. Seat naming progresses clockwise.
2-player games must use: North(N),South(S)
3-player games must use North(N),Southeast(SE),Southwest(SW)
4-player games must use North(N),East(E),South(S),West(W)
5-player games must use North(N),Northeast(NE),Southeast(SE),Southwest(SW),Northwest(NW)
6-player games must use: North(N),Northeast(NE),Southeast(SE),South(S),Southwest(SW),Northwest(NW)
8-player games must use: North(N),Northeast(NE),East(E),Southeast(SE),South(S),Southwest(SW),West(W),Northwest(NW)
*This tag may be combined with a Segmental prefix to describe the changing of a player type in a specific seat.
Ex 1
[SoutheastType "human"]
Ex 2
[NorthType "program"]
[-]
Site Tag
Site (Mandatory in EXPORT)
Describes the web address of an online game or the physical location of an offline game.
Ex 1
[Site "GamingSafari.com"]
Ex 2
[Site "Valley City, North Dakota, USA"]
[-]
Stage Tag
Stage (Optional, no default value)
Describes the stage of a multi-stage tournament.
Ex 1
[Stage "Preliminary"]
Ex 2
[Stage "Semifinal"]
[-]
Termination Tag
Termination (Conditional)
Describes the responsible seat number and the cause of an untimely end to a hand.
The seat value can be the seat letter(s) or a hyphen when no individual seat is responsible (for instance, all players unanimously decide to end game). Possible cause values include: "Time out", "Abandoned", "Reneged"
Ex 1
[Termination "W:Time out"]
Ex 2
[Termination "-:Abandoned"]
[-]
TimeControl Tag
TimeControl (Optional, no default value)
Describes the time contraints that are imposed on the players.
Ex
[TimeControl "15 min per player per game"]
[-]
Trump Tag
Trump (Mandatory in EXPORT)
Describes the suit that the Declarer has named dominant for the hand.
Values are: "C" for Clubs, "D" for Diamonds, "S" for Spades, "H" for Hearts, and "-" for when Declarer has no marriages.
Ex 1
[Trump "H"]
Ex 2
[Trump "-"]
[-]
Victor Tag
Victor (Optional)
Describes the player/team that won the game.
This tag is necessary due to the different rules and scoring of pinochle variants.
Victors are expressed by team number. Teams may have as few as one player on them. Team 1 is always the team containing North, team numbering progresses clockwise until all teams are assigned a number.
Ex 1
[Victor "1"]
Ex 2
[Victor "2"]
Examples
[-]
Double-Deck Four-Handed Pinochle
This ficticious example (actual game data and names have been replaced to protect the innocent) of a programmatically annotated hand from playok.com in EXPORT format shows the first hand of a game where Team 1 was rakbeater and richardpaulhall and Team 2 was hitormiss49 and tony ennis.
This example uses all mandatory tags, no optional tags, and a gratuitous, optional, non-parsable Comment containing a Bridge-style diagram of the dealt cards.
  • rakbeater started the bidding and called a 58 Meld Bid based largely on Double Queens Around.
  • richardpaulhall was not able to vie for declarership as he didn't have a marriage, and the contract was won by tony ennis of Team 2.
  • Conveniently, both players on Team 2 had a run in Hearts.
  • tony ennis declared Hearts as trump and decided to attack Team 1's trump by leading the Queen of Hearts on Trick 1.
  • rakbeater beat the Queen with a King, which was then beaten by hitormiss49's Ace.
  • richardpaulhall threw a Jack and the trick was raked toward hitormiss49 in the East seat -- Team 2 now had two points from Tricks.
  • hitormiss49 was the leader for Trick 2, 3, and 4.
  • With all Aces played, hitormiss49 led a King of Trump on Trick 4 hoping to either draw an Ace of Trump or at least a point from richardpaulhall.
  • Instead of receiving a point card, hitormiss49 received information -- richardpaulhall had run out of Trump.
  • tony ennis cheaply won the Trick 4 with a Ten and proceeded to cash Club Aces for the next three tricks.
  • At Trick 8, tony ennis exited with a King of Club perhaps hoping that hitormiss49 would ruff it, but rakbeater was able to win the trick with a Ten.
  • rakbeater began Trick 9 with his last Heart which tony ennis had no trouble winning.
  • tony ennis tried again to point-load a trick for hitormiss49 to trump, but rakbeater raked the trick.
  • After ten tricks Team 1 had just 6 points from 2 tricks, and Team 2 had 16 points from 8 tricks.
  • With Team 2's cache of non-trump Aces spent, they could only aspire to saw off Team 1's Aces with their remaining trump cards.
  • rakbeater threw a Club attracting both opponents to trump in wastefully on Trick 11.
  • tony ennis exited in Spades to find rakbeater regaining control.
  • rakbeater tossed another Club and again the trick featured two trump cards from the opposition.
  • Trick 14 gave some relief to tony ennis when hitormiss49 finally laid a trump.
  • From Trick 15 to 18, richardpaulhall had his moment to shine by firing his Aces.
  • However, come Tricks 19 and 20, richardpaulhall's Aces turned to dust under the Trump and good Spade of tony ennis.
  • This hand had a tragic outcome for Team 1 who initially stood to score over 100 points only to rake 18 counters in the Play round and wind up scoring 0 for the hand!
  • Team 2 smiled all the way to the scoreboard after exceeding their contract-winning bid of 65, saving their meld, and freezing their opponents.