@blex41/word-search

word-search

Word search puzzle generator.

Installation

With NodeJS:

npm install -S @blex41/word-search

... and then:

const WordSearch = require("@blex41/word-search");

In a browser:

<script src="https://unpkg.com/@blex41/word-search@latest/dist/wordsearch.min.js"></script>
<script>
  /* WordSearch is available here */
</script>

Usage

// If an option is missing, it will be given a default value
const options = {
  cols: 6,
  rows: 6,
  disabledDirections: ["N", "W", "NW", "SW"],
  dictionary: ["Hello", "crêpe", "Škoda", "word", "search"],
  maxWords: 20,
  backwardsProbability: 0.3,
  upperCase: true,
  diacritics: true
};

// Create a new puzzle
const ws = new WordSearch(options);

// Use its methods
console.log(ws.toString());
// S Š M Y W X
// E C K M O G
// A R Z O R A
// R Ê N F D I
// C P I Y Q A
// H E L L O I

Options

Here are the options you can pass when creating a new puzzle:

name	type	default	description
cols	Integer	10	Number of columns
rows	Integer	10	Number of rows
disabledDirections	Array.String	[]	Directions to disable (any of "N", "S", "E", "W", "NE", "NW", "SE" or "SW")
dictionary	Array.String	[]	Words to insert in the grid (some of them may not be inserted if they're too long, cannot be placed, or if maxWords is exceeded)
maxWords	Integer	20	Maximum number of words to insert
backwardsProbability	Float	0.3	Probability to have each word written backwards (it's a probability, not a strict percentage)
upperCase	Boolean	true	Whether the letters in the grid should be uppercase
diacritics	Boolean	false	Whether the letters in the grid should keep their diacritics (accents)
forbiddenWords	Array.String	[]	Words which should not appear accidentally in the final grid, in any direction (e.g. profanity). Will try rebuilding it for maxRetries
maxRetries	Integer	10	Used only for the forbiddenWords option - how many attempts should be made to rebuild the grid when finding forbidden words in it

Properties and methods

Once you have created your instance, you can access these Read-Only properties:

ws.grid

Returns the puzzle's grid

[
  ["S", "Š", "M", "Y", "W", "X"],
  ["E", "C", "K", "M", "O", "G"],
  ["A", "R", "Z", "O", "R", "A"],
  ["R", "Ê", "N", "F", "D", "I"],
  ["C", "P", "I", "Y", "Q", "A"],
  ["H", "E", "L", "L", "O", "I"]
]

ws.words

Returns the words that were successfully inserted in the grid:

[
  {
    word: "word",
    clean: "WORD",
    path: [
      { x: 4, y: 0 }, // W
      { x: 4, y: 1 }, // O
      { x: 4, y: 2 }, // R
      { x: 4, y: 3 } // D
    ]
  },
  {
    word: "crêpe",
    clean: "CRÊPE",
    path: [
      { x: 1, y: 1 }, // C
      { x: 1, y: 2 }, // R
      { x: 1, y: 3 }, // Ê
      { x: 1, y: 4 }, // P
      { x: 1, y: 5 } // E
    ]
  }
  /* ... */
];

ws.forbiddenWordsIncluded

Returns an Array of forbidden words which were inserted into the grid because no other solution was found after maxRetries:

["CRAP"]

You can also use these methods:

ws.dump()

Returns an Object representing the state of the puzzle. This can be useful if you want to save a game and reuse it later using ws.load(backup).

ws.load(backup)

Loads a game from an Object of a previous dump.

const ws1 = new WordSearch(/* ... */);
const backup = ws1.dump();
const ws2 = new WordSearch().load(backup);
// ws2 is now a copy of ws1

ws.toString()

Returns a String representing the grid of the puzzle. This can be useful if you want to print it to the console.

S Š M Y W X
E C K M O G
A R Z O R A
R Ê N F D I
C P I Y Q A
H E L L O I

ws.read(start, end)

Reads the letters from start to end positions and returns the String it forms. This can be useful to check what letters a user highlighted.

ws.read({ x: 1, y: 0 }, { x: 5, y: 4 }); // "ŠKODA"