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.

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.