This zip file contains a single SQL dump for two tables – region and subregion.

Region contains 248 entries, with the following data for each country: ISO code, 3 digit ISO code, fips code, country name, continent, currency code, currency name, phone prefix, postal code regex, languages and geonameid. Subregions contains region ID, name and timezone. The timezone format is “America/Los_Angeles”, “Europe/Madrid”, etc. Unfortunately, some states have multiple timezones and this is not taken into account.

There might still be some issues with some countries not having an accurate state list, but this list is more comprehensive than anything I was able to find online.

Download the list: region.sql

This calculator contains all units for all 3 races and allows for race changing and resetting the build. It also begins to toy with styles and the UI, although I didn’t spend much time other than getting elements in the rough position that I would like them to be.

I dropped back to a more minimal approach because I felt like the more advanced approaches I was working on were going in the wrong direction. I’d ultimately like a more advanced system, but I want to rewind a bit and go back to basics and consider alternative approaches to the other systems, that relied heavily on large data structures to store data, at times storing it repeatedly for different purposes.

I also stored unit actions (such as build Probe, warp in Pylon, etc.) as functions within each unit. As I wrote the functions, it quickly became apparent that a huge number of functions are identical and should only be written in one place.

This build shows me the viability of storing unit actions within the function and keeping track of unit timelines within the unit, but also shows the weaknesses of displaying the timeline when I have to scan every unit for every second to see what has been done. It still does not take into account that you need a Gateway before you can make a Zealot, but I chose to not pursue that in this build when all of the flaws of this build became apparent. It does, however, take into account queuing and will not let you build more than 1 Probe from a Nexus at any one time.

I will begin my next iteration very soon and hope to have that online within the next few days. Each iteration definitely teaches me a lot about what will and will not work. I am still very far from a final build, but I still think it is possible to get the final build online before the game launches on Jul 27, 2010.

This URL sharing is one of the most critical requirements of this system. This calculator is designed to aid strategy discussions and a key part of that is showing a friend your strategy. As you update your build order, the URL will be modified, so you can send the build order at any time and anyone going to that URL will see what you see.

This calculator also allows you to switch between Terran, Protoss and Zerg, albeit in a clunky way that will be addressed before the final build. In order to change race, change the URL to start the build order string (from # to the end of the URL) with T, P or Z. In both FireFox and Chrome, I had to refresh the page after changing the URL before the new race properly appeared.

StarCraft II Build Order Calculator

Sample Build (9 Pylon / 12 Gateway Protoss build)

This build is the first JavaScript prototype of the S2BOC. I decided at the very start that I would be building this in a client side language to reduce server strain, and so doing tests in PHP is very impractical. It uses the jQuery library and contains a custom extension to generate the build order. It shows off the abilities of the system to add units and calculate the amount of minerals available at any given time, as well as calculate the earliest moment that a unit can be built.

My next iteration should be online and viewable this weekend. This iteration will contain features not shown in this version, like taking queues into account and building requirements. I estimate there will be another 10-12 iterations before I consider writing the final version.

The calculation is based on finding out how many probes exist at this time, how long they have existed, and multiplying that by 5/6. 5/6 is the number of minerals gathered per second per harvester (before saturation, at least). Once I have found the total minerals gathered, I get a list of all units that have begun construction at that time and subtract it from the total and return it.

The formula for calculating wealth seems okay, but the initial array contained far more data than I ended up using and the formulas were a bit too hard coded. Things like MULE and Chrono Boost are not being accounted for, and supply count is ignored as well.

I like the idea of a function being passed a time value and returning a snapshot of the build status at that time, and the array storing the build information also containing when each item was started. This system would fairly easily allow new commands to be inserted mid way through the build.

I definitely need to make the calclations more dynamic, though. I’m also still unsure of how to handle the starting Nexus and 5 Probes. This system puts the build time at -100 and -17, respectively, and always adds 700 minerals to the mineral count.

All in all, this iteration did show some interesting ideas, particularly with where to store data on all of the units. I ended up sliding it in as an array inside the build class, but that seems impractical. I should probably set a race as a class, units as a class, buildings as a class and special abilities as a class. My next experimentation will involve testing those methods for viability.

The project is just beginning the iterative development phase, with some small scale tests of single aspects of the system. I began writing my notes on the site in plain text, but it quickly became apparent that I will have enough notes to require a full fledged blog.

Expect to see a flood of posts in the coming days as I think aloud on how to build this system and test various methods of implementation. I will be building it through iterative development, and as such there will be many micro tests in the coming weeks of single aspects of the system.

The first test that has already been pondered upon and attempted once is how to store the build order data in a URI without that URI becoming ungainly in length. You can see my notes on that test and see a sample of this one attempt in the iterative development section of that site.

Over the past few days, I have been exploring methods to do this, with the following requirements:

• Keep all theme files separate from the application
• Require no changes to existing controllers and views to implement or change a theme
• Allow multiple applications on the same Kohana build to use the same theme
• Provide support for cascading themes

After a few failed attempts, I have found a solution that covers all four requirements and is pretty easy to implement. Of course, it is easier to implement this from the start, but if you have an existing Kohana site, it shouldn’t be too difficult to integrate this theming setup into the site. The concept of the theme is simple: create a theme as a module and then use hooks to implement the theme elements as appropriate.

Step 1 – Enable hooks

Without hooks, this theming set up won’t be able to execute at the proper time, and timing is essential. In order to enable hooks, open up application/config/config.php and change $config['enable_hooks'] to TRUE. With hooks enabled, all files within a hooks directory are included. This will be the starting point for inserting the theme content around the template.

Step 2 – Create a theme folder

One of my stated goals for the theme was to keep all theme files inside a single folder. This encapsulation allows for very easy modification, copying and replacing of themes. Make a folder called themes, and a subfolder named after the theme. This theme folder will operate just like a module folder, containing config, controllers, hooks, views, etc. My directory tree now looks like this:

/httpdocs
    /application
    /modules
    /system
    /themes
        /visual77
            /config
            /controllers
            /css
            /hooks
            /images
            /views
    /index.php

Step 3 – Add the theme folder to the list of enabled modules

In order to use the theme folder just as a module folder, you need to register the folder in the list of modules being used by your application. Open up application/config/config.php and add the theme folder to your list of modules at the end. This lets Kohana make full use of the directory.

$config['modules'] = array
(
    DOCROOT.'themes/visual77',
);

Step 4 – Create a hook for adding theme content

The most important step is creating a hook to add your theme content around your template content. You want to let your template proceed as normal, and after completion, add your theme data.

To create hooks in Kohana, just create a file inside your hooks directory. All files in that directory will be loaded automatically. For instance, make a file called theme.php inside themes/<theme-name>/hooks.

In order to do the theming, the ideal hook to use is system.post_controller. The previous hook, system.post_controller_constructor, is before the controller has executed; the following hook, system.send_headers, is after system.execute, and therefore can’t manipulate the controller.

The goal is then to create a hook on system.post_controller and manipulate the controller to take the template data and move it within the overall theme. To access the controller, call Kohana::$instance and begin manipulating. My hook file looks like this:

<?php defined('SYSPATH') or die('No direct access allowed');

// set my hook up to execute at the appropriate time
event::add('system.post_controller', 'visual77_theme');

function visual77_theme() {
    // grab the controller
    $controller = Kohana::$instance;

    // pull the original template aside
    $temp = $controller->template;
    // replace the template with my theme template
    $controller->template = new View('visual77/index');
    // put the original template into the content section of my theme
    $controller->template->content = $temp;
    // free up some memory by unsetting the temp variable
    unset($temp);
}

Step 5 – Begin building the theme

Now that the hook is in place, the only thing left to do is build your theme. In my example, create an index.php file in themes/<theme-name>/views/<theme-name>. This index file will contain the wrapper HTML for your theme, leaving the original template to drop neatly inside the content section that you define. When you begin adding css and images, you can keep it inside the theme directory. The usual .htaccess restriction on modules only applies to the module directory, which is why I put the themes outside of the module folder.

While building, remember to keep all theme related content, such as views and controllers, inside the theme directory. This makes the theme ultra portable and easily removed. To change themes, just change the name of the theme from Step 3 to the new theme directory.

In a system like this, you can even cascade themes. One great example of cascading themes is including barebones files like CSS resets and jQuery files. On a current project, I have to build an internal client administration and an external company website. Both use certain shared libraries and both need a CSS reset and jQuery files. Using cascading themes and module sharing, I can blend these two sites very neatly. The file structure for this project looks like this:

/httpdocs
    /internal_application
    /external_application
    /modules
        /shared_libraries
    /system
    /themes
        /internal_theme
        /external_theme
        /default
    /index.php

Both internal and external applications include modules/shared_libraries and themes/default. However, internal_application also includes themes/internal_theme and external_application includes themes/external_theme. A switch statement in index.php dynamically switches the application based on the hostname. In the end, I  have two sites running smoothly in parallel on a single Kohana build.

Final Thoughts

Kohana is a fantastic system, but really needs better support for dynamic theming. In my build process for this theming pattern, I tried to emulate the wordpress theme convention, where all theme files are kept clustered and are easily swapped out for a new theme.

To see a full theme example, you can download my Sample Kohana Theme and then modify it to fit your needs. Just remember to enable hooks and include this theme as a module!

Array
    (
        to => Array
            (
                0 => stevep
                1 => bobw
            )
        bcc => Array
            (
                0 => paulj
            )
    )

Array
    (
        0 => stevep
        1 => bobw
        2 => paulj
    )

I looked around a bit for an existing PHP snippet to do just this, but they were all overly complex and used recursive callback functions. I had a feeling I could pull this off in a much more clean fashion. I toyed around a bit with the array functions and the ArrayObject library, and this is what I settled with:

$new_array = new ArrayObject();
array_walk_recursive($old_array, array($new_array, 'offsetSet'));
$flattened_array = array_keys($new_array->getArrayCopy());

The big drawback is the way ArrayObect::offsetSet() accepts its parameters, compared to how array_walk_recursive() sends the callback parameters; they are reversed. This causes the values to become keys, which has the effect of canceling out duplicate values. If your script needs duplicate values to remain intact, then this solution won’t work for you. Otherwise, it should work out just fine.

I’ll be writing an article on best practices for creating new classes in PHP and ideal naming conventions for functions and variables. In both situations, I have the bulk of the writing already completed and just need to polish it up and get it into a blog article.