Setting up JWildfire as a Project in NetBeans

In this tutorial, I’m going to show you how to set up JWildfire in the NetBeans IDE so you can edit the software in one of the best Java IDEs available. This will allow you to make custom variations of your own without having to use the custom_wf variation.

Edit March 4, 2013: Please see part 2/method 2 if you wish to modify JWildfire beyond simply making custom transforms. As it turns out, the method directly below will only allow you to create custom transforms but will run into errors if you try to modify the engine beyond VariationFunctionList.java (as used below).

For this tutorial, I’ll be using NetBeans 6.9, although any version from 6.2 and up should work as long as you have the Eclipse project importer. I don’t know what IDE JWildfire was written in originally, but the language is Java, and the importer works fine.

Step 1: Downloading the files

In order to set up the project files, you will need both the latest working copy of JWildfire and the master files.

The working program can be found on the creator’s (Andreas Maschke) website:
http://www.andreas-maschke.com/?page_id=351

The master files (the SVN files) are found on Github at:
https://github.com/thargor6/JWildfire

In the root directory of Github, there is a button that allows you to download everything. The download will be a zip file called JWildfire-master or something to that effect. I will refer to this hereafter as the “master folder”.

Step 2: Setting up the folders

Place both the master folder and the working program folder in the same directory. We’ll call this the “base folder”. You will need to unzip the master zip file but make sure it all ends up in a new container folder we’ll call the “master folder”. You will also need to unzip the working program folder, so do that as well, keeping the contents in its own folder.

Go into the working copy folder and into the folder called “lib”. There you should find a single file called “jwildfire.jar”. This is the program itself – it’s nothing but a .zip file containing everything. Create a copy of this jar file and move it to the base folder. Change the extension of this jar folder from “.jar” to “.zip”. Now unzip the contents to a new folder. We’ll call this the “library folder”.

Once you’re done, you should have two important folders: the “master folder” and the “library folder”. Both of them should be in our base folder so that they are easy to find.

Step 3: Creating the project in NetBeans

Open NetBeans. In the File menu, select “Import Project” -> “Eclipse Project”. You should get a dialog box that requests how you want to load the project. Select “Import Project ignoring Project Dependencies”. This will make two fields available: “Project to Import” and “Destination Folder”, next to which will be buttons allowing you to browse your file system.

For “Project to Import”, select the “master folder”. For the “Destination Folder”, create a new folder. This one we’ll call the “main project folder”. Whatever name you give this folder will be the project name.

Now confirm it. NetBeans will create some project files within the main project folder, but no code will ever go in here (ironic as that is).

Step 4: Importing the code

On the left side of your screen in NetBeans should be a panel with three tabs: Projects, Files, and Services. Select the Projects tab. Right click on your new project and select “Properties” from the drop-down menu. That option should be at the very bottom of the list.

You should now be presented with a complicated dialog box showing project properties. On the left side should be a list of settings areas, including “Sources” and “Libraries”.

Select “Sources” from this list. There should be an area to the right labeled “Source Package Folders”. To the right of this is a button labeled “Add Folder”. Click the “Add Folder” button. Open the “master folder” in the file system browser window and select the “src” folder. Once you’ve added this folder, click “Add Folder” again and select the “library folder”.

On the left side of the Properties dialog, select “Libraries”. This should be immediately below “Sources”. To the right, there should be a new screen with a set of tabs, one labeled “Compile”. Select this tab (if it isn’t already selected), and click the “Add JAR/Folder” button. Do NOT click “Add Library” or “Add Project”. In the file system browsing window, select the library folder. You can select the .jar file here if you want, though I’m not sure if it matters.

Step 5: Cleaning and Testing

The JWildfire code unfortunately contains some unicode characters not recognized on all systems (much less NetBeans).

Build the JWildfire program. This is the easiest way to find all of the “bugs”, which are mostly comments. I changed the missing characters to “?”. NetBeans is picky, so you will also need to change the file “BilinearFunc” to “BiLinearFunc” (capital “L”) so that it matches the class inside. You can do this with the “refactor” option that appears when you right click on the file in the Files list on the left side of your screen.

You should be able to build it cleanly now, but there is one more step.

Try running the project (debug mode). NetBeans will ask for an entry point and should give you the option of either the “launcher” or the “desktop”. Select “Desktop”!! If you accidentally select “launcher”, you will have to recreate the NetBeans project. If you make a mistake, go to the top menu bar to “Run”. Select “Run”->”Set Project Configuration”->”Customize”. Selecting “launcher” only displays the launch screen and then fails to find the program start. You can read this in the messages by checking the “debug” radio option on the launch screen. Selecting “desktop” on the other hand will load up the main program of JWildfire.

Once you have selected the entry point, NetBeans will use it thereafter. The only way to override this activity is modifying the NetBeans files (which I don’t know how to do).

Note, you don’t need to update the launcher after you modify JWildfire.

Please note, JWildfire will take a full minute or two to load. It’s a very big piece of software.

Step 6: Creating Your Own Variation

All files from here on out will refer to those of org.jwildfire.create.tina.variation in the Files tab.

There are two files of primary interest:

  • SimpleVariationFunc.java
  • VariationFuncList.java

The first file – SimpleVariationFunc – contains a class that must be extended for you to create a variation. Only two functions – “transform” and “getName” must be implemented. The rest are optional.

The second file – VariationFuncList – adds the variations to the list of available variations for JWildfire. Within the file’s class, there is a field called “static” that contains a series of “registerVariationFunc” calls. You can add your class to the bottom of this list with such a call, but you have to add “.class” at the end of the name of your class when sending it to this function. For example:

registerVariationFunc( myClass.class );

The class type is sent to the list because JWildfire creates new instances of the variation for every fractal rather than creating an instance of every variation that might be needed.

NOTE: When you create variations, be sure to put them in the same folder as all of the other variations. This should be common sense, but I’m adding it for clarity.

Extra Step: Running JWildfire outside of NetBeans

Once you’ve finished changing JWildfire, running it separate from NetBeans merely requires establishing the same file structure as the JWildfire launcher expects. Note: You cannot run the distrobution jar file that NetBeans output independent of NetBeans without the launcher.

To set up the launcher, let’s create a new folder in the project folder (created for NetBeans), called “test”. In test, place a copy of jwildfire-launcher.jar from the “library folder” (the working program). Also in this folder (“test”), create a folder called “lib”. Into the folder “lib”, place a copy of the distributable jar that was output by NetBeans into the folder “dist” in the project folder. Rename this .jar as “j-wildfire.jar”.

In short: the launcher merely needs to find the program jar with the relative path of “lib/j-wildfire.jar”.

Method 2
Modding the Engine

So you want to modify the program, eh? The method above won’t work, so I figured out how to set up the program as before. I will assume you have downloaded the files. If not, please read section 1 of part one – download the program jar and download everything from Github for JWF.

Step 1: Setting up the folders

Set up a folder that we’ll refer to as “base”. It doesn’t matter where this is – you’ll set the reference to it in Netbeans – but for organization, you might want to keep it near where you’re Netbeans project folder is going to be.

Unzip the master folder that you acquired from Github. I’ll call this the “master folder”.

The program jar can be converted to a zip by changing the extension to .zip. Do this, unzip it and find the folder called “lib”. This is the only folder of interest. Inside is a jar file. Change this to a zip and unzip it. We’ll call this folder the “library folder”.

For a moment, look inside both the master folder and the library folder. Notice, the master folder is missing a few sub folders that the library folder has. Copy those from the library folder and move them to the master folder. You do not need to copy the folders that already exist in the master folder.

Within the library folder sub folders are class files. These files are support files and should not be modified.

Within the library folder is a folder called “org”. From here, copy the folders “nfunk”, “sunflow”, and “codehaus” and place them in the corresponding folder in the master folder.

Step 2: Creating the project in NetBeans

This step is the same in the first part of this article.

Open NetBeans. In the File menu, select “Import Project” -> “Eclipse Project”. You should get a dialog box that requests how you want to load the project. Select “Import Project ignoring Project Dependencies”. This will make two fields available: “Project to Import” and “Destination Folder”, next to which will be buttons allowing you to browse your file system.

For “Project to Import”, select the “master folder”. For the “Destination Folder”, create a new folder. This one we’ll call the “main project folder”. Whatever name you give this folder will be the project name.

Now confirm it. NetBeans will create some project files within the main project folder, but no code will ever go in here (ironic as that is).

Step 3: Importing the code

This step is alittle different than the step in the first part of this article.

On the left side of your screen in NetBeans should be a panel with three tabs: Projects, Files, and Services. Select the Projects tab. Right click on your new project and select “Properties” from the drop-down menu. That option should be at the very bottom of the list.

You should now be presented with a complicated dialog box showing project properties. On the left side should be a list of settings areas, including “Sources” and “Libraries”.

Select “Sources” from this list. There should be an area to the right labeled “Source Package Folders”. To the right of this is a button labeled “Add Folder”. Click the “Add Folder” button. Open the “master folder” in the file system browser window and select the “src” folder. This is all we need!

On the left side of the Properties dialog, select “Libraries”. This should be immediately below “Sources”. To the right, there should be a new screen with a set of tabs, one labeled “Compile”. Select this tab (if it isn’t already selected), and click the “Add JAR/Folder” button. Do NOT click “Add Library” or “Add Project”. In the file system browsing window, select the master folder’s sub folder “src”.

Step 4: Cleaning

The JWildfire code unfortunately contains some unicode characters not recognized on all systems (much less NetBeans).

Build the JWildfire program. This is the easiest way to find all of the “bugs”, which are mostly comments. I changed the missing characters to “?”. NetBeans is picky, so you will also need to change the file “BilinearFunc” to “BiLinearFunc” (capital “L”) so that it matches the class inside. You can do this with the “refactor” option that appears when you right click on the file in the Files list on the left side of your screen.

You should be able to build it cleanly now, but there is one more step.

Try running the project (debug mode). NetBeans will ask for an entry point and should give you the option of either the “launcher” or the “desktop”. Select “Desktop”!! If you make a mistake, go to the top menu bar to “Run”. Select “Run”->”Set Project Configuration”->”Customize”. Selecting “launcher” only displays the launch screen and then fails to find the program start. You can read this in the messages by checking the “debug” radio option on the launch screen. Selecting “desktop” on the other hand will load up the main program of JWildfire.

Once you have selected the entry point, NetBeans will use it thereafter.

Note, you don’t need to update the launcher after you modify JWildfire.

Please note, JWildfire will take a full minute or two to load. It’s a very big piece of software.

Step 5: Testing, Troubleshooting, and Running out of Netbeans

Netbeans automatically compiles the code once it is saved, or at least that’s how it defaulted the settings for me. This may have to do with the fact that compiled code was included in the source code folders, but I don’t know. The fact that the code is compiled automatically is convenient, but here’s how you have to treat it:

Whenever you wish to run the program, run or debug run the program, don’t try to build or clean+build.

When you want to export the program to run it apart from Netbeans, clean+build it (use the “clean and build” option), DO NOT merely “build” it.

Things may eventually mess up, so here it is in bold:

TROUBLE-SHOOTING

If Netbeans starts acting stupid, go to its data folder where it keeps its cache folder. On Windows Vista, this is:

C:\Users\myusername\.netbeans\6.9\

Where “6.9” is the Netbeans version I am using.

Inside this folder is a sub folder called “var”, and inside there is a folder called “cache”. Delete the folder “cache” (while Netbeans is not running). Once you boot up Netbeans, it will recreate its own cache and it should fix the issues. If it doesn’t, it could be your program. Make sure that you files list the package they are in. Be sure to use refactor when renaming variables. Oh, and never rename a class within the class file. Always rename a class by refactor rename of the file via the Files tab (on your left in Netbeans).

Running outside of Netbeans

Again, clean and build your project. Go into the “dist” folder in your Netbeans project folder and copy the file “JWildfire.jar” (it should be the only file there). Rename it “j-wildfire.jar” and place it in a folder labeled “lib”, a sub folder of the folder where you keep your launcher jar.

Advertisements

About chronologicaldot

Just a Christ-centered, train-loving, computer geek.
This entry was posted in art, freeware, software and tagged , , , , , , , , , , , , , , , , , , . Bookmark the permalink.

Enter the space and time of my little world... Welcome Earthling.

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s