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.

Status update and Doxygen rant

It has been two weeks snce my last update, so I wanted to let you guys know what I am currently at. The good news is that the new coordinate systems have been implemented and are ready to use. Of course there is still the obligatory last check to do, but i expect everything to be fine. All methods that got the axe are now gone as well and have been put into extension methods and ZIPped into archives; that way no one will accidently use the deprecated API. I also added a section called Legacy Support to the manual with instructions.

Now for the promised rant. I have transitioned all the documentation to Doxygen, both scripting reference and user manual. Now all that would be left would be to sprinkle some CSS fairy dust on top of it so it looks nice and I'm done. Except editing the CSS is an exercise in pure trial & error frustration, there is no documentation for it and the code is barely commented. The manual is a pain in the butt as well, it's like it was written for people who already know how to use Doxygen. It will go into detail about all the possible ways of formating my text, but it doesn't explain how to get the text into the manual in a specific order. Don't worry, I got it all covered now, but it was not a fun journey.

I wanted to slim down the default HTML design, because I think the large header buttons at the top are too large and vibrant, but I've had it with Doxygen. Don't get me wrong, it's a great system and I'm sure everything made perfect sense when wrting it, but it is obscure from the outside. Anyway, I'm going to stick with the default design for now, but at least I limited the size of images so they don't disrupt the flow of the text. There probably won't be any PDF documentation anymore though, the HTML is more flexible to read and navigate, plus the PDF generated by Doxygen looks rather... ugly.

Now that I've got everything out of the way it's time to wrap it up and hopefully get it released next week.

What's up next?

Hello everyone, I decided to do a status update so you know what's going on and coming next.

Two new examples

The first example is something I wanted to do for quite a while, it generates a terrain mesh like the terrain in games like SimCity from a plain text file. You provide the numbers for the height of vertices and the mesh gets created. On top of that you can click a vertex to raise it and right-click to lower. All the vertices will be placed along the vertices of the grid, so the level designer doesn't have to wory about the layout of the scene.

The other example is a rotary phone dial using polar grids, it's based on a suggestion by a customer (I always appreciate input, don't be shy ^^). You have a rotary dial, you click it and then it rotates like a real dial, depending on which number you clicked. It may no look very impressive on its own, but the template could be used for all kinds of cool UI displays and menus. It works by checking which sector of the grid was clicked and then multiplying that with the angle of the grid and then applying the rotation over time.

Both examples are already done and will definitely be part of the next update.

New hexagonal coordinate systems

This is the main feature of the upcoming update. Up until now the only coordinate system hex grids had was the herringbone pattern. It's easy to understand, but when writing for it you often have to differentiate between odd and even X-coordinate, which is... stupid. The new coordinate systems don't have that problem, but they are harder to understand, so pick your poison ;)

The first coordinate system is "rhombic", meaning the X-axis is rotated 30° upwards. This removes the need for the even/odd cases, but now moving south-west is actually moving west. The second coordinate system is "cubic", it uses three axes in two dimensions. To understand it remember the game Qbert, the game world is in 3D with cubes, but the actual graphics are in 2D and the cubes are actually hexagons. Finally, we have barycentric coordinates for the more mathematically inclined.

I really want this feature to be done before going after playmaker support. I know you guys want Playmaker and I keep telling you "later", but this is more urgent. The good news is that these coordiante systems turned out to be much less painful to implement than I originally expected. I still need to give everything the final polish and make sure the systems are not only mathematically correct, but also make sense to a human being, so I'm about 90% done.

New documentation with doxygen

Up until now I have been writing the documentation in Pages and exporting it as PDF. It was an OK workflow and the results looked reasonably well, but as Grid Framework's API grew it became more and more of a pain to write the actual documentation with all the cross-references and unified layout and styles. I have now reached the point where it would be just madness to continue, so I decided to switch to Doxygen. When you use Doxygen you comment your source code in a specific manner, then Doxygen parses it and uses your comments to document all the methods for a human to read.

The transition phase is ugly, I need to copy-paste or rewrite all my documentation, but once it's done any future updates will be much easier. This also means you will get documentation in both HTML and PDF format from now on.

Vertex matrix gets the axe

Finally, some not-so-good news. I have been thinking about this for a while, and the vertex matrix methods were never really good. The idea was to give you a quick and simple way to store some vertices of a grid in an array and be able to read them, but the way I did it is way too specific. It will only be useful in a handful of cases. This leaves me with two options: either expand on it, writing many variants of the method and on top of that doing the same thing for faces, boxes and edges, or just cut it out.

I decided to cut it out, because there is no point in dragging all that code along, when most people will never use it and some will only use a fraction of it. It would be much easier and better if the users themselves wrote their own methods, it's less than ten lines of code anyway and you get full control over what you want. You don't have to drag along an array that's four times larger than you need. When looking at the examples I wrote, not even I used the vertex matrix methods once, because it was easier and cleaner just to roll it from scratch.

Naturally this raises another concern, what about the people who were using this method? I can't just rip it out and tell them to write it themselves. This is where extension methods come into play: After I removed the methods I put them back into and extension method in a separate file, which I ZIPed. If you need the vertex matrix methods back just unzip it and you won't notice any difference. Of course if enough people actually want the vertex matrix to stay in place I'll put it back, but if no one objects this will be the way to go.

CheckComponent()

Here is a quick but handy tip. Recently I found myself needing to reference various components in my script without knowing if they exist. I have to get the component and then check if it exists, and if not add it to prevent null exceptions. Here is what you would write in such a case:

MeshCollider mc = GetComponent<MeshCollider>();
if (!mc)
 mc = gameObject.AddComponent<MeshCollider>();
}

First we get the component and store it in a variable, then if it is null we add the component to the object. Simple, right? True, but if you need to do this several times it can get messy. You can copy-paste it once with a different type, but it gets tedious.

Fortunately we can call generics to the rescue! Let's wrap it all up into one generic function that works on any component:

private T CheckComponent<T>() where T: Component {
 T component = GetComponent<T>();
 if (!component)
  component = gameObject.AddComponent<T>();
 return component;
}



MeshCollider mc = CheckComponent<MeshCollider>();

Note that it is important for the type T to inherit from Component or else the methods GetComponent and AddComponent don't make any sense and will throw errors. We can take this even one step further by making CheckCompnent an extension method:

using UnityEngine;
using System.Collections;

public static class ComponentExtensions {
 public static T CheckComponent<T>(this Component theComponent) where T: Component {
  T component = theComponent.GetComponent<T>();
  if (!component)
   component = theComponent.gameObject.AddComponent<T>();
  return component;
 }
}

Now you can call CheckComponent as if it were a part of Unity's standard API, just like GetComponent.

// use this in any of your scripts:
MeshCollider mc = CheckComponent<MeshCollider>();

Grid Framework version 1.3.0 released

Grid Framework version 1.3.0 has been approved by the Asset Store team. The biggest features of this release is the addition of polar grids. Check out the updated included examples to see them right in action. Notice how in the lights-out example the coordinates wrap around, maning that once you've exceeded the maximum angle it start from the beginning again without you having to worry about anything.

Even if you prefer the good old rectangular- and hex grids you'll want to take a look at the updated API: You can now get the direction vectors for up, forwarad and right or north, north-east, east, south-east and so on just by calling one command. This will make grid-based movement much easier, since you don't have to convert back and forth between grid- and world space anymore.

On top of that the lights-out and the runtime snapping example showcase how to dynamially generate meshes from grids. The tiles of the polar lights game are all individual meshes that fit exactly inside the idividual faces. When the game starts the attached script runs a loop that runs through the grid and creates the needed vertices and triangles and then assigns the proper materials.

Here is the full changelog:

• added up, right and forward members to rectangular grids
• added sides, width and height members to hex grids
• added the enum GFAngleMode {radians, degree} to specify an angle type; currently only used in methods of polar grids
• added the enum HexDirection for cardinal directions (north, north-east, east, ...) in hex grids
• added the GetDirection method to hex grids to convert a cardinal direction to a world space direction vector
• hex grids and polar grids now both inherit from GFLayeredGrid, which in return inherits from GFGrid
• the Lights Off example now features a polar grid as well
• procedural mesh generation for grid faces in the Lights Off example
• mouse handling in runtime snapping example changed because it was confusing a lot of users who just copy-pasted the code

Please note that this version officially requires Unity 4, since that is what I was building with, but there is no new API used and the scripts will run just fine in Unity 3.