🔢

Sudoku

gameType: "sudoku"

Classic 9×9 Sudoku puzzles with guaranteed unique solutions and difficulty grading. Each puzzle is generated via backtracking with random choices, then cells are removed while ensuring the solution remains unique. Difficulty is controlled by the number of given cells — fewer givens means harder puzzles requiring more advanced solving techniques.

Interactive Example

🔢 Sudoku

Classic 9×9 puzzle — unique solution guaranteed

Mediumunique solution ✓
5
3
7
6
1
9
5
9
8
6
8
6
3
4
8
3
1
7
2
6
6
2
8
4
1
9
5
8
7
9
5Given clue

Given Clues

30

Empty Cells

51

Difficulty

Medium

Score

0.50

Try it

await pf.generate({
  gameType: "sudoku",
  params: { difficulty: "medium" },
  count: 10,
  difficulty: { target: 0.50 }
})

API Parameters

ParamTypeRequiredDefaultDescription
difficulty"easy" | "medium" | "hard"Yes"medium"Controls how many cells are removed. "easy" ≈ 46 givens (35 removed), "medium" ≈ 36 givens (45 removed), "hard" ≈ 26 givens (55 removed). Can also be set via the numeric difficulty option (0–0.33 = easy, 0.33–0.66 = medium, 0.66–1.0 = hard).

Common Request Options

ParamTypeRequiredDefaultDescription
countnumberYes—How many puzzles to generate in this batch.
difficulty.targetnumberNo0.5Numeric difficulty target (0.0–1.0). Overrides the params.difficulty string. Maps to easy/medium/hard.
difficulty.curve"flat" | "ascending" | "descending" | "bell"No"flat"Difficulty distribution across the batch.
seednumberNo—Seed for reproducible generation. Same seed + same params = same puzzles.

Content Output

Each generated puzzle returns the following in content:

ParamTypeRequiredDefaultDescription
puzzlenumber[][]——9×9 grid where 0 = empty cell, 1–9 = given values.
solutionnumber[][]——The complete 9×9 solved grid.
givenCountnumber——Number of pre-filled cells (17–50 typical).
difficulty"easy" | "medium" | "hard"——The difficulty setting used for generation.

Example Request

bash
curl -X POST https://api.gameplaygen.com/generate \
  -H "Authorization: Bearer gg_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "gameType": "sudoku",
    "params": { "difficulty": "hard" },
    "count": 3,
    "difficulty": { "target": 0.8 }
  }'

Example Response

json
{
  "content": [
    {
      "id": "gg_sdk7x92m",
      "gameType": "sudoku",
      "content": {
        "puzzle": [
          [0, 0, 0, 0, 7, 0, 0, 0, 0],
          [0, 0, 0, 0, 0, 5, 0, 3, 0],
          [0, 4, 0, 0, 0, 0, 9, 0, 0],
          [5, 0, 0, 0, 0, 0, 0, 0, 7],
          [0, 0, 0, 9, 0, 3, 0, 0, 0],
          [8, 0, 0, 0, 0, 0, 0, 0, 1],
          [0, 0, 6, 0, 0, 0, 0, 8, 0],
          [0, 1, 0, 2, 0, 0, 0, 0, 0],
          [0, 0, 0, 0, 4, 0, 0, 0, 0]
        ],
        "solution": [
          [3, 6, 9, 8, 7, 1, 5, 4, 2],
          [1, 8, 2, 4, 6, 5, 7, 3, 9],
          [7, 4, 5, 3, 2, 9, 8, 1, 6],
          [5, 3, 4, 1, 8, 2, 6, 9, 7],
          [6, 2, 1, 9, 5, 3, 8, 7, 4],
          [8, 9, 7, 6, 3, 4, 2, 5, 1],
          [4, 5, 6, 7, 1, 8, 3, 2, 9],
          [9, 1, 8, 2, 9, 6, 4, 7, 5],
          [2, 7, 3, 5, 4, 8, 1, 6, 3]
        ],
        "givenCount": 26,
        "difficulty": "hard"
      },
      "metrics": {
        "verified": true,
        "difficulty": 0.82,
        "balance": 0.95,
        "novelty": 1.0,
        "quality": 0.91,
        "notes": ["Unique solution confirmed", "26 givens"]
      },
      "meta": {
        "generatedAt": "2025-07-15T10:30:00Z",
        "generatorVersion": "0.2.0",
        "attempts": 1,
        "validationTime": 18
      }
    }
  ],
  "requested": 3,
  "delivered": 3,
  "stats": {
    "totalCandidates": 3,
    "totalValidated": 3,
    "totalRejected": 0,
    "totalTime": 420,
    "avgDifficulty": 0.81,
    "difficultyRange": [0.78, 0.84]
  }
}

Tips for Game Integration

  • ▸Pre-generate batches: Sudoku generation is fast (~50ms/puzzle). Generate 50–100 puzzles per difficulty and cache them.
  • ▸Hint systems: Use the solution field to power hint buttons — reveal one cell at a time.
  • ▸Difficulty progression: Use difficulty.curve: "ascending" to create a natural learning curve across a level pack.
  • ▸Unique solution guaranteed: Every puzzle has exactly one valid solution. No ambiguity.
  • ▸Seed for daily puzzles: Use a date-based seed (e.g., seed: 20250715) to give all players the same "Daily Sudoku".