Skip to main content

​
Running Marlin

After building Marlin, launch the interactive CLI: 
./build/marlin
You’ll see the welcome prompt: 
Marlin Connect 4 Engine v0.1
Type 'help' for available commands.

>

​
Available Commands

Marlin supports the following commands:
CommandDescriptionExample
position [moves]Set up a position by playing movesposition 4433
displayShow the current board statedisplay
goFind the best move using the solvergo
helpShow available commandshelp
quitExit the programquit

​
Move Format

Moves are represented as digits 1-7, where each digit corresponds to a column:
  • 4 → Drop a piece in column 4 (the center column)
  • 4433 → Play four moves:
    1. Player 1 drops in column 4
    2. Player 2 drops in column 4
    3. Player 1 drops in column 3
    4. Player 2 drops in column 3
The board uses 1-based indexing for user input (columns 1-7 from left to right).

​
Example Session

Here’s a complete example showing how to analyze a position:
1

Set up a position

Let’s create a position where both players have played in the center columns:
> position 4433
Played 4 moves
This plays:
  • Move 1: Player 1 (X) → column 4
  • Move 2: Player 2 (O) → column 4
  • Move 3: Player 1 (X) → column 3
  • Move 4: Player 2 (O) → column 3
2

Display the board

View the current position:
> display
| . . . . . . . |
| . . . . . . . |
| . . . . . . . |
| . . . . . . . |
| . . O O . . . |
| . . X X . . . |
+---------------+
  1 2 3 4 5 6 7
Legend:
  • X = Current player’s pieces (Player 1)
  • O = Opponent’s pieces (Player 2)
  • . = Empty cells
3

Find the best move

Ask Marlin to analyze the position and find the optimal move:
> go
Analyzing...
  Column 3: score 18
bestmove 3 score 18 (WIN)
Nodes analyzed: 12847
Output explanation:
  • bestmove 3 → Column 3 is the optimal move
  • score 18 → Current player can force a win in 18 moves
  • Nodes analyzed: 12847 → The solver explored 12,847 positions to find this result

​
Understanding the Analysis

​
Score Interpretation

Marlin’s scores are always from the current player’s perspective:

Positive Score

Current player can force a winExample: +18 = Win in 18 moves

Zero Score

Perfect play leads to a drawNeither player can force a win

Negative Score

Opponent can force a winExample: -12 = Lose in 12 moves
Score magnitude indicates how quickly the game will end:
  • Higher positive → Faster win for current player
  • Lower negative → Faster win for opponent

​
Move Analysis Output

When you run go, Marlin shows the evaluation for each legal move: 
Analyzing...
  Column 1: score -8
  Column 2: score 12
  Column 3: score 18    ← Best move
  Column 4: score 14
  Column 5: score 10
  Column 6: score -2
  Column 7: score -6
bestmove 3 score 18 (WIN)
Nodes analyzed: 45231
This tells you:
  • Each column’s game-theoretic value
  • Which move is optimal (column 3 with score +18)
  • How many positions were searched

​
Common Workflows

​
Analyze an Opening

> position 4        # Player 1 plays center
Played 1 moves
> go
Analyzing...
bestmove 4 score 0 (DRAW)
Nodes analyzed: 2847
The center opening leads to a draw with perfect play.

​
Reset to Empty Board

> position
Position reset to empty board
> display
| . . . . . . . |
| . . . . . . . |
| . . . . . . . |
| . . . . . . . |
| . . . . . . . |
| . . . . . . . |
+---------------+
  1 2 3 4 5 6 7

​
Detect Immediate Wins

Marlin quickly detects winning moves without deep search: 
> position 444555666    # Set up a position
> go
bestmove 7 score WIN (immediate)
The solver recognizes that column 7 wins instantly.

​
Performance Notes

Marlin uses transposition tables to cache positions. The first analysis of a position tree may take longer, but subsequent analyses (even from different move orders) will be much faster.
The node count shows how many positions were examined:
  • Small numbers (< 1,000) → Shallow search or heavily pruned
  • Large numbers (> 100,000) → Deep search in complex positions
  • The transposition table and alpha-beta pruning work together to minimize this count

​
Next Steps

Now that you can run basic analyses, learn how Marlin works under the hood:

Core Concepts

Understand bitboards, negamax, and alpha-beta pruning

API Reference

Explore Marlin’s classes and methods

Build docs developers (and LLMs) love

Get started for freeTalk to us