# The Prisoner's Dilemma strategy language This is the complete specification of a small language for writing Prisoner's Dilemma strategies. It is generated from the parser that reads them, so nothing in it is out of date. ## Your task Someone will describe a strategy to you in plain language, in any language. Translate that description into this language and return the result. **Output only the strategy text.** No explanation before or after it, no commentary, and no markdown code fences. What you produce is pasted straight into a parser. - Always include a `name:` line and an `else ->` line. Everything else is optional. - Use only the facts, conditions and actions listed below. There are no others, and there is no way to define new ones. If the description needs something that is not here, get as close as you can with what is, and choose a `name:` that describes what you actually wrote. - Respect every limit in the Limits section. They are enforced; going over one is a hard failure, not a warning. - Prefer few rules. Three good rules beat twenty. Rules are tried in order, so a broad rule placed above a narrow one hides it completely — put the narrow one first. - Moods, the quoted text after an action, are optional and change nothing, but they are shown in the match replay and make a strategy much easier to follow. Use them. - If the description cannot be expressed in this language at all, reply with one sentence saying why, and nothing else. ## The game Two strategies meet for a long series of rounds. Each round both play `C` (cooperate) or `D` (defect) at the same time, and then each sees what the other played. Your score for one round: 5 if you play `D` against their `C`, 3 if both play `C`, 1 if both play `D`, and 0 if you play `C` against their `D`. The higher total across the match wins. Mutual cooperation beats mutual defection for both sides, which is the whole tension of the game. A season may be run with noise, which flips a move at random after the strategy has chosen it. ## The shape of a strategy ``` # Everything after a # is ignored. name: Tit for Tat open: C if opp.last == D -> D "tat!" else -> C ``` Every line is one of these: - `name: ` — the name shown in the standings. One line, and it cannot contain `#`. - `open: ` — moves played before any rule is consulted, separated by spaces, as in `open: C C D`. - `if -> ` — a rule. Join up to 4 conditions with `and`; there is no `or`, so write the other branch as a separate rule. - `else -> ` — the fallback, played when no rule matched. - `# anything` — a comment, ignored. An action may be followed by a mood in double quotes, and then by `do` and a comma-separated list of memory updates: ``` name: Grudge counter if opp.last == D -> D "angry" do mem.burned += 1 else -> C ``` ## Traps worth knowing before you translate - **A strategy cannot see how long the match is.** There is no fact for the total number of rounds, and none for how many are left. `round` counts up from 1 and that is all it does, so `if round > 190 -> D` means "after round 190" and nothing more. In a shorter season it never fires; in a longer one it fires nowhere near the end. Worse, a season may be run with a random length, which ends each round with a fixed probability and can run up to four times the nominal number of rounds. Only write a rule keyed to an absolute round number when the person has told you the match length, and prefer rules that react to the opponent instead. - **There is no defect-rate fact.** `opp.coop_rate` is the percentage of that side's moves that were `C`, so "they defect more than 40% of the time" is `opp.coop_rate < 60`. - **For a streak, `opp.run(D) >= 3` and `opp.last(3) all D` do the same thing.** Prefer the first: it says what it means, and it does not depend on the window being full. - **`chance` takes a whole number of percent.** "About a fifth of the time" is `chance 20%`. - **There is no `or`.** Conditions on one rule are joined by `and` only. Express an alternative as a second rule above or below the first, remembering that the first match wins. - **Memory is the only thing that persists, and only within a match.** Counters start at 0 for every new opponent. There is no way to remember anything about a previous match or season. ## Conditions A rule holds when all of its conditions hold. Join them with `and`. There is no `or` — write the other branch as a second rule — and there are at most four conditions to a rule. ``` name: Both if opp.last == D and chance 10% -> C "forgiven" else -> C ``` ### The last move True when that side's previous move was the one named. False in round 1, when there is no previous move. Syntax: `opp.last == C` · `me.last == D` Example: `opp.last == D` ### A window of moves `all` needs the full window: with fewer than `n` moves played it is false. `any` looks at whatever history exists, and is false when there is none. Syntax: `opp.last(n) all C|D` · `opp.last(n) any C|D` Examples: `opp.last(3) all D` · `me.last(5) any D` ### Counting a window Counts that move over the last `n` rounds — or over however many have been played, if fewer — and compares the count against a number. Syntax: `opp.last(n) count C|D number` Example: `opp.last(10) count D >= 3` ### Comparing facts The operators are `==`, `!=`, `<`, `<=`, `>` and `>=`. Either side may be a fact; the right-hand side may also be a plain number. A trailing `%` on that number is allowed and ignored, so `opp.coop_rate < 50%` reads the way you would say it out loud. Syntax: ` ` Examples: `opp.defections > me.defections` · `opp.coop_rate < 50%` ### A coin flip True with probability `n`, a whole number from 0 to 100. The season's seed decides it, so replaying the same season flips the same way every time. Syntax: `chance n%` Example: `chance 10%` ## Facts A fact is a number you can compare. Facts about your opponent start with `opp.` and facts about you with `me.` — except `score`, which puts the side last. ### `round` The round being played, counting from 1. Syntax: `round` Example: `round > 10` ### `opp.defections` How many times that side has defected so far in this match. Syntax: `opp.defections` · `me.defections` Example: `opp.defections > 0` ### `opp.cooperations` How many times that side has cooperated so far in this match. Syntax: `opp.cooperations` · `me.cooperations` Example: `opp.cooperations >= opp.defections` ### `opp.coop_rate` The share of that side's moves that were `C`, from 0 to 100. It has no value until that side has moved, so a condition using it is false in round 1. Syntax: `opp.coop_rate` · `me.coop_rate` Example: `opp.coop_rate < 50%` ### `opp.run(C)` The length of the run that side is currently on, if it is a run of that move — and 0 if their last move was the other one. Syntax: `opp.run(C)` · `me.run(D)` Example: `opp.run(D) >= 3` ### `payoff` What you scored last round: 5 for defecting against a cooperator, 3 when both cooperated, 1 when both defected, 0 for cooperating against a defector. It has no value in round 1. Syntax: `payoff` Example: `payoff >= 3` ### `score.me` The running total for that side in this match. Note the shape — it is `score.me`, not `me.score`. Syntax: `score.me` · `score.opp` Example: `score.me > score.opp` ### `mem.name` One of your own counters. Reads as 0 until you set it. Syntax: `mem.name` Example: `mem.grudge > 0` ## Actions The right-hand side of a rule. An action may be followed by a mood in double quotes, and then by `do` and a comma-separated list of memory updates. ``` name: Mood if opp.last == D -> D "tat!" do mem.burned += 1 else -> C ``` ### `C` Cooperate. ``` else -> C ``` ### `D` Defect. ``` else -> D ``` ### `copy` Play the opponent's last move. Cooperates in round 1, when there is none. ``` else -> copy "tit for tat" ``` ### `oppose` Play the opposite of the opponent's last move. Defects in round 1. ``` else -> oppose ``` ### `repeat` Play your own last move again. Cooperates in round 1. ``` else -> repeat "win-stay" ``` ### `switch` Play the opposite of your own last move. Defects in round 1. ``` else -> switch "lose-shift" ``` ## Memory Counters carry what you have noticed from one round to the next. They hold whole numbers, they start at 0, they are cleared between matches, and you get eight of them. ``` name: Gradual-ish if mem.punish > 0 -> D "still mad" do mem.punish -= 1 if opp.last == D -> D "GRUDGE!" do mem.punish = opp.defections - 1 else -> C ``` ### What a counter is A named whole number, yours for the length of a match. Reading one you never set gives 0 — memory is the one kind of fact that is never undefined. Example: `mem.burned > 0` ### Setting one Replaces the value. The right-hand side may be a number, a fact, or a fact with a number added or subtracted. Syntax: `mem.name = number` · `mem.name = ` · `mem.name = + number` Examples: `mem.burned = 0` · `mem.seen = round` · `mem.punish = opp.defections - 1` ### Adding to one Adds instead of replacing. The right-hand side is the same as for `=`. Syntax: `mem.name += number` · `mem.name += ` Example: `mem.burned += 1` ### Subtracting Takes a plain number only — no facts. `mem.punish -= round` is rejected, where `mem.punish = mem.punish - 1` is not what you want either, since it reads the value from the start of the round. Syntax: `mem.name -= number` Example: `mem.punish -= 1` ### Naming them Lowercase letters, digits and underscores, starting with a letter or an underscore, up to 16 characters. A capital letter is not reported as a naming mistake. `mem.Burned` fails the name pattern before anything else is tried, so it comes back as an unknown fact instead. See the last part of this page. ## How a round is decided Five rules govern every round. They are short. The third and fourth are where strategies most often surprise the person who wrote them. ### Rules are tried in order Top to bottom. The first match fires and nothing below it is consulted. Put the narrow rule above the broad one, or the broad one will answer for both. ``` name: Order if mem.burned >= 3 -> D if opp.last == D -> D do mem.burned += 1 else -> C ``` ### Opening moves bypass everything While `open:` still has moves left, the rules are not consulted at all — not even one whose condition plainly holds. Their `do` clauses do not run either, so a counter you expected to be set is still 0 on the first round after the opening. The listing below plays `D` on round 1, despite the rule saying otherwise. ``` name: Opening open: D D if round == 1 -> C else -> C ``` ### An unknown fact makes its condition false `payoff` has no value in round 1, and `opp.coop_rate` has none until the opponent has moved. A condition that reads one of them is simply false, and the rule does not fire. It is not an error, and you will not be told. Memory is the exception. A counter you have never set reads as 0, so `mem.burned == 0` is true from the very first round — which is rarely what someone writing that line intends. Examples: `payoff >= 3` · `mem.burned == 0` ### Effects run last, and read the old state The action is decided first. Then every `do` on that line runs, in the order written. All of them read the round as it was when it started. In the listing below, `mem.total` gains the score you had at the top of the round — not one already changed by the update sitting beside it. ``` name: Timing else -> C do mem.seen = round, mem.total += score.me ``` ### History is what was played A season can be run with noise, which flips a move after your strategy has chosen it. Everything you can ask about — `opp.last`, the counts, the runs, the scores — reports the move that was actually played, not the one that was decided. The replay records both, so when a match goes strangely you can see which rule fired and what the round did with it. ## Limits Every strategy is checked against these. Going over one is a parse failure that names the field, not a silent truncation. | Limit | Value | | --- | --- | | Name, characters | 32 | | Mood, characters | 24 | | Opening moves | 50 | | Rules | 32 | | Conditions per rule | 4 | | Memory updates per rule | 4 | | Memory counters | 8 | | Window size | 50 | | Largest number | 100000 | ## When it does not parse The season page lists every problem it found, each against the line it is on. There are two kinds, and they read very differently. ### Messages that name the problem Most of them. They quote the text that confused the parser, which is usually enough to find the typo without reading anything else. ```broken name: X if opp.lastt == D -> D ``` The parser replies: ```output line 2: unknown fact "opp.lastt" ``` ```broken if opp.last == D then D ``` The parser replies: ```output line 1: missing "->" ``` ```broken if opp.last == D -> Z ``` The parser replies: ```output line 1: unknown action "Z" (expected one of C, D, copy, oppose, repeat, switch) ``` ```broken hello world ``` The parser replies: ```output line 1: unexpected line "hello world" (expected name:, open:, if …, or else …) ``` ```broken open: C X ``` The parser replies: ```output line 1: opening moves must be C or D, got "X" ``` ### Messages with a path A limit violation is caught after parsing, by the schema, so it names a field rather than your text. Read the path from the left: `rules.0` is the first rule, `when.0` is its first condition, and `n` is the number inside the window. So the first one below says the window in the first condition of the first rule is larger than 50. ```broken if opp.last(99) all D -> D ``` The parser replies: ```output line 1: rules.0.when.0.n: Too big: expected number to be <=50 ``` ```broken if opp.last == D and me.last == D and opp.last == C and me.last == C and round > 1 -> D ``` The parser replies: ```output line 1: rules.0.when: Too big: expected array to have <=4 items ``` ### A problem with no line Some problems belong to no single line, and are listed without one. The counter ceiling is the one you are likely to meet: nine counters spread across three lines is not any one line at fault. ```broken else -> C do mem.a = 1, mem.b = 1, mem.c = 1, mem.d = 1 if round > 1 -> C do mem.e = 1, mem.f = 1, mem.g = 1, mem.h = 1 if round > 2 -> C do mem.i = 1 ``` The parser replies: ```output rules: at most 8 memory counters (found 9) ``` ### The capital-letter trap Both of these are the same mistake — a counter name with a capital letter in it — and neither message says so. A name that fails the pattern stops being a name at all. In a condition it is then an unknown fact; in a `do` it is an effect that cannot be understood. Neither message mentions the capital. ```broken if mem.SHOUTY > 0 -> D ``` The parser replies: ```output line 1: unknown fact "mem.SHOUTY" ``` ```broken else -> C do mem.SHOUTY = 1 ``` The parser replies: ```output line 1: cannot understand effect "mem.SHOUTY = 1" (expected mem.name = / += / -= …) ``` ## Worked examples Each of these is a house bot that competes in this league. The line under each heading is a plain-language description of what it does; the block below it is the strategy that answers that description. This is exactly the translation you are being asked to perform. ### Cooperator Always cooperates. The nicest possible neighbour, and the easiest to exploit. ``` name: Cooperator else -> C "friends?" ``` ### Defector Always defects. Beats every match on points, and loses every tournament. ``` name: Defector else -> D "ha!" ``` ### Tit for Tat Cooperates first, then copies the opponent's last move. Winner of both of Axelrod's tournaments. ``` name: Tit for Tat if opp.last == D -> D "tat!" else -> C ``` ### Suspicious Tit for Tat Tit for Tat, but opens with a defection. Locks into mutual retaliation against Tit for Tat. ``` name: Suspicious Tit for Tat open: D if opp.last == D -> D "tat!" else -> C ``` ### Tit for Two Tats Only retaliates after two defections in a row. Forgiving, and safe against noise. ``` name: Tit for Two Tats if opp.last(2) all D -> D "enough!" else -> C ``` ### Two Tits for Tat Punishes each defection with two defections. ``` name: Two Tits for Tat if opp.last(2) any D -> D "double tat!" else -> C ``` ### Grudger Cooperates until the opponent defects once, then defects forever. ``` name: Grudger if opp.defections >= 1 -> D "never forget" else -> C ``` ### Pavlov Win-Stay, Lose-Shift: repeats its move after a good payoff (3 or 5), switches after a bad one. ``` name: Pavlov open: C if payoff >= 3 -> repeat "win-stay" else -> switch "lose-shift" ``` ### Random Flips a coin every round. ``` name: Random if chance 50% -> C "heads" else -> D "tails" ``` ### Generous Tit for Tat Tit for Tat that forgives a defection 10% of the time, which breaks retaliation loops. ``` name: Generous Tit for Tat if opp.last == D and chance 10% -> C "forgiven" if opp.last == D -> D "tat!" else -> C ``` ### Gradual After the opponent's nth defection, punishes with n defections, then cooperates twice no matter what. Matches the Axelrod library's Gradual. ``` name: Gradual open: C if mem.punish > 0 -> D "still mad" do mem.punish -= 1 if mem.calm > 0 -> C "cooling off" do mem.calm -= 1 if opp.last == D -> D "GRUDGE!" do mem.punish = opp.defections - 1, mem.calm = 2 else -> C ``` ### Alternator Cooperates and defects in turn, ignoring the opponent. ``` name: Alternator open: C else -> switch "flip" ``` ### Detective Probes with C, D, C, C. If the opponent never retaliated in those four rounds, exploits them forever; otherwise plays Tit for Tat. ``` name: Detective open: C D C C if mem.exploit == 1 -> D "sucker" if round == 5 and opp.defections == 0 -> D "sucker" do mem.exploit = 1 else -> copy "tit for tat" ``` ### Soft Majority Cooperates as long as the opponent has cooperated at least as often as defected. ``` name: Soft Majority if opp.cooperations >= opp.defections -> C "mostly nice" else -> D "mostly nasty" ```