# Kuubik - Cube Simulator/Learning Software



## Kelsparov (Jun 15, 2014)

I wrote a Rubik's cube (3x3x3 only) simulator/learning software for my A Level Computing project, and I thought I would share it with everyone.

*You can download the program here*. After following the link, click 'File - Download' to download all files and then extract the folder on your computer to wherever's suitable. You can open the program by opening 'Kuubik.jar'. The download includes a user manual.

*The main aims of the project were to*:

Provide an interactive learning facility for beginners.
Help users keep track of their times by saving the times in a database and calculating statistics based on these times.
Provide features to generate solutions for a given cube state in order to help learners with tricky problems.
Provide users with a virtual alternative to the physical Rubik's cube so that more automated features are available.
Allow users to share their progress (statistics, graphs of times, cube states, scrambles, solutions etc) with others in order to further their learning.
*Functionality*:

Generate a solution for the current state of the cube (method is Cross, Corners, Edges, Edge orientation, Corner orientation, Corner permutation, Edge permutation). The generated solution includes the notation for the moves and an English explanation of what is happening (designed to help beginners understand the thought-process behind certain steps).
Scramble the cube and record the time taken to solve the cube (timer is stopped when cube is solved). 
Automatically calculates the most-recent average of 5, 12, 50, and 100, as well as an overall mean, and tracks your best average of 5, 12, 50, and 100.
Save the current state of the cube to file.
Save the statistics to pdf.
Save the recorded times to a permanent database and view these times, along with all relevant information, in the _Solve Table_.
Load a cube state from file.
Load the information about a solve into the program.
Manually add information about a solve.
View a graph of your past 12 times.
Add temporary scrambles which can be loaded from a text file (one scramble per line) or added manually, and these scrambles can then be applied to the cube automatically.
Save algorithms along with comments.
Edit the preferences (inspection time, size of text for scramble, and real-time solving speed).
Cancel the current solve/timing in progress.
Paint a custom state on the cube using a colour palette.
Generate a solution for a selected piece by clicking on the piece.
Generate and apply a random scramble.
Learn how to solve the Rubik's cube by using the tutorials, which can be accessed through the tutorial menu.
Replay the execution of a solve by double-clicking on a listed time and then clicking the 'View Execution' button.
*Quick Guide*:

To start a solve, click the 'Start New Solve' button at the bottom of the window, or press 'Alt + 1', and then the inspection timer will start counting down.
Press and release the space bar in order to start the timer. You can start the timer while the inspection timer is running or you can start it manually when the inspection timer is not running.
To cancel the current solve, go 'Tools - Cancel Solve'.
After solving the cube, or after re-pressing the space bar, your time will be recorded in the list at the right-hand side of the screen. If you used the automated timing features, the scramble, solution, time, and penalty will also be recorded.
To generate a solution for the current state, go 'Tools - Solve Cube' (this also performs the execution automatically, so if you don't want to lose the current state, save it by going 'File - Save Cube State - txt').
Double click a listed time to edit it.
Press 'Delete' after selecting a time to delete it.
To view the database of solves, go 'View - Show Solve Table'.
To edit the preferences, go 'Options - Preferences'.
To exit tutorial mode, go 'Tutorial - Exit Tutorial'.
*Limitations of the system*:

The system generates solutions using only the beginner's method. Advancements of the system could include more-advanced methods such as CFOP, ZZ, and Roux etc.
Custom statistics are currently not available, e.g. calculating the average of 15, or average of 20 etc.
The time graph shows 12 times or fewer – it does not show times over a custom range.
The key-mappings for performing moves are fixed – they cannot be customised.
The sticker colours of the cube cannot be customised, e.g. you cannot change the yellow face to show purple stickers.
The system does not currently support custom notation; only WCA notation is supported.
Certain tutorial files or solve-information files may cause the system to crash.
There is currently no English-like explanation for solving the cross.
The program currently does not run on OSX.
*Controls*:


Spoiler





```
[B]Move	Key[/B]
U	j
U’	f
D	s
D’	l
R	i
R’	k
L	d
L’	e
F	h
F’	g
B	w
B’	o
M	x
M’	.
Rw	u
Rw’	m
Lw	v
Lw’	r
x	y
x’	n
y	;
y’	a
z	p
z’	q
```



*Keyboard shortcuts*:


Spoiler





```
[B]Action				Shortcut[/B]
Start new solve			Alt + 1
Save statistics			Ctrl + S
Load cube state			Ctrl + O
Add solve			Ctrl + D
Edit selected solve		Ctrl + E
Cancel solve			Ctrl + Q
Solve cube			Ctrl + R
Time graph – Save as image	Ctrl + S
Time graph – Close window	Ctrl + W
Time graph – Reset zoom		Ctrl + R
Time graph – 2D			Ctrl + 2
Time graph – 3D			Ctrl + 3
```



*How to create tutorials*:


Spoiler



The data for a tutorial should be written in a text file. A tutorial consists of sub-tutorials, and the format of these tutorials is:

```
[I]Mandatory comment line[/I]
“SCRAMBLE:”
[I]Scramble to be applied. If no scramble is to be applied, the character “N” should be used.[/I]
“DESCRIPTION:”
[I]Description of the current sub-tutorial to be shown to user.[/I]
“EXPECTED FINAL STATE:”
[I]The steps that are expected to be solved.[/I]
“HINT:”
[I]Any number of hints (at least one) here - one hint per line.[/I]
“OPTIMAL SOLUTION:”
[I]Optimal/expected solutions to the problem.[/I]
“EXPLANATION:”
[I]Explanation of the solution to the problem[/I]
“*”
```

If the sub-tutorial requires the user to perform moves, then the word "ENABLE" (in upper-case) should be included in the comment line, e.g. "Beginner Tutorial - ENABLE".
If the sub-tutorial requires the user to solve a problem, then the author must include the 'expected final state', 'hint', 'optimal solution', and 'explanation' sections.

A sub-tutorial must have one of the following formats:

Comment, Scramble, Description
Comment, Scramble, Description, Expected Final State, Hint, Optimal Solution, Explanation

In the 'expected final state' section, the author can specify which pieces/sub-steps they wish to be solved (one criterion per line). For example:

```
EXPECTED FINAL STATE
w-g
w-o
w-b
```
means that the author wishes for the white-green edge, the white-orange edge, and the white-blue edge to be solved.

*List of all criteria that can be specified in the 'expected final state' section*:

"x-y" where x and y are two different, valid colours for an edge piece.
"x-y-z" where x, y, and z are three different, valid colours for a corner piece.
"cross"
"corners"
"edges"
"edge orientation"
"corner orientation"
"oll" meaning both edge orientation and corner orientation should be solved.
"corner permutation"
"edge permutation"
"pll" meaning both edge permutation and corner permutation should be solved.

The 'hint' section should include one hint per line. For example:

```
HINT 
Try moving the white-orange edge out of the way first.
Perform F’ R then try to solve it from there.
```

After you complete a sub-tutorial, you can add another sub-tutorial in the same text file by adding it after the asterisk (*).

*Example*:

```
Example of R U R' case. ENABLE
SCRAMBLE:
L2 D L U F' U2 D F2 L D F' R2 B U2 R2 F' B' U2 L2 F2 D2 L' B R2 U L2 z2 U2
DESCRIPTION:
There are four situations you need to recognise when solving the corners. For now, we will learn how to solve a corner if it is in the top layer and white is facing to the right.
Look at the White-Green-Orange corner.
Its 'destination' is between the White, Green, and Orange centres (since those are its three stickers), so we must bring the corner 'above' its destination. In this case, the corner is already above its destination. To solve a corner, we must hold the cube so that the corner is at the Top-Front-Right position, which is where the corner is in this case. The white sticker is facing to the right, so now we can learn an algorithm to solve this piece:
R U R'
If you perform these moves on the cube, the White-Green-Orange corner will be solved.
Try solving the corner using the moves provided.
EXPECTED FINAL STATE:
cross
w-g-o
HINT:
Perform R U R' - ('i j k' on your keyboard)
OPTIMAL SOLUTION:
R U R'
EXPLANATION:
We rotate the cube so that the corner is at the Top-Front-Right position, then we see that the white sticker is on the right, so we perform the algorithm (R U R').
*
Second sub-tutorial.
SCRAMBLE:
B L2 B2 D2 F L2 F2 U2 B R2 F2 L B2 R2 D' L2 B2 F D' L' U' D F R F2 U R U R
DESCRIPTION:
Welcome to the second sub-tutorial
*
```



*Screenshots*:


Spoiler


























I might make some improvements to it over summer, but for now, I'm fed up with it haha; the paperwork has just been a nightmare, so I'm going to take a break from this stuff for a while. I finished the program a few months ago, but I didn't feel comfortable publishing it before I had submitted it for marking. 

Make sure to check the user manual if you need help with any part of the program.

If you have any questions, (constructive) criticisms or other comments, feel free to post them 

*Download​*
*P.S.* The name 'Kuubik' is the Estonian word for 'Cube' - I think it's kinda cool that it's a homophone of the English word 'Cubic' and resembles the spelling of the name 'Rubik'. 

Kelsey


----------



## Lucas Garron (Jun 16, 2014)

> The Java JAR file "Kuubik.jar" could not be launched.



:-(

(OSX. System console doesn't have anything, and I can't find a way to view the Java console without downloading something I don't want to.)


----------



## Kelsparov (Jun 16, 2014)

Lucas Garron said:


> :-(
> 
> (OSX. System console doesn't have anything, and I can't find a way to view the Java console without downloading something I don't want to.)



No! I had hoped that it would work on Macs as well, but I must have compiled it in such a way that it doesn't work on Macs (I'm very unfamiliar with creating GUIs and exporting JAR files, so this is my own fault). Sorry about that, I'll update the post to say that it currently doesn't work on OSX


----------



## Filipe Teixeira (Jun 16, 2014)

Its not oppening


----------



## Kelsparov (Jun 16, 2014)

filipemtx said:


> Its not oppening



Which OS are you using? And have you definitely extracted the folder? Make sure you version of Java is up to date.

I have tried this on other computers (even school computers with huge Java restrictions) and it works, so I'm not sure what the problem could be other than and old version of Java or something.


----------



## Filipe Teixeira (Jun 16, 2014)

I tested in another computer and it worked. Its a nice sim.


----------



## Kelsparov (Jun 16, 2014)

filipemtx said:


> I tested in another computer and it worked. Its a nice sim.



That's good. Thanks for the comment


----------

