blex41/word-search

Word search puzzle generator

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"

word-search's Issues

Profanity filtering

This is awesome!

I'm using it in a game for kids and I was wondering if it is possible to prevent certain words from appear in the resulting grid?

It doesn't happen very often but I've seen inappropriate words appearing a couple of times, just by chance.

I don't see anything in your API so I'm guessing I need to check the result myself and then regenerate if I find a blacklisted term?

ws.toString() returns different data than ws.grid

In my code I am doing this

const ws = new WordSearch(options);
console.log(ws.toString())
return ws.grid;

grid and toString values are different.

'randomness' configurable as seed

I see _shuffle/randomness is used in the quite a bit in the files. Would be great if this would be configurable somehow as a seed or alike since I'm getting inconsistent results with certain words not being placeable, though it's only happening 'sometimes' due to the random factor being involved.

Issue with load function

Hello,
I have found a issue with the load function in which not merging (using) the correct values for cols and rows for the new
The following test will showcase the issue

it("ws.load() correctly applies the given properties for cols and rows", () => {
 const options = {
   cols: 4,
   rows: 4,
   dictionary: ['kim'],
   maxWords: 1,
   backwardsProbability: 0.1,
   upperCase: true,
   diacritics: true,
  };

  const ws6 = new WordSearch(options);
  const ws6Dump = ws6.dump();
  const ws7 = new WordSearch().load(ws6Dump);

  expect(ws7.data.grid[0].length).toBe(ws6.data.grid[0].length);
  expect(ws7.data.grid[0][0]).toBe(ws6.data.grid[0][0]);
  });

So it will need the following change as i have permission in this repo I'm able to make a PR for a fix.
the change is the following in the file src/index line 37

load(config) {
 this.data = config.data;
 this.settings = config.settings;
 this.forbiddenWordsFound = config.forbiddenWordsFound;
 return this;
}