Generate a Word Search Puzzle Grid

Supply the words, a square grid size, and an integer seed; the generator places each word horizontally, vertically, or diagonally, allows compatible letters to cross, and fills every remaining cell with a reproducible letter sequence. The response includes both the finished rows and exact placement coordinates, making it useful for printable activities, automated tests, classroom materials, and applications that need a stable puzzle plus a reliable answer key.

Prepare a word list and choose the grid dimensions

Start with between one and twenty distinct words written with the English letters A through Z. Letter case does not affect the puzzle because the generator normalizes every accepted word to uppercase before placement. Choose <code>grid_size</code> as the number of rows and columns in the square, from 2 through 25. The longest word cannot exceed that size: a six-letter word, for example, needs a grid at least six cells wide because every permitted placement follows a straight line. A larger grid leaves more room between terms and creates more filler cells, while a compact grid tends to produce denser overlaps. If your first size cannot accommodate the full set, increase it or shorten the list rather than expecting words to bend or wrap around an edge. Duplicate words are rejected after case normalization because two identical answer-key entries would be ambiguous. Spaces, hyphens, accents, digits, and punctuation are also rejected, keeping every grid cell to one predictable uppercase character. These validation rules make the returned rows easy to print, split into cells, or compare in software without additional text cleanup.

Use a seed to reproduce placement and filler letters

The <code>seed</code> controls every choice that would otherwise appear random. For each word, the generator builds the complete set of positions that stay inside the grid across east, west, north, south, and the four diagonal directions. It orders those candidates from the seeded pseudo-random sequence, places longer words first, and uses deterministic backtracking when a promising arrangement blocks a later word. Existing letters may be shared only when they match, so crossing words remain readable and no character is overwritten. After all terms have positions, the same seeded sequence supplies uppercase filler letters for blank cells. Repeating the identical words in the identical order with the same grid size and seed therefore returns the same grid and placements. That is particularly useful when a puzzle must be regenerated from a small configuration, reviewed in a test fixture, or shared between a teacher and an answer-key service. Changing the seed usually changes positions and filler, but it does not provide cryptographic unpredictability. Treat the seed as a reproducibility control, not as a secret or a defense against someone intentionally reconstructing the answer.

Read the grid and build an answer key

The response returns <code>grid</code> as an array of equal-length strings, one string per row. This format can be displayed directly in a monospaced layout or converted into individual cells by splitting each string into characters. Coordinates in <code>placements</code> are zero-based: <code>row: 0</code> and <code>column: 0</code> identify the top-left cell. Direction codes describe how to move after each character: <code>E</code> and <code>W</code> are horizontal, <code>N</code> and <code>S</code> are vertical, and <code>NE</code>, <code>NW</code>, <code>SE</code>, and <code>SW</code> are diagonal. Placements remain in the same order as the submitted word list even though the search internally handles longer words first. You can hide that array from players and retain it as the answer key, or use it to highlight solved terms in an interactive interface. If the complete list has no valid arrangement at the requested size, the request returns an input error instead of silently dropping a word or producing a partial puzzle. That all-or-nothing behavior makes automation dependable: a successful result always contains every requested word, while an error tells the caller to select a larger grid or a smaller set.