synth/games/tasks/star_placement_puzzle/README.md

Star Placement Puzzle

This project implements a star placement logic puzzle game.

Game Rules

On an n×n grid, the grid is divided into different regions (marked with letters). Players need to place stars that satisfy the following rules:

1. Each row must have exactly k stars
2. Each column must have exactly k stars
3. Each letter region must have exactly k stars
4. Stars cannot be adjacent, including horizontally, vertically, and diagonally

Example

An example of a 4×4 star placement game with k=1:

Region grid:
    ["A", "A", "B", "B"],
    ["A", "A", "B", "B"],
    ["C", "C", "C", "C"],
    ["C", "D", "D", "D"]

Valid star layout:
    [" ", "*", " ", " "],  # Row 1
    ["*", " ", " ", " "],  # Row 2
    [" ", " ", "*", " "],  # Row 3
    [" ", " ", " ", "*"]   # Row 4

Where:
- Each row has 1 star
- Each column has 1 star
- Region A has 1 star
- Region B has 1 star
- Region C has 1 star
- Region D has 1 star
- No stars are adjacent

Quick Start

Generate Puzzles Only

If you only need to generate star placement game puzzles without testing and pass rate checking, you can use the following commands:

# Generate 10 star placement game puzzles
python -m tasks.star_placement_puzzle.scripts.star_placement_puzzle --num_of_data 10 --min_n 4 --max_n 6 --min_k 1 --max_k 2

# Specify a random seed for reproducible results
python -m tasks.star_placement_puzzle.scripts.star_placement_puzzle --seed 42 --num_of_data 5