Play the game

Sudoku Documentation

Introduction:

This Sudoku game was started as a personal project to bring me back on track with web development after spending months traveling and not using a computer all this time. I thought I forgot most, but it seems getting back to business took less time than I thought, and was also fun process.

I wanted to build a Sudoku game in pure JS, after playing lots of Sudoku on my iPhone. At the beginning the game was simple, I managed to create a board with random numbers which followed the rules of the game:

  1. No number can repeat itself in the same 3x3 square
  2. No number can repeat itself on the same 9 cells column or row.
  3. Every empty cell should have a "mirror" empty cell (for example cells [0,7] & [8,1] OR [3,3] & [5,5]) ps. when Cells and 3x3 Cox index starts from '0' ,left to right, top to bottom.
  4. Each game should have one and only solution to be considered a valid Sudoku game.

Technologies:

Browser support:

Program flow:

  1. HTML table markup is generated for the board
  2. there are many pre-generated games for each difficulty level. A random one is picked from the default 'easy' grade, from the 'board.games' object. This is done because it takes time (~400ms) to generate a valid Sudoku game, so for sake of user experience the program first loads a pre-made game.
  3. Meanwhile, the program creates (spawns) 6 new games on 6 different CPU threads via web-workers and runs all necessary calculations to make sure they are valid games. there are a couple of good reasons to use web-workers in this situation:
    1. The workers run on different threads, which makes sure the browser doesn't "hang up" when intense JS calculations are done, and the UX is kept smooth.
    2. In some rare cases the where calculations becomes too intense for a specific game, it can crush the browser, so by utilizing the web-workers, this situation will no longer happen
    3. Performance. creating many boards at the same time and sort them by difficultly while the person is actually interacting with the program in the background is pretty neat :)
  4. Every time a user choose to play a new game, the program picks one of the games that was generated when the program first loaded, so the user will have a unique board never played before. every board the program generates is unique for the user and probably universally unique by the laws of probability.
  5. The program spawns up to 15 new unique games into the 'board.games' object for each level of difficulty, so the user will never have to wait for a game to be calculated and generated, because this already happened in the background.

Program options:

How a Sudoku game is generated:

  1. For every spawned board there is an array which represent it, and which is being 'populated' with numbers according to the laws of sudoku, until all the board is full and complete.
  2. After the board is made, the program starts to remove numbers from random cells and their "mirror" cells, and checks after each pair removal if there is a solution and it's a single one. this is the the process which takes the longest time in the creation process and it's pure math, which is done by the "Dancing Links" algorithm (written by professor Donald Knuth), and this was the initial reason I choose to use web-workers. This algorithm is very complex math which solves problems, and probably 99% of Sudoku programs in the world use this, in one implementation of the other.
  3. Cells keep being removed. if more than 1 solution is found, or none, then the last cells that were removed are returned, and another position to be removed is picked randomly. this is done until a certain point that the program finds it hard to remove more.
  4. Now is the trickiest part, which is the most important; grading the generated game. This was done after excessive research for weeks, and eventually learning a number of methods to solve sudoku games, from basic methods to more advanced ones, and building functions that mimic the that line of thinking and try to solve the game like a human would. The grading system is an excellent one, tested on many games and fine-tuned for more than 2 weeks, to make sure games are rated as honestly as possible. I have designed a sudoku Solver which can solves most games and if not, there are complex calculations to determine the grade anyhow. the grader was designed to be standalone so others could integrate it in their games as well, because I haven't found anything like this in Javascript on the Internet.
  5. After the game has been given a grade, it is added to the array of already created games, sorted by its rating.

Program structure:

There are a couple of globals functions/objects:

Deeper explaining some of the main methods: