How is a Java Program Constructed?
The Java program, after it is written as code, becomes a JAR file. This is actually a ZIP file archive.
This ".jar" file is not very different from a Warcraft 3 ".w3x" map in some ways. Alone, the file is an archive of data and it cannot do anything. This is true of a ".w3x" and it is also true of a ".jar" .
To play a Warcraft 3 map, you need the Warcraft 3 game.
Likewise, to run a ".jar" you need a program called "java". Similar to how you can do "war3.exe -loadfile MyMap.w3x", you can also do "java.exe -jar MyJar.jar". The concept is pretty similar. It is an archive of data and scripts, and they can only be run by the interpreter program to run them -- they are not actually true computer code.
What you should understand about how this program is made to get it running (on any operating system)
ReteraModelStudio.exe is a tiny program that doesn't do anything. The actual model editor program and all of its code is inside ReteraModelStudio.jar, which is a ZIP file. We need to start a "java.exe" program running that is loading that ZIP file as the place to get its code data from, that is all and that is the only thing we must do. You can do that on any operating system.
I have run ReteraModelStudio and the code it grew out of on Ubuntu Linux, and I have run ReteraModelStudio on Gentoo Linux. I have run it on Windows 7 64-bit, and I have run it on Windows 10 64-bit. Once in my life, in the summer of 2012, I ran a previous version of the program on Windows XP 32-bit on a dying laptop, although it was very slow. I sent this model studio to a friend who uses MacOS in 2018, and he said it worked for him on MacOS also. But in each of these cases, we were not using ReteraModelStudio.exe -- we were using the JAR, where the real program is. Obviously the ".exe" file is only going to work on Windows.
ReteraModelStudio.exe is just a wrapper to launch "ReteraModelStudio/jre/bin/java.exe" that should be included with the download.
What I am saying here is that I included the Java runtime with the program. I'm not certain whether we are really supposed to do it that way, but the Java automatic updater is a tremendous irritation that is generally unnecessary and has made many users complain to me that they will never install Java no matter what, despite anything to do with how the language is used or what it can do. I do not have much interest forcing people to install the Java updater, especially if they do not want to. So I included all of Java in the download, to increase the probability that the program works for people who don't care about any of that and don't want to go through annoying Java installations.
When I double-click ReteraModelStudio.exe, nothing happens. What next?
So, once you know all of that, here are the steps to debug the program:
- Check your computer's operating system. If it is any 64-bit Windows, then generally the EXE should probably work as intended and we need to SKIP to Step 6. But if you are on 32-bit Windows, or Linux, or Mac, or something else, then you will not be able to use the EXE included. In that case, go to Step 2.
- Because your computer cannot use the EXE that is included, you must install Java. To do this, I usually Google Search "Install Java". If you do not like Google, it appears that the correct website is https://www.java.com (java DOT com) which is rather logical. Go to this website and install the Java application. The recommended version of Java to use for the Matrix Eater is Java 8. Originally, any new version of Java was supposed to be able to run older Java programs. If you code a program using Java 6 or Java 7, you can run that program using Java 8. From Java 9 and afterward, I think this backwards compatibility was broken. I do not believe this program would work on Java 9, Java 10, or Java 11, but I have not tested it more than possibly one time, when it did not work for me for a reason that I do not know.
- Using the Java application that you installed in Step 2, your computer should now be able to run "java" from the command line. On Linux or Mac, you can open this by searching for "Terminal Emulator" or "Terminal" or something related (per operating system) in your list of applications. On Windows, press Windows Key + R to open the Run box, and type "cmd" into the box. It does not need to be administrator.
- Regardless of your operating system if your installation of Java is successful, and you have opened the command line of your operating system, then you will be able to type "java -version" into the box, and it will print out something for you.
- If the box tells you something such as java: command not found then this means that it did not install correctly. You could try restarting your computer. If this does not help, Google search how to run Java on your specific operating system. On some unusual versions of Linux, maybe you would need to type "/usr/bin/jre7/bin/java -version" or something similar. It might have a special location on Mac OS, if they do not install it naturally. This may depend how you install. On Windows XP or a weird Windows, in the worst case, you can probably type "C:\Program Files\Java\jdk8<versionnumber>\bin\java" instead. On any operating system, if you found and ran this program like we see above, it should show this version information. That means you found it.
- Find the folder where you downloaded and unzipped the program and its readme from the Hive Download button. In my case, this was in the Windows Downloads folder. I get a result like this:
- Click on the folder location on the top of this window so that it becomes something that you can copy, and then press CTRL+C on the folder path so that now you have copied that location.
- Open the command line. You may already have done this on Step 3 if you are using the non-standard process. On Windows, press Windows Key + R to open the Run box, and type "cmd" into the box. It does not need to be administrator.
- In your command line, regardless of operating system, type cd which is the special command to open a folder. Then press SPACEBAR. Then paste the clipboard contents that you copied on Step 7. On Windows, you can do this by doing either CTRL+V or Right Click in the black CMD window. If this does not work, right click on the top of the window and go to Edit -> Paste.
- Now, at this point, the black window will contain something like "cd C:\Users\micro\Downloads\Reteras Model Studio\ReterasModelStudioV0.01". Go ahead and press the ENTER key.
- On Windows, you should now see this box give you back a prompt that is showing the folder you have typed. If this fails, it is possible that you copied the incorrect location on the computer. That is not a problem, just try again from Step 8 and make sure that you copy the correct location.
- If you are doing the non-standard setup, then enter the name of the "java" program that you found in Step 4 or Step 5. If you skipped those steps because you are doing the standard 64-bit Windows setup, then enter into the box .\jre\bin\java but do not press enter.
- After entering the name of this java program, on the same line, type in -jar ReterasModelStudio.jar
- Now press ENTER. This should command the system to run the program in the debugging mode that will show additional information, and so the information that you see next will be very important for how to fix your setup.
- On a computer with a fresh install of this program that has never used the Matrix Eater application precursor, nor the Retera Model Studio, this presents me with a popup that asks me where my Warcraft 3 Installation is located. You can also give yourself this popup by deleting the config information in C:\Users\<Name>\AppData\Roaming\JWC3 even if you have used the program previously. On Linux or Mac, these temporary files are in your home directory in a dotfile folder called ".jwc3".
- If you do not see the popup shown above, go to Step 17 for debugging. Otherwise, skip ahead to Step 20.
- The second most likely case, if you do not see the popup above, is that you might be on a computer where Warcraft III is not installed, or you only have installed the very latest version that no longer reports to the Registry where it is located. So, if you are using Patch 1.30 or newer (this might also affect Patch 1.29) or your Warcraft 3 installation was created in a nonstandard way, you might see the popup shown below. If not, skip to Step 19 to debug when Java is not working at all. If Java is working, you are generally guaranteed to see one of these popups, unless cached information was loaded from previous use of the Matrix Eater or from Retera Model Studio.
- When you see this popup Error retrieving Warcraft III game directory... This is actually a very good sign. It means that you are well on your way to making the program work. When this happens, press OK. Now you will see the popup on Step 15, but you will see that I have no idea what to suggest to you, because my code could not find the Registry Keys for Warcraft III, so it will show some default folder that is not very useful. Enter the location of your Warcraft III installation that is NOT in My Documents and contains either "Warcraft III.exe" or "Warcraft III Launcher.exe" in this box. It is commonly "C:\Program Files\Warcraft III" or something similar.
- If the popup boxes do not appear, and Java is not working at all, then generally this will mean you have one of three problems.
- The first possible problem is if Java is not installed correctly at all, or you did you enter the location of java correctly. This will show some kind of error from the system and then it will do nothing else. Here are two examples of how this might look:
Both of these errors shown above indicate that the Java installation is not valid. The first one means that the folder we typed does not even exist, and the second one means that the java we tried to use is not installed or is not valid. You should be able to fix this by revisiting Step 2.
- You might also get Error: Unable to access jarfile ReterasModelStudio.jar . If you see this, it means that the Java installation is good, but we did not type the correct name of the JAR that contains all of my program code. In the example below, I deliberately entered a mistake that says "ReteraModelStudio.jar" instead of "ReterasModelStudio.jar" and so I caused the error to occur.
There is also a second error that we might get with a good Java installation but where there is something wrong when it tries to find my code. This would occur if you had the wrong version of Java installed, in which case you might get an error like "Unsupported major.minor version 52.0". I get this error if I attempt to run the application using Java 6 (since it requires Java 8):
- You might get some other weird bug -- such as something wrong with my code that I don't know about that is specific to your computer. In this case, you will see a big bunch of text starting with "Exception in thread" (similar to the version issue shown above, but in this case there will not be anything about UnsupportedClassVersionError). Generally, if you see the word Exception this indicates something is wrong with the code of the program that I wrote, even though Java is running correctly. Here is an example of what this might look like:
One possible culprit for this problem would be if you are using an operating system or hardware that the OpenGL code for rendering models does not support. Apart from running Java, there is special OpenGL code that I am using that tries to load immediately after the Java code starts up. At that point, it goes back to linking binary program code that is per-operating-system and can fail in ways specific to your computer, but it should report the reason for the problem with something such as UnsatisfiedLinkError or RuntimeException: Unable to extract LWJGL natives . Either of these would mean a failure in that subsystem for rendering 3D graphics. Generally, this uses the same LWJGL library for rendering 3D in Java that was used to build Minecraft. Another possible error like this would be when the program fails to find information in the game data, such as this failure to load the Unit Data SLK tables that occurs if I install the game in a different language (this should hopefully be fixed in Reteras Model Studio v0.03):
- Press OK after entering the Warcraft III installation path, and the application should start. If it does not, report back on this forum what kind of output you receive in the black terminal window. Generally, that will be the most helpful way that you can tell me something that I can fix.