Category: Development

Posted on by — Leave a comment

A diary on working with third party code

There comes a time for every developer when they must work with code written by somebody else. Some times it’s voluntary. Say for instance there is a useful library the developer wants to use instead of writing all the code themselves. Other times, it’s not. Like when a new developer joins a project already in progress. The example in this post is of the former.

I was recently working with a Unity plugin which enables easy development of 2D environments. Given that Unity is a 3D engine having a framework for 2D scenes is useful and speeds development. The team unanimously decided to use an existing plugin instead of building one in-house. We immediately started building the game around this framework. However we did have to pay a small fee.

A couple of days later came a surprise. The developer of the library released a major update. Version 2.0! Given that we had purchased the library less than a week before, we tried contacting the developer to find out if we could get the upgrade for free. We were a little concerned with the response, or lack thereof. We didn’t receive any response at all. Not a yes, not a no, nothing. Not a big deal, we still had version one to use.

Fast forward a few weeks, and then comes an issue. It turns out there was a bug in the library affecting sprites inside a scaled parent. I was able to fix the bug, but only by introducing another issue. Any sprite not in another object moved. I then found out the new version of the plugin fixes the bug among other new features. However, since we had not heard back from the developers it would be a paid upgrade for us.

In the end we bought version 2 of the library only to find out it introduced the same issue my fix did.

Anyway, there is no real lesson to learn from all this. It’s just one of the many issues we dealt with during development.

Posted on by — Leave a comment

Switching Engines

When I started work on Crowman & Wolfboy there had already been some development complete on the game. A few levels were already built and saving and loading were being coded. However we soon ran into several problems with development.

Documentation seemed really out-of-date with the original engine. Code wasn’t working as the documentation specified it should. Even the examples given didn’t work. It was a serious problem which made progress slow.

Not long after joining we started looking into alternatives. First, we came up with a list of requirements which an alternate need to meet to even be considered. With nearly all the art complete, the new engine needed to support 2D art assets. Nearly all engines are capable of this. A strictly 2D engine is the obvious answer, but 3D engines can be clamped into 2D so we didn’t want to rule them out. We wanted to target both iPhone and Android mobile platforms so solutions specific to one platform were quickly excluded. For example, when we were doing this Cocos2D only supported iOS and would require another separate engine for development on Android. Next, documentation needed to be current. This was the original problem we were trying to get away from.

From this list of requirements we narrowed the possibilities and eventually chose Unity. It is a 3D engine but has several frameworks for building 2D games. It supports exporting to both iOS and Android platforms. And lastly, documentation is excellent. As an added bonus, there is an active community using Unity.

Since switching we haven’t looked back.

Posted on by — Leave a comment

The Importance of Documentation

In the previous post I describe several forms of documentation and their uses. Hopefully it’s clear that each form is important and serves a distinct purpose. In a typical day, I find myself referencing at least two of these forms. some days I don’t reference any documentation. On days I do, it is most often a function list and forum.

For example, I might start off the day needing to do some complex operation with an object’s rotation in Unity. You can see Unity’s class list with the rest of their scripting documentation. I know an object’s rotation is represented by a quaternion so let’s start there. Now I see that the operation is already implemented as part of the class requiring only one line o code on my part. Later on, when it’s not working the way I expect, I can heard either their forum or Q/A site. Now I can search for other people with the same problem or ask a new question myself. An answer will probably send me back to the class list as a reference.

These are the kinds of connections present between all the forms of documentation. Each one serves a specific purpose and knowing that purpose will help you find information faster.

Posted on by — Leave a comment

The Many Forms of Documentation

When I tell non-progammers I’m a software engineer most of them ask about coding languages or mention something about HTML. They have this idea that programming is all code all the time. A lot more goes into programming than just code. Before writing any code an engineer needs to know what capabilities are already provided to him/her. This is known as documentation.

Documentation comes in many forms. You probably already know one. Dictionaries are the most basic forms of documentation. They exist for spoken languages as well as computer languages. They contain words and their definitions. Some even contain grammar information. The dictionaries for computer languages are often called specifications. They contain the reserved words and grammar definition of a language.

Every computer language has a specification. The Java specification is on Oracle’s website. The specification is the most important form of documentation for a language. It defines what can and cannot be written in the language. The specification also defines the syntax of the language. However, as important as a specification is, they are rarely referenced. Most are difficult to read and contain more information than the common programmer is looking for.

The most common form of documentation is a class or function list. This kind of documentation varies from language to language but all have the same basic information. They contain predefined classes, methods, and functions for use in code. PHP has an excellent function list with the ability for people to leave comments. Another excellent example is the Mozilla developer network. These types of documentation are useful because a programmer can use functionality which is already built and tested instead of having to build their own. Most of my bookmarks are to a class list for something. The Unity game engine actually includes a class list as part of its installation making it easier to find documentation while offline.

A third form of documentation is what I call tutorials. They go by many names, tutorial, how to, cookbook, et. al. They contain examples of how to do basic or complex tasks. These are useful when there isn’t a single function to accomplish a task, but you know it is commonly performed. Looking up a task in a tutorial often yields a simple example and information for more complex situations.

The last form of documentation I will cover is the forum. This kind of documentation is a little different from the others. People ask questions and others answer. It requires a community of people capable of answering questions. There are many forums about programming. The most popular now is stack overflow. What makes these work is the community. With so many people willing to answer questions it is likely there is somebody capable of answering one you might have. Over time the forum becomes a reference as more questions receive answers.

There are other forms of documentation like BNF and class diagrams which I may cover later. Until then, know the differences and purposes of each kind of documentation.

Posted on by — Leave a comment

Why Math?

When I was in high school I took a class most students take. It was a trigonometry class. Most of my classmates had a frequent recurring question, “Why do we need to know this?” The teacher wasn’t very helpful with giving an answer. So I took it upon myself to come up with one. Being a youth myself it proved a difficult task. What I came up with were two rather unsatisfying answers. The first answer was simply, “for the test.” My other answer looked a little further into the future and was, “for next year’s class.” Little did I know that I would continue using it for years to come.

Most recently I used trig in programming the camera movement for Windom. There were two rules for it’s motion. One, the camera should move in a parabolic shape vertically, close to the character when low and high and far from the character when in the middle heights. And two, it should move in a circle horizontally around the character. Those of you who know your trig should already see how it will come into play.

I was working from a drawing of what the motion should be. But what I needed was a function which defines the distance from the character. So as a starting point, I decided to find the function which defines the drawing. Here’s a visual.

Stick figure with parabolic camera motion

Here’s what I knew. The line of symmetry goes through the top of the character, there is a point on the parabola at the character’s feet and one above the character. The function which defines this is h(sqrt(-x/m)+1) where h is the height of the character and m is the furthest distance modifier. It turns out this function isn’t very useful. It gives a height when provided with the distance from the character. I wanted a distance from the character provided with the height. Easy, just take the inverse. The result with some simplification is hm(1-x^2). That is what defines the distance which the camera should be from the character given the height of the camera.

The rest is comparatively easy. I know the rotational point where the camera should be in radians. It is just a matter of using trig to convert to x and z coordinates. I went with x=d*sin(r) and z=d*cos(r) where d is the distance provided by the the function in the previous paragraph and r is the rotational position in radians.

If I didn’t know trig the circular motion part would have been immensely more difficult. When I was in high school I never expected to need trig for very much but now I have more appreciation for it.

Posted on by — Leave a comment

Javascript Controlled SVG Part 2

I have already covered utility functions and GUI code, but most of the code is for calculations of color data. This post will explain how all of the code ties together.

When the user first loads the color picker the default state is loaded. All values are zero and correspondingly the color is black. RGB (0,0,0) is black and HSV (0°,0,0) is black.

All event handlers do basically the same thing. First the master color color data  is updated to reflect the changes made by the user. Next the RGB, HSV, and hex code are updated to reflect the color data. If the user is changing RGB values, those copied to the color date and used to calculate HSV and hex code. If the user is changing HSV values, those copied to the color date and used to calculate RGB and hex code.

All event handlers ultimately call the update function. This in-turn updates the handle locations, background gradients, and preview area. each is separated into its own function.

The updateHandles function uses the color data to update the locations of the sliders. Let’s go over one group in the function.

var redHandle = max - colorData.red / 255 * 199;
document.getElementById("redHandle").setAttribute("y",redHandle);
document.getElementById("redLabel").firstChild.nodeValue = Math.round(colorData.red);

The first line is responsible for calculating the top side of the red value slider handle. Yes, I know it has magic numbers. if you read my earlier posts you would know this is more like a proof of concept than a finished product. magic numbers never make it into my finished works. 255 is the maximum value for red, 199 is for the size of the slider. Looking at it now, 199 could be replaced with (max - min). The second line moves the handle to the new position. The third updates the value displayed below the slider. These three lines are repeated for every slider with different constants.

The background of each slider shows the resulting color of moving that particular slider. These gradients need updated every time the color data changes. doing so is as easy as calculating color data as if the slider is set to each end. The hue background is slightly different. It has one gradient with all the hues represented and two overlays. one overlay is completely white representing the saturation. the other is black representing the value. The opacity of each overlay is adjusted according to the current location of the corresponding slider.

The preview is easier to compute than any topic discussed so far. Using the RGB color data, the hex code is calculated. Each color is converted using the deciToHexDigits function to ensure placement of zeros. The resulting string is then shown to the user and applied as the fill of the preview area.

Posted on by — Leave a comment

Javascript Controlled SVG Part 1

In my last post I described the experience and development of my first true attempt at SVG. This post will describe the javascript code which implements the behavior of that color picker. This is meant to describe the code to somebody who understands basic programming but not necessarily javascript or working with graphics. If you have a solid grasp on javascript and programming GUIs you can skip this post.

All code is viewable in the source of the page.

First let’s cover the “global” variables. The first, HEX, is used as a constant in the conversion from decimal to hexadecimal (more on that soon). The colorData variable is used to store the state of the color data and is directly modified and displayed by the sliders. The min and max variables are treated more like constants as they represent the minimum and maximum pixel locations of the sliders. The selected variable points to the currently selected slider, or null if none are selected. To be selected means the user is currently modifying that slider. Finally, button points to the button currently in use by the user, or null if none are in use.

Now for the functions. The code covered in this post does not include application logic. These functions facilitate communication between the graphical state and the data and most are event handlers. Most of them are fairly straightforward.

The first function is mouseCoords. This function is pretty straightforward. It takes any mouse event fired by the browser, extracts the coordinates of the event, and returns a single object containing the x and y coordinates.

deciToHex takes an integer and returns a string of the hexadecimal representation. The deciToHexDigits function converts an integer to a zero padded hex string which has a minimum number of digits. It takes two parameters, the integer to convert and the number of digits.

The update function updates the graphical state to reflect any changes to the data. It should be called anytime the state changes.

The drag function is deprecated and no longer works. However, you will notice it is still being called by some SVG elements. This was used early in development but never removed when replacements were developed. In a non-educational, shipping product any code referring to it should be removed. The reason it is still in the source is because it was handed in that way and this is meant to be an archive of what was graded.

The selectHandle function is the event handler for when a user clicks in one of the handles of a slider. It sets the global for the currently selected handle. The unselect function sets the state of all objects to not selected. It is similar to a “select none” action in most applications. It affects all sliders and buttons.

The buttonOver, buttonDown, buttonOut, and buttonUp functions are all event handlers working in conjunction with makeButtonDown and makeButtonUp to control the graphical state of the buttons. When the user mouse-downs on a button the global button is set to point to that button and the grical state of it changes. The user can then mouse-out and mouse-over the button with only the state of that button changing. If the user then mouse-ups anywhere outside of the button no action is performed and the global is set to null. This functionality is similar to native buttons on most platforms. If the user mouse-downs on a button and proceeds to mouse-up over the same button, it is considered a click. the click is reflected by changing the color data withing the boundaries of each attribute followed by the graphical update.

Color Picker

The next post (Part 2) will cover the application logic and associated code.

Posted on by — Leave a comment

SVG Attempt

Let’s start with a topic that has seen vast improvement in browsers lately.

SVG is relatively new compared to other web technologies. The first release of the language specification occurred in 2001. I was just starting high school. Less than ten years since then, support for the language is extensive, reaching even mobile devices.

My earliest attempts at SVG were reproducing GUI elements. They can be viewed by visiting my Interface Design course page. From there you can also view my homework assignments if you so desire. My final project is the topic of this post.

My partner (Adam) and I chose to make a color picker for our final project. The goal was to make a color picker which can be built into a larger application. That was the only requirement. Our first task was to research current solutions.

We looked at several color pickers in popular programs. Our color picker needed to fit in a small space and provide a wide range of colors. While swatches have a small footprint and are easy to use, they don’t provide enough choice to the user. But pickers which use a large area, like the default in Photoshop, are too large. This led us to sliders as the primary mechanism to adjust the color.

The next decision to be be made was which color model to show. We wanted one easy to understand and easy to use. RGB is the easiest to use with three variables each with 256 possible values making it our first choice. HSL and HSV are more accessible given that each presents the user with the hue which is how most people think of color. CMYK was ruled out because the color picker is intended for web use only. For the same reason, we included the hexadecimal value. In the end we included RGB and HSV sliders to gain the advantages of both.

This is when we ran into a problem. First RGB and HSV variables all have different domains. Second, the maximum value (360 hue) is greater than the amount of pixels available for the sliders. Good design dictates that sliders can reach all possible values in their domain. By shortening a slider some possible values are excluded either beyond the end or between pixels. We chose to make all sliders 200 pixels long but provide buttons to adjust the sliders in sub-pixels. This has the unfortunate side effect of destroying scale. One slider (hue) has the domain 0-359, and two (saturation and value) are 0-100, and three sliders (RGB) are 0-255; but every slider is 200 pixels long. We also added variable gradients to show how moving a particular slider will affect the color.

The end result can be thought of more like a prototype than a finished product. A major oversight was labels. The sliders from left to right are as follows: Red, Green, Blue, Hue, Saturation, and Value.

Color Picker

Be on the lookout for a post about the code.