New blog

As mentioned in the previous post, I have been working on getting a blog on the new website. It is now live and it is much better than this one.

http://hiphish.github.io/grid-framework/news/

This blog will stay up for a while, but it won't get updated anymore, this post will stay on top for the time being to redirect people. It has served me well over the years, and now it's time to move on to something better.

New website

Over the last few months I have been busy redesigning the website and we are finally live now. Check it out:

http://hiphish.github.io/grid-framework/

The new website has been rewritten from scratch, but all the old links are still valid. It is now a modern site that looks good on desktops, on tablets, on phones and even in text mode. All content is static and the site works fine with and without JavaScript enabled in your browser.

Showcase your work

Judging by the five-star reviews you all seem to like Grid Framework, but what are you using it for? I want to have a showcase page on the website where I can show off some of the games made using Grid Framework. If you want your game featured drop me a line, include a screenshot (or give me permission to pick one myself) and a few sentences about your game and what you used Grid Framework for. I'm looking forward to seeing all the cool uses you came up with.

About the new website

The original website was made from hand-written HTML and CSS. While I like the pure hands-on approach it became quickly apparent that that wouldn't cut it in the long run. Take for example the navigation bar: It has to appear on every page, it has to be the same everywhere and the currently active item has to be highlighted. HTML has no interactive elements and no way to include snippets. I could have used JavaScript, but then the site would break down it people don't have JavaScript enabled.

I was looking into different solutions and settled for Pelican. Pelican is a static site generator, meaning you write template HTML pages with placeholders and you write your content separately. Pelican then generates the finished website from your template, content and a number of settings. This has all the benefits of being static while being easy to maintain.

For the actual website I decided instead of reinventing the wheel I would just leverage the work of people who know more about web development than me. I use Bootstrap as my CSS framework and jQuery for light JavaScript decoration. I also now have a proper gallery using Pretty Photo library. You can find a list of all components on the about page.

One final note about JavaScript if you are concerned about proprietary code: all the foreign code is free software and the code I have written is free as well (MIT licensed), no need to worry.

What is still missing is the blog. Because I intend the Workshop to be home to all my projects it would be a bad idea to lump all news into the same blog. Pelican has no capability of producing multiple blogs, I will have to write a multiblog plugin instead. Until then this blog stays the news site.

Grid Framework version 1.8.0 released

Version 1.8.0 of Grid Framework has been approved by the Asset Store team. This release introduces a new rendering shape for hex grid: the circle. Of course, like with polar grids, just because it's called a circle that does not mean you are limited to just circles, you can decide on the start and end "angle" or have a hole in the centre to create a ring.

The shape can be drawn around any hex, not just the origin. Here is the full changelog:

Introducing a new rendering shape for hex grids.

• New: Hex grids can render in a circular shape.
• New: `renderAround` property on hex grids for the new shape.
• Fixed: Size and rendering range not showing up properly in the inspector.

Grid Framework version 1.7.4 released

Grid Framework version 1.7.4 has been approved by the Asset Store team. This release brings official support for Unity 5, so feel free to upgrade. Unity 4 is still supported, thanks to the changes to the Asset Store I can now upload separate packages for different versions of Unity.

There are no API changes, so it doesn't matter whether you want to use Unity 4 or 5. The only real difference between packages are the example scenes. The formats Unity 5 uses are different from 4, so a package created in Unity 5 would appear broken in 4.

Playable examples

I have added playable builds of the examples to the website, now you can click the title of an example and try the result out in the Web Player. To get back click on the Grid Framework examples label above the player. Just remember that you have to click into the player to get it to accept input.

Check out the web pages:

http://hiphish.github.io/grid-framework/examples/

Grid Framework version 1.7.2 released

Version 1.7.2 of Grid Framework has been approved by the Asset Store team. This release and the previous one provide bugfixes:

• Fixed: Null exception on polar grids when getting Vectrosity points if the grid is not being rendered.

For version 1.7.1:

• Fixed: The grid align panel now correctly respect or ignores rotation when auto-snapping.

A homepage for Grid Framework

Grid Framework now has its own homepage:

http://hiphish.github.io/grid-framework/

I have been running this blog now for almost three years, which is way too long to go without a proper website. Back when I had just started out I didn't know if Grid Framework would ever take off, so I organised everything in a quick&simple manner, but I think it's finally time to step up my presentation.

The site is hosted on GitHub, so you can browse the source code if you wish, it's all handwritten in HTML and CSS, nothing fancy. There are still a few things I would like to overhaul, like a proper screenshot gallery, playable examples and redo the videos. But for now the site is at least presentable.

If you have any suggestions or find display errors on some devices please let me know.

Goodbye MonoDevelop, hello Vim

One thing that has been getting on my nerves ever since I started working with Unity has been MonoDevelop. While it is a good IDE for the most part it suffered from a number of annoying issues, such as folds randomly opening, poor performance, and auto completion randomly not working. Your mileage may vary, and for the most parts it was doing its job, but the annoying hiccups kept happening all the time.

I tried out the official Xamarin Studio, but that one didn't fare better and on top of that always threw up error messages when opening a file. I was looking into alternate editors, but they didn't offer the rich C#-focused feature set of MonoDevelop, so I was stuck with it.

Eventually I was so fed up, I decided to go all the way back: no fancy IDEs, no GUIs, back to to bare basics: Vim. The cool thing about Vim is that's it's a very simple barebones editor that can be extended and customised to your liking. Vanilla Vim is nice, but you have not really used Vim until you have tailored every aspect to your personal liking. That's a gradual process that will take years of experience, but I do already feel very comfortable outside of the hand-holding restrictions of the IDE.

For an ideal Unity setup you will want a GUI client of Vim, such as MacVim. That doesn't mean that Vim will get all those fancy buttons and menus, although you can enable those if you want to, but the main advantage is that it can be launched like any other application instead of through the terminal. MacVim has also better mouse support (it's faster to resize windows with the mouse) and the character cursor looks different in insert mode.

The next thing you want is support for .Net and C# features. The plugin for that is Omnisharp:

https://github.com/OmniSharp/omnisharp-vim

Omnisharp will add pretty much all features that you have come to love from MonoDevelop, without the headache. Omnisharp also provides an interface for other plugins, for example you can use it with YouCompleteMe to get automatic code-completion:

https://github.com/Valloric/YouCompleteMe

There is a ton of other useful plugins out there as well and some are listed on Omnisharp's page. Another advantage of Vim is that it's not restricted to one particular language or framework. You can easily write your essay or design your HTML web page in it. Customisations can be set for each file type differently or you can use them over multiple types. Since it's all one editor you don't have to learn a new IDE for every project.

In fact, I have been designing my new upcoming website in Vim as well, the same editor I use for writing Grid Framework. How cool is that? Here is a video I found on YouTube of someone using Vim to edit text with the speed of though:

Grid Framework version 1.7.0 released

Version 1.7.0 of Grid Framework has just been approved by the Asset Store team. This release brings some more love for hexagonal grids in the form of two new coordinate systems and four new rendering shapes.

The new coordinate systems are the downwards herringbone coordinate system where every second column is shifted down- instead of upwards and the downwards rhombic coordinate system where each successive column is shifted one hex down- instead of upwards.

Two of the new rendering shapes are downwards rectangle and downwards rhombus to go with the new coordinate systems. The two completely new rendering shapes are the up- and downwards herringbone grids. Unlike the other shapes these ones are continuous and expand smoothly.

Notice how the grid on the left-had side shifts ever odd column upwards and the grid on the right-had side shifts ever odd column downwards.

Here is the full change log:

• New: Downwards herringbone coordinate system for hex grids
• New: Downwards rectangle rendering shape to accompany the new coordinate system.
• New: Downwards rhombic coordinate system.
• New: Downwards rhombic rendering shape to accompany the new coordinate system.
• New: Up- and downwards herringbone rendering shape.
• Fixed: The grid align panel now correctly respect or ignores rotation when aligning.

Grid Framework version 1.5.3 released

Grid Framework version 1.5.3 has been approved by the Asset Store team. This release brings compatibility with the upcoming Unity 5.

Grid Framework itself was compatible, but a number of examples used properties that have been removed in Unity 5. Those are properties that secretly called GetComponent, but looked like regular variables.

And while I'm at it, here is a little teaser for the next feature update: rhombic hex grid rendering

Grid Framework version 1.5.2 released

Grid Framework version 1.5.2 has just been approved of by the Asset Store team. This release is a bugfix for polar grids where the cylindric lines have not been calculated properly if the depth of the grid was not 1.

Another thing you might notice is that the engine requirements have been knocked down to Unity version 3.5.7, the latest release of Unity 3. While Grid Framework has always been compatible with Unity 3, I have been using Unity 4 for deployment so far. Now the compatibility with Unity 3 is official.

Compatibility with Unity 5 is coming with the next update; it's nothing major, but some of the examples did not compile due to deprecated properties.

Grid Framework version 1.5.1 released

This release is a hotfix for everyone who was using Playmaker

• Fixed: Compilation errors when toggling on Playmaker actions.

Playmaker actions wil compile correctly now, anyone else was unaffected. So what happened? One of the problems when developing an extension that relies on another extension is that it will not compile if the dependency is not present. For Vectrosity is was easy, I just needed to assemble and array and the user would then send it over to Vectrosity. Or not, you could do something entirely different with it as well if you wanted, it's just an array of Vector3.

Playmaker is different though, the actions are classes derived from Playmaker classes, so if you don't own Playmaker the code will not compile. My solution was to do the following:

//#define PLAYMAKER_PRESENT
#ifdef PLAYMAKER_PRESENT
// code goes here
#endif //PLAYMAKER_PRESENT

This means the code will only compile if the keyword PLAYMAKER_PRESENT is defined, which it isn't since the first line is commented. To make the scripts compile you have to toggle them on through a menu item which then edits the scripts to un-comment or comment that line. Before I submit a new release I have to toggle the actions off and so I missed the compilation errors.

It's still a bad oversight on my side and I'm not trying to excuse my failure, but I wanted to share how this can happen. A better solution would be if plugins could define keywords globally, then Playmaker could announce its existence on its own instead of having to toggle things manually.

Grid Framework version 1.5.0 released

Grid Framework version 1.5.0 has been approved by the Asset Store team. This version brings a great new feature for anyone interested in making isometric 2D games: shearing. Shearing allows you to slant a rectangular grid's axes without having to rotate the grid. Up until now the only way to achieve the isometric look was to rotate the grid or the camera in 3D space, but in 2D games the camera has to be perpendicular to the image plane and thus the grid as well. Now all you need to do is just set the shearing of the axes and you're good to go, everything else stays the way it was.

The shearing is stored in a new type called Vector6 that works very much like Unity's own Vector3. The Vector6 class resides in the new GridFramework.Vectors name space to prevent name collision with other custom types or a possible future official Vector6 type from Unity.

the GFBoolVector3 and GFColorVector3 classes have also been moved to that namespace and had their "GF" prefix stripped away. If you used them in your own scripts strip away the prefix and place a using directive at the start of your script, otherwise you have to do nothing.

Here is the full change log:

Introducing shearing for rectangular grids.

• New: Rectangular grids can now store a `shearing` field to distort them.
• New: Custom `Vector6` class for storing the shearing.
• API change: The odd herringbone coordinate system has been renamed to upwards herringbone. The corresponding methods use the `HerringU` pre- or suffix instead of `HerringOdd`; the old methods still work but are marked as depracated.
• API change: The enumeration `GFAngleMode` has been renamed `AngleMode` and moved into the `GridFramework` namespace.
• API change: The enumeration `GridPlane` has been moved into the `GridFramework` namespace. It is no longer part of the `GFGrid` class.
• API change: The class `GFColorVector3` has been renamed `ColorVector3` and moved into the `GridFramework.Vectors` namespace.
• API change: The class `GFBoolVector3` has been renamed `BoolVector3` and moved into the `GridFramework.Vectors` namespace.
• Enhanced: Vectrosity methods without parameters can now pick betweem size and custom range automatically.
• Fixed: Vectrosity methods were broken in previous version.
• Updated the documentation.

Whitelisting subdirectories in Git

After having migrated the development of Grid Framework to Git I wanted to set it up to track only certain sub-directories. I turned out that whitelisting is quite tricky, so here is how I did it for people who might run into the same problem.

We'll use only one .gitignore file and it will be placed in the root of our repository, which is also the root of our project. We can do the usual blacklisting stuff like blacklisting ceretain file types and directories, but the Assets directory is where it gets tricky. Since the directory contains all sorts of other plugins used during development but not worth tracking, we can neither black- nor whitelist the entire directory.

First we'll blacklist all the contents of the Assets directory. Note that this does not blacklist the directory itself, just its contents, but since Git operates on files the effect is the same. The difference is that blacklisting an entire directory prevents us from ever whitelisting any of its contents.

Assets/*

Now we can whitelist a subdirectory and its meta file:

!Assets/Grid\ Framework/
!Assets/Grid\ Framework.meta

Simple enough, but what if we want to whitelist only a specific subdirectory of a subdirectory? The Editor directory contains code from other plugins as well, so we don't want to track the entire thing. In this case we need to repeat the same process as above but one level deeper.

!Assets/Editor/
!Assets/Editor.meta

Assets/Editor/*

!Assets/Editor/Grid\ Framework/
!Assets/Editor/Grid\ Framework.meta

First we whitelist the Editor directory, then we immediately blacklist its contents and whitelist a specific subdirectory. This way none of the other editor extensions will be tracked. We can repeat the same process for the Plugins directory.

!Assets/Plugins/
!Assets/Plugins.meta

Assets/Plugins/*

!Assets/Plugins/Grid\ Framework/
!Assets/Plugins/Grid\ Framework.meta

And yes, you do have to repeat all these steps for every level of subdirectories. You don't have to whitelist subdirectories of already whitelisted directories, so any subdirectory in "Assets/Editor/Grid\ Framework/" is already tracked. Also note the backslash in the path, it is necessay to escape the space character.

UPDATE: Whitelisted the Unity meta files of whitelisted folders as well, just in case. Of course if you are not using Unity you need to figure out if and what meta files you have instead and if they need to be tracked as well.

Shearing

As I mentioned last time the upcoming release will be a maintenance release with some much-needed cleanup. While I'm still waiting for approval I have been working on a new feature for rectangular grids that I had wanted to do for quite a while now, but couldn't until the cleanup: I'm talking about shearing.

This is an un-rotated rectangular grid with skewed axes to create the popular 2:1 isometric look. This is quite powerful, because it allows for isometric 2D graphics to be used with Grid Framework. Getting an isometric look in a 3D game is very simple, you just rotate the camera until it looks right. However, in a 2D game the camera has to be perpendicular to the image plane and objects are just drawn as if they were at an angle, so rotation is out of question.

Shearing is fully implemented, I just need to write the documentation for it. It works with arbitrary numbers and for all axes along any other axis, so you can shear your grids any way you want. It will be a feature for the 1.5 update once the upcoming 1.4.2 release gets approved.

Grid Framework version 1.4.1 released

Actually it has been up for almost a month already, but I have been busy. Anyway, this is the long-awaited release that brings PlayMaker support to Grid Framework, so here is the change log:

• Introducing Playmaker support: Almost the entire Grid Framework API can no be used as Playmaker actions (some parts of the API are ouside the capabilies of Playmaker for now)
• Updated the documentation to include a chapter about Playmaker and how to write your own Grid Framework actions.
• Fixed: the origin offset resetting every time after exiting play mode.
• Fixed compilation error in one of the Playmaker actions (setter and getter for depth of layered grids) 

If you're wondering why I skipped 1.4.0, it's because I discovered a bug right after submission, so I submitted 1.4.1 right afterwards, thus skipping over the release of 1.4.0. As always you can read about how to use the new PlayMaker actions or write your own ones  in the documentation.

As for future plans for Grid Framework, I still have a place that I want to optimise before considering new features, and it will require a good amount of digging, but the result will be cleaner and easier to maintain code.

Grid Framework version 1.3.5 released

Grid Framework version 1.3.5 has been approved last week, here is the changelog:

• Added a new event for when the grid changes in such a way that if would need to be redrawn.
• Some of the exmples were broken when Unity updated to version 4.3, now they should be working again.
• Overhauled the undo system for the grid align panel to remove the now obsolete Unity undo methods.

I promised I would be working on Playmaker support, so what's going on here? I have been bogged down a lot with studies and real life stuff oder the last months (nothing bad though, don't worry), so things were going slowly, but they were moving. The current problem is Playmaker itself; from what I have used it is a fantastic system to crate game logic and totally worth it, however, when it comes to extending it things aren't that nice anymore.

I am in contact with a staff member who is helping me out, so I'm not entirely reliant on the lackluster documentation, but there is a lot of ugly code redundancy that cannot be avoided. I'm still working on it and it will come out eventually, but it will take more time. How much? I don't really know, it depends on how rigid or flexible Playmaker turns out to be.

Grid Framework version 1.3.4 released

This is a small update, it adds the ability to offset the origin of the grid. It also adds a chapter to the manual about extending Grid Framework with your own code. There is nothing in there experienced .NET user wouldn't know, but I figure some user might not know about extension methods and might do things in a hacky way, so I added the chapter to it, along with example code.

Grid Framework version 1.3.3 released

Grid Framework version 1.3.3 has been approved by the Asset Store team. This update adresses a bug introduced in version 1.3.2 where values of colour vectors (such as axisColor) and bool vectors were not persistent. Now they will stick again. I also broke the examples for the sliding puzzle and movement with obstacles, which are now fixed. Based upon a customer's question I also built a snake game example; it's mostly an extension of the grid-based movement but with several snake segments following each other.

And last, but for some people certainly not least, if you delete the local documentation (found in the WebPlayerTemplates folder) the help menu entry will forward you to an online documentation instead. Some customers complained about me cluttering their project with that folders, and they are right, but unfortunately that's the only place where I can place the files, or else Unity will try to compile the JavaScript files and throw a ton of errors.

The documentation files are all contained in that one folder, so you can either uncheck it when importing, delete the folder after import or move it somewhere else. I know this is inconvenient, but unless Unity provides me with a proper way to bundle offline documentation this is the best I can do.

Grid Framework version 1.3.2 released

Version 1.3.2 of Grid Framework has been approved by the Asset Store Team. The biggest news is the  addition of new coordinate systems for hexagonal grids. You have cubic coordinates, rhombic coordinates and the old odd herringbone coordinates now. Even herringbone and barycentric coordinates will be added at some point in the future for the sake of completion, but they are no priority.

The documentation received a complete overhaul. Rather than two manually typed PDFs you now have one automatically generated Doxygen documentation in HTML format. Previously you accessed it by double-clicking the PDF in your project view, not you can just go to Unity's help menu and the documentation will open up in your browser.

The user manual and scripting API are now together again. The top- and sidebar of the HTML can be used to quickly find what you want. There is also a new section called Legacy Support that contains information on changed or dropped features and how to restore them or upgrade your code. The changelog has also been added to the manual, thanks to Markdown you now have both a nicely formatted HTMl and a well readable plain text file.

There are also two new examles. The first example constructs a SimCity-like terrain mesh from a plain text file containing the heights as integers and allows you raise and lower vertices by clicking them. Just set up your grid, insert your height file and click play.

The other example uses polar grids to simulate a rotary dial, as found on old telephones. Click a number and the dial will rotate that much, print a message and then rotate back. This example can be used for circular GUIs, menus, clocks or anything else that needs to rotate around angles.

There is also the usual bug-fixing, vertex matrix methods got cut and the NearestFace/BoxG methods of rectangular grids have changed somewhat. You can find the exact details in the Legacy Support section of the documentation. Here is the full changelog:

- Hex Grids: new coordinate systems, see the manual page about @ref hex_grid for more information.
- New HTML documentation generated with Doxygen replaces the old one.
- Fixed a bug in `Angle2Rotation` when the grid's rotation was not a multiple of 90°.
- _New example:_ generate a terrain mesh similar to old games like SimCity from a plain text file and have it align to a grid.
- _New example:_ a rotary phone dial that rotates depending on which number was clicked and reports that number back. A great template for disc-shaped GUIs.
Some existing methods have changed in this release, please consult the @ref legacy_support page of the user manual.
- Rect Grids: changed the way `NearestBoxG` works, now there is no offset anymore, it returns the actual grid coordinates of the box. Just add `0.5 * Vector.one` to the result in your old methods.
- Rect Grids: changed the way `NearestFaceG` works, just like above. Add `0.5 * Vector3.one - 0.5 * i` to the result in your old methods (where `i` is the index of the plane you used).
- Hex grids: Just like above, nearest vertices of hex grids return their true coordinates for whatever coordinate system you choose.
I am sorry for these changes so late , but I realize this differentiation made things more complicated in the end than they should have been. It's better to have one unified coordinate system instead. Read the @ref legacy_support to learn how to get the old behaviour back.