User Defined Topics

Creation system requirements

Before you begin, there are two requirements for creating and deploying User Defined topics:

Windows Only. User Defined topics can only be built on a Windows PC version of the game. This is because MAC uses an APP format that cannot be accessed through the MAC operating system. APP is a zip file, but because that file can only opened by developers, we cannot use MAC to help you create files.
Self Hosting. You must have a way to self host your files on an HTTP or FTP server, or, have a mechanism for distributing the ZIP files (such as, via email) so that they can be loaded with a FILE protocol (see below).
- Important: We do not directly support cloud providers like Dropbox, iCloud, One Drive, Sync, etc. However, you could use these services to host ZIP files that your users download, and manually install using the FILE protocol.

before you begin

Building a topic is a very time consuming process and can take days to weeks to complete. If you have never built a topic before, we recommend building a mini-topic consisting of a few hundred words and run through the entire process to get an understanding of how much effort is involved.

Dictionary construction will be an area where you spend most of your time, especially if you are making a topic which contains definitions. If you have a dictionary in another form, it might not take as long to complete this work. 80% of your time is spent in in this area. The next largest area is in the figuring out the dictionary levels and level.ratings, as you will have to test every combination in "dictionary" mode at least 5 times to get a good set of numbers rating. "English Words" was played more than 200 times to figure it's ratings.

What is in a worzzler topic directory?

Worzzler uses a directory structure to differentiate one topic from another. The directory's name is the topic name inside of the app. Inside the the directory you create your topic. It contains different types of files, such as:

DIC files contains the dictionaries for Worzzler. These files are encrypted using AES-128 to protect the 99% of the work you will invest in making your topics. DIC files have a numeric prefix that gives the dictionary's difficulty.

IMPORTANT: You cannot rename your .dic dictionary files after they have been encrypted!! The encryption uses a "salted random password" based on the dictionary's name.
UNDIC files contain the unencrypted dictionaries. To create a dictionary you put your word lists, one word per line, into this file. When Worzzler starts, it automatically encrypts UNDIC files and creates DIC files. Then you remove the UNDIC files from the directory before shipping your files out.
ABOUT files have the same name DIC/UNDIC files and provide information about the dictionary, and are used when the player clicks a column header.
LEVEL files contain the patterns Worzzler uses to fill in words for puzzles. Words can be two or more letters in length. There is a special topic, called "zzGenerator" you can install that helps you to create level files.
GAME files is referred to as a "puzzle collection" inside of the game, and it simply is a list of .LEVEL files. Level files have a numerical prefixed used for ordering.
QUICKSTART.GAMES file lists three ".game" files that describe a short, medium and long duration game as part of the quick start mechanism.
LEVEL.RATING lists the average time it takes to complete a level with an easy dictionary and exact game.
MATCH.SCORE is a file that contains a player's best score for all the match types, puzzle collections, dictionaries and difficulties they play.
GAME.STYLE is a file that contains the text "WORD". This allows Worzzler to change in the future and offer different types of games inside of the framework.

Stage 1: Build a master dictionary

Before you build your topic, you need to build a master dictionary. This will be the most time consuming part of your project, because you will need to come up with enough variation in the words to make the experience for your topic player rewarding enough, since the game is randomly selecting words from the dictionary to fill out the grid. 80% of your time will be in this first stage, especially if you are building the lists from scratch without any kind of source material.

You have two basic ways to do this:

Simply list the words, in lower case(!), in a text file, one word per line.
Recommended: Build a spreadsheet of the words, and mark the words so you can filter the dictionaries make smaller dictionaries of less difficult or different terms. For example, a "plants and animals" master dictionary contains both, but a plants dictionary only contains plant names and the animals dictionary only contains animal names, resulting in 3 dictionaries.

Extended Letters and Symbols

Worzzler is not restricted to English letters, in fact, it can handle spaces, numbers, symbols and an extended UTF-8 character set. This allows you to handle phrases, hyphenated words, special cases and foreign languages.

The only restriction is the way in which Worzzler handles words. When a puzzle is created, the "letters" are shown in upper case, and when words are selected, the first letter is left in uppercase, and the reset of the letters are forced to lower case. This may create issues, especially if using a name such as "NEW YORK", it appears, when selected "New york".

Definitions?

Before you build your first words, you need to decide if your dictionary will contain definitions. This is an optional feature that you can use to transform Worzzler a teaching aid, rather than purely a puzzle/guessing game. When you have definitions, and they guess a correct word the system will show a dialog with the found word and a description, which is separated by a "~" character. (Note: This feature is disabled for Wordsmith games.)

For example:

mind~The mind is a set of cognitive faculties including consciousness, perception, thinking, judgement, and memory.

Definitions can contain some HTML-like takes for styling purposes:

- adds a new line to the text
highlight - applies bold to the word or phrase. Note: is not supported.
highlight - applies italics to the word or phrase.
<size=38>highlight</size> - sets the font size to 38px. Default is 22.
<color=#88aaccff>highlight</color> - sets the color of the word with #rrggbbaa ... rr (RED) gg (GREEN) bb (BLUE) aa (ALPHA)

Example:

mind~The mind is a set of cognitive faculties including consciousness, perception, thinking, judgement, and memory. It is usually defined as the faculty of an entity's thoughts and consciousness. It holds the power of imagination, recognition, and appreciation, and is responsible for processing feelings and emotions, resulting in attitudes and actions.

Links?

You can link to an external website for any definition using a link. For example:

mind~The <size=38>mind</size> is a set of cognitive faculties including consciousness, perception, thinking, judgement, and memory. It is usually defined as the faculty of an entity's <color=#880000>thoughts and consciousness</color>. It holds the power of imagination, recognition, and appreciation, and is responsible for processing feelings and emotions, resulting in attitudes and actions.~https://en.wikipedia.org/wiki/Mind

Warning: Putting in definitions into your dictionaries is a very time consuming process, so unless you are using Worzzler as a teaching aid for students to learn terminology, words, or phrases, you do not have to put in definitions.

Example: Definitions and Links

Stage 2: Create .UNDIC and .about files

After you have created your dictionaries, in the recommended spreadsheet format, you need to copy your words, phrases and definitions into one of more files with an ".undic" file extension. The name of the file is "## name", where the ## is a integer number that is used to:

sort the dictionaries
give the dictionary a relative difficulty value

For example, this is the English words .undic files:

01 easy.undic
02 medium.undic
04 hard.undic
06 master.undic

You Must Create a "Master" Dictionary
You create a dictionary called "Master" that contains all of the words in your topic.

Understanding Dictionary Difficulty

TBD

Create .about Files

"About" files describe information about the dictionary. They appear in the Match grid, when the player clicks a column header. For example this is the description for the "01 Easy.about":

The EASY dictionary contains 828 words and is a subset of the Google(TM) 1,000 most common English words list.

Fewer than 1,000 words appear because this dictionary only contains 4 to 8 letter words and all words are vetted against a Scrabble(TM) dictionary, to remove words like common names, cities, countries, states, contractions, phrases and inappropriate words.

Note: The text of the .about file can contain , , <size> and <color> tags.

Automatic Conversion of Unencrypted Dictionaries ⇒ Encrypted Dictionaries

Since the BULK of your effort is tied up in the creation of dictionaries, we offer a way to encrypt the dictionaries to protect your investment. IMPORTANT: While WORZZLER does create encrypted dictionaries, no encryption system is 100% secure if the application files are included with the data. A determined hacker will deduce how the encryption works, therefore, it is important to understand that while we take precautions to encrypt dictionaries, they are not 100% safe. Encryption exists to deter average or casual hackers.

When you create your dictionaries, you create them in an unencrypted plane text format. We recommend Notepad++ as the Windows text editor because it supports UTF-8 text and supports multiple tabbed windows. When Worzzler starts, any unencrypted dictionary is rebuilt as an encrypted dictionary.

The file on the left are called ".undic" files and the ones on the right are the generated ".dic" files. Once the ".dic" files are generated you can delete the ".undic" files.

Stage 3: create or Find .LEVEL files

In order to guarantee that the game always generates a solvable puzzle, the game uses a pattern. The pattern is a definition that tells the system where it is allowed to put the words for a level. The game traces the order of the letters in the pattern file to know how many letters it needs, the finds a word in the dictionary of that length. It continues until all of the words in the pattern are generated. For example: This is part of a .level file that describes a 9x9 grid. If you look at it, you can see a capital letter followed by a series of lower case letters that form words.

These files are complicated by hand. So we offer two options for setting them up:

Use the Pattern Generator
Assemble Pre-Built Patterns

Note: 9x9 is the recommended maximum size of a puzzle so that it works on mobile devices.

Pattern Generator
The pattern generator is a specially named topic called "zzGenerator". You can select a grid size from 3x3 to 15x15. The topic does not contain a dictionary, instead, when the game is working with a "zzGenerator" topic, it produces a random set of letters to fill the grid. Next you play a Wordsmith mode game, and draw out a when you are in Wordsmith mode. In the example below, the dialog box appears after "Vkr" is drawn out.

To get "zzGenerator" pattern follow these steps. Important: Worzzler specifically ensures that you are on the Windows version of the platform, so while you can install it on MacOS, it does not appear in the available topics.

Start Worzzler
Select "New Game"
Select "Manage Topics" (then click YES at the prompt)
Select "Custom URL"
In the text area type "https://dictionaries.worzzler.ca/Generator.worzzler.txt"
Click Load

This should now download the topic. The actual download is 8KB.

This tells you that:

There are 7 words.
There are 5 words with a length of 3 letters.
There are 2 words with a length of 5 letters.

Options:

YES writes the file and clears the pattern. Files are written to "My Documents\Worzzler"
NO clears the pattern.
CANCEL closes the dialog box.

In "My Documents\Worzzler", you will find a file called:

05 03-05 3=5 5=2.level
Note: If you create another level with the same number of the different types of words, Worzzler will append the file instead of overwriting it.

Format is "GG NN-MM L=C.level" where:

GG is the grid size ... a 5x5 grid
NN is the minimum letters in the grid ... 3 letters
MM is the maximum letters in the grid ... 5 letters
L=C (can be repeated several times)
- L is the number of letters
- C is the count of the number of words with those letters.

If you look inside of the level file, you will actually see 4 copies of the pattern. The differences are the patterns flipped horizontally, vertically, and both, and neither flipped.

Shape Levels

While the standard grid format is a square, you are not restricted to square game boards. In fact, you can have any shape so long as you can form words in all parts that are left over. To make a shape level, simply replace the letters for a "*", like so:

When that level is selected, you get a shape pattern:

Pre-Built Patterns

The Pre-Built Patterns are simply level files that have already been created in the Generator that are available for download. You simply grab the files and append them to each other. The convention is to keep the same sized grid and number of words in each grid to the same about.

In the listing to the left, it is now easy to see what levels are available and which options you have for building up the levels you want.

To get the Pre-Built Patterns, click this link:

http://dictionaries.worzzler.ca/pc/Generic.zip

This ZIP file, contains dozens of files for various levels that have a 3x3 to 9x9 sized grid. Note: 9x9 is the recommended maximum size of a puzzle so that it works on mobile devices.

STAGE 4: Assemble .LEVEL files

Regardless of whether you are generating .level files or we offer, the next stage involves assembly. Suppose, you want to create a 6x6 grid of 4 to 6 letter words. In the Pre-Built Patterns above, there are three files that make up this pattern.

To create a level file, you take all three of these files and append them together, and possibly name the file "04-06.level". There is no specific naming convention for your .level files, but whatever name you give it, just be consistent. Furthermore, if you are going to build a lot of topics, you might want to reuse .level files from other projects.

stage 5: understanding time

Time for a puzzle level is calculated as:

Match Rating x Dictionary Difficulty x Level Rating / Game Difficulty

Match Ratings (with Timed), therefore, untimed wordsmith game have a match rating of 3 and the timed version is 4.

Exact: 1 (1)
Dictionary: 2 (2)
Wordsmith: 3 (4)

Dictionary Difficulty is a rating you give your dictionaries. In the English words dictionary, number at the beginning of the file name dictates the difficulty of the dictionary, as well as the order the names appear in the grid.

01 easy
02 medium
04 hard
06 master

Game Difficulty is the artificial multiplier a player can use to increase or decrease the time they get. A game difficulty of 3.0 reduces the time by 3. A game difficulty of 0.5 increases the time by 2.

Level Rating, which is stored in the "level.rating" file is used to calculate how much time is allotted for a player for a specific puzzle level. Figuring out the actual ratings will be a challenge. Consider these 3 level files:

06 04-06 4=5 5=2 6=1.level
06 04-06 4=1 5=4 6=2.level
06 04-06 4=2 5=2 6=3.level

There is no reason why you cannot create a single level file called:

06 04-06.level

That combines all three .level files above.

When you build a new topic, you will not know what values to set for the level ratings. But you can figure this out, by creating a .game file for each .level file, then play that game at least 5

playing, what you consider is the medium difficulty puzzles, at least 5 or more times, using an "exact / untimed" game. You first create You will want to play the games for each of the dictionaries you are building.After 5 attempts, the game will report an estimated time. This time, converted to seconds, is then divided by the dictionary difficulty. The result is the preliminary rating.

The preliminary rating is how long it takes you, the topic's content master, to complete the game. The next question for you is, what level do you want the players of your topic to aspire to? Do you want them to beat your average time, or, are you lenient and give them more time that it takes you. I double my times, therefore, if playing with a level 1 dictionary and an average time of 28 seconds, I set the level's rating to 56.

Testing the Levels

For example, if the level rating is 45, it means that a player with a level 1 dictionary, play an untimed exact match game, can complete the level, on average, in 45 seconds.

In order to set the permanent level.rating file, first create temporary level.rating and game files. Then play the levels multiple times to get an average.

Therefore, the level rating is 56, divided by the dictionary difficulty. For example, suppose the dictionary difficulty is 2, then the rating for that level is 28.

The game then calculates the amount of time (in seconds) available to play the level as:

28 x Dictionary Difficulty x Level Rating x Game Difficulty

In this stage, you create a temporary "level.ratings" file and give it a value like 100. The "level.ratings" The "level.ratings" is the average time it takes you to complete the levels, and is used to calculate the time your players will take to the complete the levels. The value is the number of seconds, and there is a way to figure out this number in game with you testing. This is stage 6.

stage 6: Build a temporary level.rating file

You create a "level.rating" file and list each of the level file names, and give it a value like 100.

stage 7: build temporary .game files

In this stage, you build one game file for each level. For example, if the level is "05-07.level" you create a game file called "01 05-07.game" and place the name of the level file in it.

Start Worzzler, and go play each level in EXACT mode with your easiest dictionary. In the game's statistics, it will tell you how long it takes for you to complete the level.

stage 8: Test temporary .game files

At this stage, you can now test the games. In this case, I am testing a 6x6 grid, and after 5 attempts, my average time is 56 seconds:

Therefore, the level rating is 56, divided by the dictionary difficulty. For example, suppose the dictionary difficulty is 2, then the rating for that level is 28.

The game then calculates the amount of time (in seconds) available to play the level as:

28 x Dictionary Difficulty x Level Rating x Game Difficulty

Game Difficulty is:

Exact = 1 + 0 for timed
Dictionary = 2 + 0 for timed
Wordsmith = 3 + 1 for timed

Your Skill Level or Their Skill Level?

Now, the more difficult decision. Is 28 the rating you want your audience to strive for? Or do you make it easier and give them more time. I usually double the average amount, because if a player wants more challenge, they can use a handicap to give themselves less time, but if you don't give them enough time, they might be turned off by the difficulty.

stage 9: Test dictionary difficulty

In stage 2, you built some dictionaries and gave it some sorting/dictionary difficulties. The problem is, until you actually play with the dictionaries you created, you won't know what a dictionary's difficulty rating should be. In this section, we will test the dictionary difficulty

Your goal is to try and come up with ratings that result in roughly the same score. For example, in "English Words", the dictionary ratings for Easy, Medium, Hard and Master are 1,2,4,6, respectively. When I play the levels, roughly the same score, but you can see that the times are dramatically different between the dictionaries, yet the score is very similar. That is is the goal of this process.

01 easy.dic~00 005A~1~0~1.0=5,5,1175,1049,5078,277396868,505606973,2835181418

Value	Part Name	Explanation
01 easy.dic	Dictionary	Name of the Dictionary File
00 005A	Level Name	Name of the Level Files (without the .level extension)
1	Game Type	0 - Exact Match 1 - Dictionary 2 - Wordsmith
	Timed/Untimed Flag	0 is untimed 1 is timed
1.0	Handicap	Statistics for a specific handicap value. This means that multiple statistics are kept according to the player's handicap settings.
5 (first)	Score Count	Number of games in which a score was counted. This is the actual number of games played.
5 (second)	Time Count	Number of games in which a time was accumulated. This value can be less than Score Count because we don't accumulate time when the player uses "Give Word". Otherwise, a player just spam "Give Word" and get a ridiculously low average time.
1175	Best Score	Highest number of points of all games played.
1049	Last Score	Points in the previous match.
5078	Total Score	Total points of all matches. To get the average number of points, divide by the "Score Count".
277396868	Best Time (ticks)	Best Time. Times are measured in ticks, and 10,000,000 ticks/second.
505606973	Last Time (ticks)	Time in previous match
2835181418	Total Time (ticks)	Total time of all matches. To get the average time of all matches, divide by the "Time Count".

stage 10: build .game files

The .game files are your puzzle collections in the game. It's a simple text file listing the .level files. Each level of the puzzle collection, opens each level file, randomly selects a pattern, then generates a puzzle from it.

Game File Names
The name of a game file is "## name.game", where "##" is a number that defines the sort order. And name is a short name of the file. Probably 8-10 characters maximum. The following are game files for the "English Words" topic:

stage 10: MISCELLANEOUS files

Two files miscellaneous files:

MATCH.SCORE is a file that contains a player's best score for all the match types, puzzle collections, dictionaries and difficulties they play. Before you deploy the topic, this should be removed "unless" you want to establish a score for your users to beat.
GAME.STYLE is a file that contains the text "WORD". This allows Worzzler to change in the future and offer different types of games inside of the framework.