feat: new casino game: plinko

7 files changed, 497 insertions, 4 deletions

diff --git a/internal/game/blackjack_rules.go b/internal/game/blackjack_rules.go
index 9e36466..f163fb8 100644
--- a/internal/game/blackjack_rules.go
+++ b/internal/game/blackjack_rules.go
@@ -30,6 +30,10 @@ func (g *Game) lookRouletteTable(sess *net.Session, target string) bool {
 	return g.lookCasinoTable(sess, target, casino.GameRoulette)
 }
 
+func (g *Game) lookPlinkoTable(sess *net.Session, target string) bool {
+	return g.lookCasinoTable(sess, target, casino.GamePlinko)
+}
+
 func (g *Game) lookPaiGowTable(sess *net.Session, target string) bool {
 	return g.lookCasinoTable(sess, target, casino.GamePaiGow)
 }
diff --git a/internal/game/casino.go b/internal/game/casino.go
index 6dce0bd..15e3b6a 100644
--- a/internal/game/casino.go
+++ b/internal/game/casino.go
@@ -707,14 +707,15 @@ func (g *Game) casinoBoardReminder(sess *net.Session, category string, menu *cas
 	}
 	_, isCraps := snapshot.(*casino.CrapsSnapshot)
 	_, isPoker := snapshot.(*casino.VideoPokerSnapshot)
+	_, isPlinko := snapshot.(*casino.PlinkoSnapshot)
 	_, isPaiGow := snapshot.(*casino.PaiGowSnapshot)
 	b, isBigSix := snapshot.(*casino.BigSixSnapshot)
 	isBigSix = isBigSix && b.Phase != "playing" && b.Phase != "result"
 	s, isRoulette := snapshot.(*casino.RouletteSnapshot)
-	if !isPoker && !isCraps && !isPaiGow && !isBigSix && (!isRoulette || s.Phase == "playing" || s.Phase == "result") {
+	if !isPlinko && !isPoker && !isCraps && !isPaiGow && !isBigSix && (!isRoulette || s.Phase == "playing" || s.Phase == "result") {
 		return "", false
 	}
-	if !isPoker && !isCraps && !isPaiGow && !isBigSix && sess.Player.OptionString("casino_display") == "compact" && (menu.Repeat || !menu.ShowBalance) {
+	if !isPlinko && !isPoker && !isCraps && !isPaiGow && !isBigSix && sess.Player.OptionString("casino_display") == "compact" && (menu.Repeat || !menu.ShowBalance) {
 		// The compact reminder is already a short block; leave it intact.
 		return "", false
 	}
@@ -741,6 +742,9 @@ func composeTableThenReminder(table, reminder string) string {
 // renderCasinoMessage colorizes a casino message unless it is an
 // already-composed structured menu.
 func (g *Game) renderCasinoMessage(sess *net.Session, category string, menu *casino.MenuView, message string) string {
+	if message == "" {
+		return ""
+	}
 	if category == "casino_menu" && menu != nil {
 		return message
 	}
@@ -797,6 +801,8 @@ func (g *Game) renderCasinoSnapshot(sess *net.Session, snapshot casino.Snapshot)
 	// how verbose the command menus are.
 	size := sess.Player.OptionInt("card_size")
 	switch s := snapshot.(type) {
+	case *casino.PlinkoSnapshot:
+		return renderPlinko(s, mode, unicode)
 	case *casino.PaiGowSnapshot:
 		return renderPaiGow(s, mode, unicode, size, sess.Player.OptionString("card_style"), g.CardArt)
 	case *casino.VideoPokerSnapshot:
diff --git a/internal/game/cmd_registry.go b/internal/game/cmd_registry.go
index 5b60118..d8cc18f 100644
--- a/internal/game/cmd_registry.go
+++ b/internal/game/cmd_registry.go
@@ -38,6 +38,12 @@ var commandRegistry = map[string]commandDef{
 		}
 		g.executeTableAction(s, "deal")
 	}, ClassActive},
+	"difficulty": {func(g *Game, s *net.Session, args []string, _ string) {
+		g.executeTableAction(s, "difficulty "+strings.Join(args, " "))
+	}, ClassInstant},
+	"balls": {func(g *Game, s *net.Session, args []string, _ string) {
+		g.executeTableAction(s, "balls "+strings.Join(args, " "))
+	}, ClassInstant},
 	"paytable": {func(g *Game, s *net.Session, _ []string, _ string) { g.executeTableAction(s, "paytable") }, ClassInstant},
 	"denom": {func(g *Game, s *net.Session, args []string, _ string) {
 		g.executeTableAction(s, "denom "+strings.Join(args, " "))
@@ -249,6 +255,7 @@ var casinoCommonVerbs = []string{"watch", "game", "table", "list", "stop", "rule
 // command: "sp" is split at a blackjack table, but spin at a Big 6 wheel,
 // because "split" is not a Big 6 verb and "spin" is not a blackjack verb.
 var casinoVerbsByGame = map[casino.GameName][]string{
+	casino.GamePlinko:     {"bet", "rebet", "difficulty", "balls", "paytable"},
 	casino.GameBlackjack:  {"bet", "rebet", "unbet", "hit", "stand", "double", "split", "insurance", "surrender", "decline"},
 	casino.GameBaccarat:   {"bet", "rebet", "unbet"},
 	casino.GameRoulette:   {"bet", "rebet", "unbet"},
diff --git a/internal/game/look_casino.go b/internal/game/look_casino.go
index ec9ab61..df6a714 100644
--- a/internal/game/look_casino.go
+++ b/internal/game/look_casino.go
@@ -83,7 +83,7 @@ func (g *Game) renderCasinoTableDetails(sess *net.Session, cfg casino.TableConfi
 		fmt.Sprintf("  Seated   %s", seated),
 	}
 	switch cfg.Game {
-	case casino.GameRoulette, casino.GameBigSix:
+	case casino.GameRoulette, casino.GameBigSix, casino.GamePlinko:
 		// Look, like sitting down and the table command, shows the live
 		// wheel: tracker, racetrack, and betting layout.
 		if rendered := strings.TrimRight(g.renderCasinoSnapshot(sess, table.Board(sess.Player.Name)), "\n"); rendered != "" {
@@ -103,6 +103,8 @@ func (g *Game) renderCasinoTableDetails(sess *net.Session, cfg casino.TableConfi
 // look details block. The full wording lives in the rules help page.
 func casinoTableSummary(cfg casino.TableConfig) string {
 	switch cfg.Game {
+	case casino.GamePlinko:
+		return fmt.Sprintf("16 rows; four risks; 1-10 balls; %.4g%% base RTP + upward rounding", cfg.Plinko.Normalize().RTP)
 	case casino.GameBlackjack:
 		b := cfg.Blackjack.Normalize()
 		dealer := "dealer stands on soft 17"
diff --git a/internal/game/look_target.go b/internal/game/look_target.go
index 9065ccc..cfa6009 100644
--- a/internal/game/look_target.go
+++ b/internal/game/look_target.go
@@ -47,7 +47,7 @@ func (g *Game) doLookTarget(sess *net.Session, input string) {
 		return
 	}
 
-	if g.lookBigSixTable(sess, lower) || g.lookBlackjackTable(sess, lower) || g.lookBaccaratTable(sess, lower) || g.lookRouletteTable(sess, lower) || g.lookCrapsTable(sess, lower) || g.lookPaiGowTable(sess, lower) || g.lookVideoPokerCabinet(sess, lower) {
+	if g.lookPlinkoTable(sess, lower) || g.lookBigSixTable(sess, lower) || g.lookBlackjackTable(sess, lower) || g.lookBaccaratTable(sess, lower) || g.lookRouletteTable(sess, lower) || g.lookCrapsTable(sess, lower) || g.lookPaiGowTable(sess, lower) || g.lookVideoPokerCabinet(sess, lower) {
 		return
 	}
 
diff --git a/internal/game/plinko_test.go b/internal/game/plinko_test.go
new file mode 100644
index 0000000..711525f
--- /dev/null
+++ b/internal/game/plinko_test.go
@@ -0,0 +1,261 @@
+package game
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+	"unicode/utf8"
+
+	"thehouseoficarus/internal/casino"
+	"thehouseoficarus/internal/color"
+)
+
+func TestPlinkoCommands(t *testing.T) {
+	g, s, conn := casinoCrapsGame(t, "name: Plinko\ncasino_tables:\n  - id: plinko\n    game: plinko\n")
+	g.executePlay(s, []string{"plinko"}, "play plinko")
+	g.executeCommand(s, "difficulty", []string{"expert"}, "difficulty expert")
+	g.executeCommand(s, "balls", []string{"10"}, "balls 10")
+	table, ok := g.Casino.Participation(s.Player.Name)
+	if !ok || table == nil {
+		t.Fatal("not seated")
+	}
+	snap := table.Status(s.Player.Name)[0].Snapshot.(*casino.PlinkoSnapshot)
+	if snap.Total != 10 || snap.Risk != "expert" || snap.Pockets[0] != 10000 {
+		t.Fatalf("commands failed: %+v", snap)
+	}
+	g.executeBet(s, []string{"1"}, "bet 1")
+	if !table.Busy(s.Player.Name) || len(s.Player.PendingWagers) != 1 {
+		t.Fatal("drop did not start")
+	}
+	conn.data = nil
+	for i := 0; i < 32 && table.Busy(s.Player.Name); i++ {
+		g.emitCasinoEvents(g.Casino.Tick())
+	}
+	if table.Busy(s.Player.Name) || len(s.Player.PendingWagers) != 0 {
+		t.Fatal("drop did not settle")
+	}
+	text := stripANSI(string(conn.data))
+	if !strings.Contains(text, "Ball 10 ->") || strings.Count(text, "Returned:") != 1 || strings.Contains(text, "credits returned") || strings.Contains(text, "net +") {
+		t.Fatal(text)
+	}
+	conn.data = nil
+	g.doLookTarget(s, "plinko")
+	if !strings.Contains(stripANSI(string(conn.data)), "P L I N K O") {
+		t.Fatal("look missing paytable")
+	}
+}
+func TestPlinkoBallShades(t *testing.T) {
+	if plinkoBallColor(1, 1) != color.NearestXterm256(255, 255, 255) {
+		t.Fatal("single must be white")
+	}
+	for total := 2; total <= 10; total++ {
+		last := 256
+		for count := 1; count <= total; count++ {
+			r, g, b := color.Xterm256ToRGB(plinkoBallColor(count, total))
+			if r != 255 || g != b || g > last {
+				t.Fatal("invalid white-red gradient")
+			}
+			last = g
+		}
+		if last != 0 {
+			t.Fatal("all balls must be pure red")
+		}
+	}
+}
+func TestPlinkoRenderRows(t *testing.T) {
+	for _, mode := range []string{"none", "ansi", "xterm256"} {
+		for _, unicode := range []bool{false, true} {
+			for row := 0; row <= 16; row++ {
+				s := &casino.PlinkoSnapshot{Row: row, Total: 10}
+				s.Counts[0] = 10
+				out := renderPlinko(s, mode, unicode)
+				for _, line := range strings.Split(stripANSI(out), "\n") {
+					if utf8.RuneCountInString(line) != plinkoWidth {
+						t.Fatal("board must keep its full width, including exterior spaces")
+					}
+				}
+				wantLines := 1
+				if row == plinkoRows/2 || row == plinkoRows {
+					wantLines = 2 // midpoint hint ruler, base rail
+				}
+				if got := len(strings.Split(out, "\n")); got != wantLines {
+					t.Fatalf("row %d printed %d lines, want %d", row, got, wantLines)
+				}
+				if strings.Contains(out, "\x1b[48;") {
+					t.Fatal("the board must not paint a background")
+				}
+				if mode == "none" && (!strings.Contains(out, "*") || strings.Contains(out, "\x1b")) {
+					t.Fatal("plain overlap fallback missing")
+				}
+			}
+		}
+	}
+}
+
+func TestPlinkoUsesSharedHints(t *testing.T) {
+	for _, mode := range []string{"on", "once", "off"} {
+		t.Run(mode, func(t *testing.T) {
+			g, s, conn := casinoCrapsGame(t, "name: Plinko\ncasino_tables:\n  - id: plinko\n    game: plinko\n")
+			s.Player.Options = map[string]any{"color": "none", "unicode": true, "casino_hints": mode}
+			g.executePlay(s, []string{"plinko"}, "play plinko")
+			text := string(conn.data)
+			if strings.Contains(text, "difficulty easy|medium|hard|expert") != (mode != "off") {
+				t.Fatalf("join hints (%s): %s", mode, text)
+			}
+			if mode != "off" && strings.Index(text, "P L I N K O") > strings.Index(text, "bet N") {
+				t.Fatal("hints must follow the paytable")
+			}
+			conn.data = nil
+			g.executeTableAction(s, "balls 2")
+			if strings.Contains(string(conn.data), "bet N") != (mode == "on") {
+				t.Fatalf("settings hints (%s): %s", mode, conn.data)
+			}
+			g.executeBet(s, []string{"1"}, "bet 1")
+			table, _ := g.Casino.Participation(s.Player.Name)
+			for i := 0; i < 32 && table.Busy(s.Player.Name); i++ {
+				conn.data = nil
+				g.emitCasinoEvents(g.Casino.Tick())
+			}
+			if strings.Contains(string(conn.data), "bet N") != (mode == "on") {
+				t.Fatalf("settlement hints (%s): %s", mode, conn.data)
+			}
+			conn.data = nil
+			g.executeVerbs(s, nil, "what")
+			if !strings.Contains(string(conn.data), "balls N") {
+				t.Fatal("explicit hints missing")
+			}
+		})
+	}
+}
+
+func plinkoTestBoardRow(s *casino.PlinkoSnapshot) []rune {
+	lines := strings.Split(renderPlinko(s, "none", true), "\n")
+	return []rune(lines[0])
+}
+
+func TestPlinkoPegsNeverMove(t *testing.T) {
+	for row := 0; row <= 16; row++ {
+		s := &casino.PlinkoSnapshot{Row: row, Total: 1}
+		empty := plinkoTestBoardRow(s)
+		left, right := 32-2*row, 36+2*row
+		pegs := map[int]bool{}
+		for k := 1; k <= row; k++ {
+			pegs[left+4*k] = true
+			if empty[left+4*k] != '·' {
+				t.Fatalf("row %d: peg missing at its true position %d", row, left+4*k)
+			}
+		}
+		if right < plinkoWidth && empty[right] != '\\' || empty[left] != '/' {
+			t.Fatalf("row %d: border moved", row)
+		}
+		for lane := 0; lane <= row; lane++ {
+			s.Counts = [17]int{}
+			s.Counts[lane] = 1
+			filled := plinkoTestBoardRow(s)
+			x := 34 - 2*row + 4*lane
+			if filled[x] != '●' {
+				t.Fatalf("ball not in its own lane: row %d lane %d", row, lane)
+			}
+			for px := range pegs {
+				if filled[px] != '·' {
+					t.Fatalf("row %d lane %d overwrote peg at %d", row, lane, px)
+				}
+			}
+		}
+	}
+}
+
+func TestPlinkoHintsPrintOnceAtMidpoint(t *testing.T) {
+	pockets := [17]float64{16, 7.8, 5.9, 4.4, 3.1, 2, 1.1, 0.5, 0.2, 0.5, 1.1, 2, 3.1, 4.4, 5.9, 7.8, 16}
+	labels := casino.PlinkoPocketLabels(pockets)
+	isRuler := func(line string) bool {
+		r := []rune(line)
+		if len(r) != plinkoWidth || r[1] != ' ' {
+			return false
+		}
+		for k, label := range labels {
+			if r[2+4*k] != label {
+				return false
+			}
+		}
+		return true
+	}
+	for row := 0; row <= 16; row++ {
+		s := &casino.PlinkoSnapshot{Row: row, Total: 1, Pockets: pockets}
+		hasRuler := false
+		for _, line := range strings.Split(stripANSI(renderPlinko(s, "none", true)), "\n") {
+			hasRuler = hasRuler || isRuler(line)
+		}
+		if hasRuler != (row == plinkoRows/2) {
+			t.Fatalf("row %d: hint ruler present=%v", row, hasRuler)
+		}
+		// The pyramid row itself never carries pocket letters any more.
+		board := plinkoTestBoardRow(s)
+		for k, label := range labels {
+			if board[2+4*k] == label {
+				t.Fatalf("row %d: pocket hint leaked into the board", row)
+			}
+		}
+	}
+}
+
+func TestPlinkoLegendDownTheLeft(t *testing.T) {
+	s := &casino.PlinkoSnapshot{Pockets: [17]float64{16, 7.8, 5.9, 4.4, 3.1, 2, 1.1, 0.5, 0.2, 0.5, 1.1, 2, 3.1, 4.4, 5.9, 7.8, 16}, Total: 1}
+	labels := casino.PlinkoPocketLabels(s.Pockets)
+	if string(labels[:]) != "ABCDEFGHIHGFEDCBA" {
+		t.Fatalf("wrong labels: %s", string(labels[:]))
+	}
+	entries := plinkoLegendEntries(s)
+	if len(entries) != 9 {
+		t.Fatalf("want 9 distinct legend entries, got %d", len(entries))
+	}
+	for row := 0; row < len(entries); row++ {
+		s.Row = row
+		line := string(plinkoTestBoardRow(s))
+		want := fmt.Sprintf("%c %s", entries[row].label, entries[row].text)
+		if !strings.HasPrefix(line[1:], want) {
+			t.Fatalf("row %d: legend entry not on the left: %q", row, line)
+		}
+		if entries[row].label == 'A' && !strings.Contains(line, "16x") {
+			t.Fatal("legend missing the 16x edge payout")
+		}
+	}
+	// The legend stays clear of the pyramid as it widens.
+	s.Row = len(entries) - 1
+	if left := 32 - 2*s.Row; left <= 10 {
+		t.Fatalf("legend would collide with the pyramid: left border %d", left)
+	}
+	// The paytable prints the same entries, one per line, not a wide block.
+	s.Row = 0
+	paytable := stripANSI(renderPlinko(&casino.PlinkoSnapshot{Pockets: s.Pockets, Risk: "easy", Paytable: true}, "none", true))
+	for _, e := range entries {
+		if strings.Count(paytable, fmt.Sprintf("%c %s", e.label, e.text)) != 1 {
+			t.Fatalf("paytable legend missing or duplicated %c", e.label)
+		}
+	}
+	// Rounded ties, not just mirrored positions, share one legend entry.
+	s.Row = 16
+	s.Counts = [17]int{}
+	rail := strings.Split(renderPlinko(s, "none", true), "\n")[1]
+	if !strings.Contains(rail, "[A] [B] [C] [D] [E] [F] [G] [H] [I] [H] [G] [F] [E] [D] [C] [B] [A]") {
+		t.Fatal(rail)
+	}
+	s.Pockets[7], s.Pockets[8], s.Pockets[9] = 0.1, 0.1, 0.1
+	if got := plinkoLegendEntries(s); len(got) != 8 {
+		t.Fatalf("rounded ties duplicated: %d entries", len(got))
+	}
+}
+
+func TestPlinkoHintsAreDimWhite(t *testing.T) {
+	r, g, b := color.Xterm256ToRGB(plinkoHintColor())
+	if r != g || g != b {
+		t.Fatalf("hint is not white: %d,%d,%d", r, g, b)
+	}
+	if r > 95 {
+		t.Fatalf("hint is too bright: %d", r)
+	}
+	br, bg, bb := color.Xterm256ToRGB(plinkoBallColor(1, 1))
+	if r >= br || g >= bg || b >= bb {
+		t.Fatal("hint must be dimmer than a ball")
+	}
+}
diff --git a/internal/game/render_plinko.go b/internal/game/render_plinko.go
new file mode 100644
index 0000000..17f533a
--- /dev/null
+++ b/internal/game/render_plinko.go
@@ -0,0 +1,213 @@
+package game
+
+import (
+	"fmt"
+	"math"
+	"strings"
+
+	"thehouseoficarus/internal/casino"
+	"thehouseoficarus/internal/color"
+)
+
+const plinkoWidth = 69
+
+// plinkoRows is the board height (16 bounces, 17 pockets).
+const plinkoRows = 16
+
+func plinkoBallColor(count, total int) int {
+	shade := 255
+	if total > 1 && count > 1 {
+		shade = 255 * (total - count) / (total - 1)
+	}
+	return color.NearestXterm256(255, shade, shade)
+}
+
+// plinkoGradientRGB is the board's shared hue: icy white at the center,
+// deepening through sky blue and violet to a saturated rose at the edges.
+func plinkoGradientRGB(x int) [3]int {
+	stops := [4][3]int{{215, 255, 255}, {85, 195, 255}, {145, 85, 245}, {255, 0, 95}}
+	distance := math.Abs(float64(x-34)) / 34
+	segment := min(2, int(distance*3))
+	blend := distance*3 - float64(segment)
+	var rgb [3]int
+	for i := range rgb {
+		rgb[i] = int(math.Round(float64(stops[segment][i])*(1-blend) + float64(stops[segment+1][i])*blend))
+	}
+	return rgb
+}
+
+func plinkoColorAt(x int, scale float64) int {
+	rgb := plinkoGradientRGB(x)
+	return color.NearestXterm256(
+		max(0, min(255, int(float64(rgb[0])*scale))),
+		max(0, min(255, int(float64(rgb[1])*scale))),
+		max(0, min(255, int(float64(rgb[2])*scale))))
+}
+
+// plinkoHintColor is the dim white used by the one-time midpoint pocket ruler.
+func plinkoHintColor() int { return 238 }
+
+// Foregrounds are deliberately faint so the balls stay the brightest thing
+// on the board.
+func plinkoPegColor(x int) int    { return plinkoColorAt(x, 0.68) }
+func plinkoBorderColor(x int) int { return plinkoColorAt(x, 0.78) }
+func plinkoPocketColor(x int) int { return plinkoColorAt(x, 0.90) }
+
+func plinkoMultiplier(multiplier float64) string {
+	return strings.TrimSuffix(fmt.Sprintf("%.1f", multiplier), ".0") + "x"
+}
+
+type plinkoCell struct {
+	glyph rune
+	fg    int
+	guide bool
+}
+type plinkoLine [plinkoWidth]plinkoCell
+
+func newPlinkoLine() plinkoLine {
+	var line plinkoLine
+	for x := range line {
+		line[x] = plinkoCell{glyph: ' ', fg: -1}
+	}
+	return line
+}
+func (line *plinkoLine) text(x int, text string, fg int) {
+	for _, c := range text {
+		if x >= len(line) {
+			break
+		}
+		line[x] = plinkoCell{glyph: c, fg: fg}
+		x++
+	}
+}
+func (line plinkoLine) render(mode string) string {
+	var b strings.Builder
+	for _, cell := range line {
+		fg := cell.fg
+		// Basic ANSI has no dim white; the dim attribute plus bright black is
+		// its closest readable stand-in for a faint white hint.
+		dim := false
+		if cell.guide && mode == "ansi" {
+			fg, dim = 7, true
+		}
+		b.WriteString(color.Render(mode, color.ColorSpec{Fg: fg, Bg: -1, Dim: dim}, string(cell.glyph)))
+	}
+	return b.String()
+}
+
+type plinkoLegendEntry struct {
+	label rune
+	text  string
+	// pocket is the left-most pocket index that carries this label, used to
+	// tint the entry with that column's board hue.
+	pocket int
+}
+
+// plinkoLegendEntries is one entry per distinct payout, outside-to-center.
+// Mirrored and rounded-tie pockets share a letter and therefore one entry.
+func plinkoLegendEntries(s *casino.PlinkoSnapshot) []plinkoLegendEntry {
+	labels := casino.PlinkoPocketLabels(s.Pockets)
+	var entries []plinkoLegendEntry
+	seen := map[rune]bool{}
+	for k, label := range labels {
+		if seen[label] {
+			continue
+		}
+		seen[label] = true
+		entries = append(entries, plinkoLegendEntry{label: label, text: plinkoMultiplier(s.Pockets[k]), pocket: k})
+	}
+	return entries
+}
+
+// plinkoLegendText pads an entry to a fixed width so a guide letter in the
+// next column never butts directly against the multiplier.
+func plinkoLegendText(e plinkoLegendEntry) string {
+	return fmt.Sprintf("%c %-7s", e.label, e.text)
+}
+
+// The legend is written down the left, outside the pyramid, one entry per
+// row, so every value is known well before the ball reaches the pockets.
+func renderPlinkoLegend(s *casino.PlinkoSnapshot, mode string) []string {
+	var lines []string
+	for _, e := range plinkoLegendEntries(s) {
+		line := newPlinkoLine()
+		line.text(1, plinkoLegendText(e), plinkoPocketColor(2+4*e.pocket))
+		lines = append(lines, line.render(mode))
+	}
+	return lines
+}
+
+// plinkoHintLine is the one-time pocket ruler printed at the board's midpoint,
+// so players learn the pocket columns without a letter on every row.
+func plinkoHintLine(labels [17]rune, mode string) string {
+	hint := newPlinkoLine()
+	for k, label := range labels {
+		hint[2+4*k] = plinkoCell{glyph: label, fg: plinkoHintColor(), guide: true}
+	}
+	return hint.render(mode)
+}
+
+// The legend appears down the left, then each snapshot appends one scanline.
+// The pocket hints print once, as a ruler at the board's midpoint.
+func renderPlinko(s *casino.PlinkoSnapshot, mode string, unicode bool) string {
+	labels := casino.PlinkoPocketLabels(s.Pockets)
+	if s.Paytable {
+		title := "=== P L I N K O / " + strings.ToUpper(s.Risk) + " ==="
+		heading := newPlinkoLine()
+		heading.text((plinkoWidth-len(title))/2, title, plinkoPocketColor(34))
+		note := newPlinkoLine()
+		note.text(1, "Matching letters share a payout; returns include the stake.", plinkoPocketColor(34))
+		lines := []string{heading.render(mode), note.render(mode)}
+		lines = append(lines, renderPlinkoLegend(s, mode)...)
+		tail := newPlinkoLine()
+		tail.text(1, "White = one ball; shades to red = all balls overlapping.", plinkoPocketColor(34))
+		return strings.Join(append(lines, tail.render(mode)), "\n")
+	}
+	ball, peg := 'o', '.'
+	if unicode {
+		ball, peg = '●', '·'
+	}
+	line := newPlinkoLine()
+	left, right := 32-2*s.Row, 36+2*s.Row
+	line[left] = plinkoCell{glyph: '/', fg: plinkoBorderColor(left)}
+	line[right] = plinkoCell{glyph: '\\', fg: plinkoBorderColor(right)}
+	// Pegs sit at their true between-lane positions; they are never moved to
+	// make room for a guide letter.
+	for k := 1; k <= s.Row; k++ {
+		x := left + 4*k
+		line[x] = plinkoCell{glyph: peg, fg: plinkoPegColor(x)}
+	}
+	for k := 0; k <= s.Row; k++ {
+		count := s.Counts[k]
+		if count == 0 {
+			continue
+		}
+		glyph := ball
+		if mode == "none" && count > 1 {
+			glyph = rune('0' + count)
+			if count == 10 {
+				glyph = '*'
+			}
+		}
+		line[left+2+4*k] = plinkoCell{glyph: glyph, fg: plinkoBallColor(count, s.Total)}
+	}
+	if entries := plinkoLegendEntries(s); s.Row < len(entries) {
+		e := entries[s.Row]
+		line.text(1, plinkoLegendText(e), plinkoPocketColor(2+4*e.pocket))
+	}
+	lines := []string{line.render(mode)}
+	if s.Row == plinkoRows/2 {
+		lines = append(lines, plinkoHintLine(labels, mode))
+	}
+	if s.Row == 16 {
+		rail := newPlinkoLine()
+		for k, label := range labels {
+			x := 1 + 4*k
+			rail[x] = plinkoCell{glyph: '[', fg: plinkoPegColor(x)}
+			rail[x+1] = plinkoCell{glyph: label, fg: plinkoPocketColor(x + 1)}
+			rail[x+2] = plinkoCell{glyph: ']', fg: plinkoPegColor(x + 2)}
+		}
+		lines = append(lines, rail.render(mode))
+	}
+	return strings.Join(lines, "\n")
+}