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"