Word Search Generator

Generates word search grids dynamically. The DB stores only words and clues; the engine builds the grid.

Usage

const result = engine.generateWordSearch(
  [
    { word: 'APPLE', clue: { type: 'TEXT',  value: 'A red fruit' } },
    { word: 'DOG',   clue: { type: 'IMAGE', value: 'https://cdn/dog.webp' } },
  ],
  12,    // gridSize
  true,  // allowDiagonal
  false, // allowReverse
);

Response

{
  "grid": [
    ["A", "P", "P", "L", "E", "X", "K", "M", "R", "T", "W", "Z"],
    ["B", "Q", "D", "O", "G", "U", "V", "W", "X", "Y", "Z", "A"]
  ],
  "placedWords": [
    {
      "word": "APPLE",
      "clue": { "type": "TEXT", "value": "A red fruit" },
      "startRow": 0,
      "startCol": 0,
      "direction": [0, 1]
    }
  ],
  "size": 12
}

Parameters

Parameter	Type	Description
words	{ word, clue }[]	Words with clues
gridSize	number	Grid dimension (gridSize x gridSize)
allowDiagonal	boolean	Allow diagonal words
allowReverse	boolean	Allow reversed words

Directions

Vector	Description	Available when
[0, 1]	Horizontal right	Always
[1, 0]	Vertical down	Always
[1, 1]	Diagonal down-right	allowDiagonal: true
[1, -1]	Diagonal down-left	allowDiagonal: true
[0, -1]	Horizontal left	allowReverse: true
[-1, 0]	Vertical up	allowReverse: true
[-1, -1]	Diagonal up-left	Both true
[-1, 1]	Diagonal up-right	Both true

Algorithm

1. Sorts words by length (longest first).
2. Tries up to 100 random positions per word.
3. Places if no conflict (empty cell or same letter).
4. Fills empty cells with random A-Z letters.
5. Returns grid and word placement metadata.

Words that don’t fit are silently omitted.