Mancala-Solver

A helper for the iMessage GamePigeon Avalanche Mancala mode. It can read a screenshot using Google Cloud Vision or accept manual board input, then compute the best single-turn move sequence.

Features

• Avalanche-mode solver (multiple sowings in one turn).
• Screenshot OCR via Google Cloud Vision (optional).
• Manual board entry (recommended for accuracy).
• Vertical board display aligned with left/right columns.
• Prints one best move sequence (not a list).

Project layout

• Mancala/ is the Maven project (build/run from here).
• src/main/java/mancala/MancalaGenerate.java is the solver.
• src/main/java/mancala/Mancala.java is a playable CLI version.

Requirements

• Java 21 (or any JDK 8+ if you change the compiler target).
• Maven.
• For OCR mode: a Google Cloud project with Vision API enabled and a service account JSON key.

Build

From the repo root:

cd Mancala
mvn -q -DskipTests package
mvn -q dependency:build-classpath -DincludeScope=runtime -Dmdep.outputFile=cp.txt

Run (Manual mode)

Manual input is the most reliable and does not require Google Cloud.

java -cp "$(cat cp.txt):target/mancala-1.0-SNAPSHOT.jar" \
  mancala.MancalaGenerate --manual

Enter numbers in this exact order:

• Top store (opponent)
• 6 rows of left right (top to bottom)
• Bottom store (you)

Example (fresh board):

0
4 4
4 4
4 4
4 4
4 4
4 4
0

You can also enter 12 numbers without stores (stores default to 0). To finish input, send EOF (macOS/Linux: Ctrl+D on a blank line; Windows: Ctrl+Z then Enter).

Run (OCR / Screenshot mode)

Noob-friendly Google Cloud Vision setup

0) Preconditions

• Google account
• Local shell (macOS/Linux assumed)
• Ability to use absolute paths

1) Create GCP project

1. Go to Google Cloud Console.
2. Project selector → New Project.
3. Name: anything (e.g. loadgame-vision).
4. Note your PROJECT_ID.

2) Enable Vision API

1. Console → APIs & Services → Library.
2. Search Cloud Vision API.
3. Enable it.

3) Create service account

1. IAM & Admin → Service Accounts.
2. Create Service Account (name it vision-sa).
3. Grant role:
   • Cloud Vision API User
   • (or Editor if you want zero friction)
4. Finish.

4) Create key (JSON)

1. Click the service account.
2. Keys tab → Add Key → Create new key.
3. Type: JSON.
4. Download the file (e.g. vision-sa-<hash>.json).

5) Place key securely

mkdir -p ~/.gcp
mv ~/Downloads/vision-sa-*.json ~/.gcp/vision.json
chmod 600 ~/.gcp/vision.json

6) Export credentials (shell)

One-off (current session only):

export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp/vision.json"

Verify:

echo $GOOGLE_APPLICATION_CREDENTIALS

7) Persist across sessions (optional)

zsh:

echo 'export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp/vision.json"' >> ~/.zshrc
source ~/.zshrc

bash:

echo 'export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.gcp/vision.json"' >> ~/.bashrc
source ~/.bashrc

8) Sanity check (optional)

python - <<EOF
from google.cloud import vision
client = vision.ImageAnnotatorClient()
print("Vision client OK")
EOF

If this fails: check the credentials path and that Vision API is enabled.

Notes (non-negotiable)

• Never commit the JSON key.
• Prefer ignoring the key file (e.g. vision.json) or the ~/.gcp/ folder. Avoid ignoring *.json globally if this repo has package.json or other JSON files.
• Rotate keys if leaked.

1. Put your image somewhere accessible (e.g. Mancala/image.jpg).
2. Set your credentials:

export GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/your-service-account.json"

3. Run with a path argument:

java -cp "$(cat cp.txt):target/mancala-1.0-SNAPSHOT.jar" \
  mancala.MancalaGenerate "/absolute/path/to/image.jpg"

If you omit the path, it tries image.jpg in the current directory, then Mancala/image.jpg.

Note: the current code prints File not found! for any IOException, which can also mean missing/invalid Google credentials. If OCR fails, verify your key and that Vision API is enabled.

Output format (vertical board)

The solver prints the board like this:

OPP_STORE
L1 R1
L2 R2
L3 R3
L4 R4
L5 R5
L6 R6
MY_STORE

Where:

• Left column is the opponent side (top to bottom: board indices 13,12,11,10,9,8)
• Right column is your side (top to bottom: board indices 6,5,4,3,2,1)
• Top store = opponent (board index 0)
• Bottom store = you (board index 7)

Pocket numbers used in move order

The printed move order uses your pocket numbers 1–6:

Top store
13  6
12  5
11  4
10  3
 9  2
 8  1
Bottom store

So:

• Pocket 1 is bottom-right.
• Pocket 6 is top-right.

Playable CLI (no solver)

You can also play a simple text-based Mancala game:

java -cp "$(cat cp.txt):target/mancala-1.0-SNAPSHOT.jar" mancala.Mancala

Troubleshooting

• Maven not found: install it via Homebrew (brew install maven) or your OS package manager.
• "File not found!" on OCR: verify the image path and GOOGLE_APPLICATION_CREDENTIALS.
• Manual input seems stuck: enter 14 numbers, or enter 12 numbers and then a blank line.
• Java compatibility warnings: ensure your JDK and pom.xml target match.

Security / Publishing

• Never commit or publish your service account JSON key.
• Keep keys outside the repo (e.g. ~/secrets/) and set GOOGLE_APPLICATION_CREDENTIALS.
• Before publishing, you can clean ignored build output with:

git clean -fdX

License

Add a license if you plan to publish or share widely.