Popisfizzy's site

The Art of Code: Namespaces and Inheritance

Fri, 10 Feb 2012 23:16:42 +0000

I'm a programmer. As such, I'm impatient.

Many people don't understand the true complexities of programming. There is more to code than just writing code. Programming is a unique field, a crossroads that few other fields dare to travel: It's where mathematics meets engineering meets art. A good programmer must know the mathematics of what they're doing, of how to analyze algorithms to understand what works best for them. A good programmer must be a knowledgeable engineer, able to write robust, reliable, efficient code in a way, and documented in a way, that is precise, concise, and clear. A good programmer must be an artist, able to write code that is elegant, extensible, maintainable, and usable. The first and second are clear to many users. But what about the art of programming?

I am impatient. People who do not understand good design principles, people who can not write elegant code, extensible code, maintainable code, useable code. They annoy me. People who can not design good code. And, thus, I grow weary of helping them, sometimes going so far as to just outright stop. But this shouldn't be so. There should be no reasons why the average user of BYOND, the average DM programmer, can not write code that implements good design principles. The Art of Code is my attempt to help users with this, to understand the art of programming, and the beauty of code. These tutorials will be aimed at a slightly more-advanced audience than my So You Want To Program tutorials, but will be written as clear as possible nonetheless. So, let's begin, shall we?

My first tutorial on this series is going to focus on namespaces and inheritance as applied to DM. These two language features are dinstinct in most object-oriented programming language, but this isn't so in DM. In fact, the language muddles the two so much that few people recognize the difference that exists. Nonetheless, the distinction is still present, and not even that far from the surface.

Inheritance

First off, let's discuss inheritance. To most DM programmers, this should be a topic you are already familiar with. Inheritance is one of the main features of object-oriented programming languages. Certain types of programming constructs, called classes, can inherit their features from other classes. The inheriting classes are called subclasses, and the inherited class is called a superclass. For example, below is a typical example of classes and inheritance.

animal
    /*
     * This defines the animal superclass. We define a few variables and procs for the
     * subclasses to use.
     */

    var
        hunger
        thirst

        bathroom

    proc
        Speak()
            // How the animal 'speaks', or vocalizes. Some animals just don't.

        Eat()
            // Some animals eat meat, others eat plants. Others do both.
            hunger ++

        Drink()
            // How the animal drinks. Some sea animals basically do it when they eat.
            thirst ++

        Bathroom()
            // How the animals uses the bathroom.
            bathroom --

        Move()
            // How the animal moves.

        Die()
            // Called when the animal dies.
            del src

animal/dog
    /*
     * A dog is a type of animal, so we'll use it.
     */

   Speak()
       world << "[src] barks!"

   Eat(animal/a)
       world << "[src] eats [a]."
       a.Die()

       ..()

  Move()
      world << "[src] walks."

animal/fish
    /*
     * A fish is a type of animal, but one quite different from a dog.
     */

    Speak()
        // Fish don't really have a vocalization, so nothing happens.
        return null

    Eat(animal/a)
        // We have a carniverous fish here.
        world << "[src] eats [a]."
        a.Die()

        Drink() // It drinks when it eats.
        ..()

    Move()
        world << "[src] swims."

animal/bird
    /*
     * Another type of animal, different from a fish and a dog.
     */

    Speak()
        world << "[src] chirps."

    Eat(plant/berry)
        // This is a berry-eating bird.
        world << "[src] eats [berry]"
        berry.Eaten()

        ..()

    Bathroom()
        world << "[src] goes to the bathroom on a nice, clean car."
        ..()

And there we have a small example of how inheritance can work in DM. This is the way most people work with, but as we'll see later, this isn't the only option available to DM programmers. It's still simple, and intuitive, but not always the kind of thing we want.

Namespaces

At first glance, namespaces are a feature that does not appear to be present in DM. Before I go any further, let me explain what a namespace is. Think of a namespace as an abstract kind of 'container' that holds a lot of similar things together. For example, if you have a Gun, maybe you'll have a few different things associated with it. There might be the Gun itself, ammunition, and maybe Magazines or Clips. You could hold all of this together in a Weapons or Guns namespace. Why is this useful? Maybe there is ambiguity in your code. Maybe your code also has other types of magazines, like the kind that you can read, or other kinds of clips, the kind that you can use to hold two things together.

Without a namespace, this becomes ambiguous. Obviously the Magazine or Clip can't inherit from a Gun. That makes no sense, as they don't share any features with a gun. Thus, what are your options? You could rename them, but that's not a good choice. With namespaces, you can store the Clip and Magazine away under the Guns or Weapons namespace, and you have absolutely no conflict. Your readable Magazine and your holds-things-together Clip can exist and there doesn't have to be any conflict whatsoever.

But as I said, it doesn't appear that BYOND has namespaces. So, why am I talking about this at all, then? Well, the thing is, BYOND does have them. In fact, you use them all the time. It's just that they are not immediately obvious. In most other programming languages, the separation between inheritance and namespaces are immediately apparent, because the way they are both handled is entirely different. BYOND, though, combines both of these things in its typepath system. A typepath, by default, indicates inheritance, but it is not the same inheritance. In fact, inheritance in BYOND can be overwritten. How?

The parent_type Variable

You may have used the parent_type variable before. Most people use it to see what the typepath of the parent is. For example, in our example above, the parent_type of each /animal/dog, /animal/fish, and /animal/bird is just /animal. When your code is compiled, this variable is automatically set to what the superclass is. The thing is, this isn't the only way to use this variable, and in fact this is more of a minor way of using it.

Here's the best thing about the parent_type variable: It can be set by the programmer at compile time, and this changes what the class inherits from. Thus, the programmer has the ability to entirely change the default method of inheritance in DM. Why is this useful? Because it can simultaneously be used to create namespaces. As I mentioned above, the notions of inheritance and namespaces in DM are tied together through the typepath system. Without explicitly overriding it, when you have something like /foo/bar, by default /bar.parent_type = /foo. But, by using the parent_type variable it is possible to turn /foo into a namespace. In fact, unlike any other programming language that I know of, /foo simultaneously becomes both a class and a namespace.

Implementing Namespaces

Now, back to the gun example I mentioned earlier. How would you implement this in DM? Below is one possible way.

gun
    /*
     * Here we implement the gun namespace/class. It inherits from /obj, but it becomes a top-
     *level class. Thus, to create a new gun object we just have to wrote new /gun. It is
     * not necessary to know that the /gun
     * is a type of /obj, and thus this information can be left out, if a user
     * so wishes.
     */

    parent_type = /obj

    var
        // The name of the gun.
        name

        // The type of ammunition the gun uses.
        ammunition_type

        // The type of magazine the gun uses.
        magazine_type

        // The magazine currently being used. May be switched out.
        gun/magazine/magazine

        // The mob holding the gun.
        mob/holder

    proc
        Load(magazine/m)
            if(!istype(m))
                // If it's not at all a magazine type, just return.
                return 0

            if(!istype(m, src.magazine_type))
                // If it's a magazine, but the wrong kind, temporarily Jam() the gun.
                src.Jam()
                return 0

            if(!istype(m.ammunition, src.ammunition_type))
                // If it's the wrong type of ammunition, jam the gun.
                src.Jam()
                return 0

            // If everything goes well, load the magazine.
            src.magazine = m
            src.magazine.gun = src
            return 1

        Jam()
            // Not actually implementing this, as the way it jams could really vary, and
            // it isn't really necessary to actually implement it.

        Fire(angle)
            // Attempts to fire a bullet in the given angle. This can be overwritten to,
            // for example, result in an inaccurate or unreliable gun.
            return src.magazine.Fire(angle)

    magazine
        /*
         * Now we implement the magazine.
         */

        // As with /gun, /gun/magazine derives from /obj.
        parent_type = /obj

        var
            // The type of ammunition the magazine stores. Just store a
            // typepath here.
            gun/ammunition/ammunition

            // The gun the magazine is loaded into.
            gun/gun

            // The amount a magazine holds. Should be an integer greater than zero.
            max_size

            // The amount currently being held.
            size

        New()
            // Create a new ammunition, as indicated by src.ammunition, and set
            // src as its magazine.
            src.ammunition = new src.ammunition(src)

            return ..()

        proc
            Reload()
                // Reloads the magazine.

                if(size < max_size)
                    src.size ++
                    return 1

                else
                    return 0

            Fire(angle)
                if(src.size > 0)
                    // The amount of ammunition in the magazine.
                    src.size --

                    // The bullet fires.
                    return src.ammunition.Fire(angle)

                else
                    return 0

    ammunition
        /*
         * And now we implement the ammunition.
         */

        // A type of datum. Ammunition only says how to model individual bullets, rather
        // than being something that exists in the world.
        parent_type = /datum

        var
            // The damage the bullet does.
            damage

            // The stability of the bullet. How much it wobbles in the air. A percentage.
            stability

            // The magazine the gun is attached to.
            gun/magazine/magazine

        New(gun/magazine/magazine)
            src.magazine = magazine

        proc
            Fire(angle)
                // Whatever happens here. Presumably, a bullet object would be
                // created (perhaps as a /gun/bullet, or an /obj/bullet, or whatever
                // solution works best).

And here we have a very basic namespace for guns, with a top-level /gun object and a few classes in the namespace that handle actually firing and etc. the gun. Note that neither /gun/magazine or /gun/ammunition are subclasses of /gun: /gun/magazine is a sublcass of /obj and /gun/ammunition is a subclass of /datum. While it may be confusing at first, and is an example of BYOND's muddling of the difference between inheritance and namespaces in its typepath system, it can result in far better organization of code. Below is one potential example of how we could utilize this namespace to implement a weapon.

gun/RPGLauncher
    /*
     * This implement a Rocket Propelled Grenade launcher.
     */

    name = "SP4NK3R"

    ammunition_type = /gun/ammunition/RocketPropelledGrenade
    magazine_type = /gun/magazine/RPGMagazine

    Fire(angle)
        if(prob(5))
            // The gun is kind of unreliable. There is a 5% chance that the gun
            // will explode rather than fire an RPG.
            src.Explode()
            return 0

        else
            return ..()

    proc
        Explode()
            // Do explosion stuff here.

gun/magazine/RPGMagazine

    max_size = 2
    ammunition = /gun/ammunition/RocketPropelledGrenade

gun/ammunition/RocketPropelledGrenade

    damage = 50

    // 85% stable.
    stability = 0.85

    Fire(angle)
        // Fires a new rocket in the angle indicated.
        new /bullet/rocket(angle, src.magazine.gun.holder.loc, damage, stability)

And, with this model would could extend the /gun/magazine/RPGMagazine class, to create subclasses that are special types of RPGs. For example, maybe there is a Napalm RPg or an Acid RPG. These would, presumably, still exist in the gun namespace to avoid any conflict outside it.

Summary

In conclusion, BYOND's typepath system is simply a highly-complex namespace system. The system can influence inheritance and such hierarchy, but this is only a default, overwriteable behavior, albeit one that simplifies things a great bit, but one that is not at all necessary. Sometimes, overwriting this behavior is useful, and even necessary, to write elegant, extensible, and easily-maintainable. Namespaces and inheritance are both powerful language features, even more powerful when used together, and while they can be confusing, they can also be one of the most powerful tools for defeating ambiguity and increasing clarity when designing code.

Beyond The Tutorial

As an aside, note that the typepath system makes it simple for their to be namespaces within other namespaces, allowing there to be a hierarchal system that breakdown differently at each level. This can be useful for extremely complex systems, where things are tied together and where collisions or ambiguity are a very conceivable and real possibility.

Namespaces are also very useful in libraries. They allow for the possibility of a number of different classes to be packaged under one namespace to avoid annoying and difficult-to-resolve collisions between a library and a user's own code. When a collision occurs, typically the only real solution is for a user to rewrite all of their own code to fix it, which is often more difficult than just implementing the library themselves! This makes namespaces a very useful tool in library development.

So You Want A Tutorial: Doors and Teleporation

Wed, 08 Feb 2012 21:00:04 +0000

I'm a programmer. As such, I am lazy. I also help people a lot on these forums. But I'm also lazy.

This is a conundrum. To solve this, I have decided to write a series of tutorials regarding common questions on these forums, so that I can link to them for convenience. See, I already do this quite often, but also quite often I have to expand on the topic. Thus, I wish to make detailed, instructional tutorials that will need little more expansion.

My first topic is on teleportion, and specifically door-like teleportion. That is, when something steps on a tile and is immediately transported to another place. This is a relatively simple topic, but one that can have numerous errors associated with it, despite the fact there is one well-known, fairly-uniform, simple result.

To start off, let's look at where things can go wrong.

How Not To Do It

First off, let's take a look at the wrong way to do it. Below is extremely simple, but it is also wrong in a good number of ways.

turf/Enter(mob/m)
    m.loc = locate(4, 30, 1)

There we go. Simple enough, right? When something tries to enter the turf, their location is to the location at (4, 30, 1). Only two lines, so this seems like a good choice, right? Wrong. In just two lines, I can identify four major flaws: It's not robust, it's not dynamic, it's not easily-modifiable, and it does not follow the interface set out for it.

What do I mean by robust? I mean it doesn't handle errors well. There are two very simple examples in this code. The first is the assumption that the argument is in fact a mob. While it will also handle well whether it's a mob or an obj, it will typically not handle well for anything else. For example, if somehow a turf or area were to be passed as arguments, this would crash, as their loc variable can not be changed at runtime. Additionally, if it happens that the object at (4, 30, 1) doesn't exist (perhaps the map was changed). This won't cause a runtime error, but it will likely delete the object being moved. If this object happens to be the player's mob, then they'll also be disconnected! Not good.

What do I mean by not dynamic? In order for this method to work, there has to be a specific object created for every possible door. If you want to go just one block over, for example, to (4, 31, 1), you have to create an entirely new object. This is ridiculous! There is no need for a new type of object for every door that can exist. There must be a better way.

What do I mean by not easily-modifiable? Well, assume you rearrange your map. Now your old coordinates don't work. You have to go through every object in your code and change their coordinates. On top of that, because it is not dynamic (as mentioned above), you also might have to delete a bunch of objects (if you don't want your code to get bloated).

Lastly, what do I mean by the code not following the interface set out of it? This is the most difficult to explain. Under the normal system of movement in DM. The Enter() proc should only ever take a movable atom (/atom/movable) and return true or false as to whether it can move to that location. The code within the Enter() function should not actually have any effect on the world, just return true or false as to whether something happened. The Entered() method, instead, should be used when something has successfully entered the turf. This is the interface that BYOND sets out for these procs. Other languages have stricter ways of enforcing an interface, but DM unfortunately does not. Thus, there are a lot of cases of people messing it up. To follow the interface, this type of code should actually be moved into the Entered() function.

Getting There

Well, now we know a few things. We need to use Entered(). We need to make it more robust and capable of dealing with potential errors. We need to make it more dynamic so we have less useless repetition. We need to make it more easily-modifiable, so that we don't need to go through a lot of work when we want to change something. How can we manage this?

Well, below is one possible way, which may have occurred to you.

turf
    var
        // The x, y, and z coordinates of the turf you're being
        // transported to.
        to_x
        to_y
        to_z

    Entered(mob/m)
        // We're using Entered() now, to follow DM's interface
        // for movement.

        if(istype(m))
            // Check that m is a mob,

            if(locate(to_x, to_y, to_z) != null)
                // If locate moves the player to a valid location,
                // then move them.

                m.loc = locate(to_x, to_y, to_z)

This seems like a much better solution, doesn't it? It uses Entered(), so BYOND's movement interface is preserved, we do type checking and value checking to help prevent errors, and we now have variables that allow us to be a bit more dynamic with our objects, keeping down bloat, and it makes it a lot easier to modify a map. Now, instead of setting the coordinates inside the code, we can just use the map editor to edit a turf's to_x, to_y, and to_z variables. The downside is that we're still stuck to our coordinate system, so if we re-arrange the map we might have a lot of coordinate sto change. Still, this seems like it could be the best we could do without getting a lot more complex, doesn't it? Well, not quite. There's a feature of DM that makes this a bit simpler.

The tag Variable

The tag variable is a special variable in DM that is used in conjunction with the locate() proc. If you set the tag variable of an object, then locate(tag) will return that object. Note that tag can not be set at compile-time, and multiple objects should not have the same tag variable. Thus, using the tag variable we can separate our system from the coordinate sysetm of the map, simplifying re-arranging it.

How To Do It

Taking all we have, we can now produce the following code.

turf
    // This is the tag of the location we're moving to.
    var/moveto_tag

    Entered(atom/movable/a)
        if(istype(a))

            // This stores the turf we're moving to. Note that tag
            // isn't only on turfs, but all /atom types. Therefore,
            // it's entirely possible that this is not a turf.
            // I do not typecheck here, though, because it is
            // up to the map designer to put a tag on the right
            // object, and they could have a reason for moving
            // the player to a non-turf.
            var/turf/t = locate(moveto_tag)
            if(t)
                a.loc = t

And there we have it. I've changed mob/m to atom/movable/a to allow /obj objects to pass through the door now, too. This gives us the most robust, most dynamic, most easily-modifiable solution that fit's BYOND's movement interface and is, at the same time, simple. This is the solution that the average user needs. Now, in order to set up a 'portal' between two doors (or whatever you have), you just need to edit the entry point's moveto_tag variable, and the exit point's tag variable.

Beyond The Basics

We could conceivably go well beyond this, though. For example, under the standard BYOND movement interface, when movement occurs, it is because the moving object's Move() proc was called, with their new location as the argument. Then the current location and the new location determine whether the user should move. Rather than directly modifying the moving object's loc variable, we could use the Move() proc to double-check whether movement should occur or not, or how it should occur. This could be used, for example, to implement traps, locked doors, or things blocking one or both ends of the door. Remember, BYOND's default movement interface, while lacking in features in a few places, is still very robust and useful, and it's a good idea to use it when you can.

It's also possible that you may want to use movable atoms rather than a turf or area as a portal. Because the Move() proc will never call the Enter() or Entered() procs, this has to be implemented in a different, but similar, way. There are two procs exclusively for the /atom/movable type that acts similarly to Enter() and Entered(), called Cross() and Crossed(). The implementation are very similar.

The Dunning-Kruger Effect

Tue, 07 Feb 2012 05:42:13 +0000

I'm sure more than a few people around here are aware of this, I just wanted to let people know of the Dunning-Kruger Effect. There are more than a few members of these forums who are a practical incarnation of it.

Woo, Orrery!

Sun, 05 Feb 2012 20:26:45 +0000

Now, this'd've been more suitable for the blogs when they were around, but they aren't around anymore so suck it.

If anyone remembers, in a time long, long ago, in the immeasurable distant ages of the old internet (maybe back in March or April?) I was working on a Javascript game engine utilizing the features of HTML5. That engine is called Orrery, and I've gotten back into working on it, rewriting it to work a little more nicely. I'm finally at the point where I can draw neat things!

For example, this, which I think looks pretty neat. :D

Everything in that is algorithmically-generated. There is no manual drawing of any of the polygons. In fact, this is the code I use to draw it.

var angle = Math.PI / 360 * 24;
var scale = 4;

var second_angle = 0;
var translate_x = 0;
var translate_y = 0;
setInterval( function () {
  angle += Math.PI / 360;

  second_angle += Math.PI / 360;
  translate_x += Math.PI / 720;
  translate_y += Math.PI / 720;

  var dx = 5 * Math.sin(translate_x);
  var dy = 15 * Math.sin(translate_y);

  Canvas.Draw.Translate(dx, dy);
  Canvas.Draw.Rotate(Math.PI * Math.cos(second_angle) / 180);
  Canvas.Draw.Translate(-dx, -dy);

  Canvas.Draw.Clear();
  Canvas.Draw.Polygon(40, -40, 12, 66 * scale,  angle * 4, { FillColor : '#100000' });
  Canvas.Draw.Polygon(40, -40, 11, 58 * scale, -angle * 2, { FillColor : '#321000' });
  Canvas.Draw.Polygon(40, -40, 10, 50 * scale,  angle    , { FillColor : '#543210' });
  Canvas.Draw.Polygon(40, -40,  9, 42 * scale, -angle / 2, { FillColor : '#765432' });
  Canvas.Draw.Polygon(40, -40,  8, 34 * scale,  angle / 3, { FillColor : '#987654' });
  Canvas.Draw.Polygon(40, -40,  7, 26 * scale, -angle / 4, { FillColor : '#BA9876' });
  Canvas.Draw.Polygon(40, -40,  6, 18 * scale,  angle / 5, { FillColor : '#DCBA98' });
  Canvas.Draw.Polygon(40, -40,  5, 10 * scale, -angle / 6, { FillColor : '#FEDCBA' });
}, 1);

Thus, I can basically scale it and increase its rotation speed and direction with just a few changes in the code (And I'm also getting, in theory, about 1000 FPS. In practice, it's about 85 FPS and I'm just telling the canvas to update as fast as possible). I've basically just finished working on my code for drawing basic figures (squares, rectangles, parallelograms, ellipses, circles, and regular n-sided polygons), and may just implement some other simple line-and-figure drawing, and maybe a way to draw a convex hull.

So, yeah. That's what I've been doing lately.

What.

Fri, 03 Feb 2012 23:36:40 +0000

http://thinkprogress.org/health/2012/02/03/417657/ santorum-tells-sick-kid-not-to-complain-about-1-million-drug -costs-because-people-pay-900-for-an-ipad/?mobile=nc

"While campaigning yesterday in Woodland Park, Colorado, GOP contender Rick Santorum told a sick child and his mother that they shouldnt complain about the exorbitant cost of his medication because some people spend $900 on iPads."

What.

My last blog post.

Tue, 24 Jan 2012 01:55:47 +0000

For a different reason than the rest. My account expires in a little over one week, and for the first time in years I'll have to go without a membership. My financial situation currently is incredibly awful, and while I'd like to renew my membership, I'm broke for a couple weeks until my next paycheck, and even then I really just can't afford it.

Well, I got my first membership when the blogs were a new thing, and I'll be going out as they're becoming an old thing (to an extent), so I guess it's kind of appropriate.

See ya.

Looking through old notebooks is interesting...

Sat, 31 Dec 2011 01:27:50 +0000

"Hello dying pen, you've been a good friend"

Just written at the top of a page. Nothing else related to it, anywhere.

Happy Festivus.

Sun, 25 Dec 2011 18:23:10 +0000

Because combo breaker.

Regular hexagonal tiling, hex grids, and coordinate system.

Wed, 21 Dec 2011 11:23:12 +0000

The title rolls right off the tongue, wouldn't you say? Lately I've been working on a non-BYOND project. One of the many I'll probably never finish. This particular one is the reason I started Orrery, the HTML5-based game engine I'm working on. In particular, part of the project is going to involve translating positions on a hex grid to positions on a Cartesian grid, which is the sort of grid that you normally see on stuff like graph paper, and is one of the most common coordinate systems.

Before we start off, I need to describe how my particular hex grid system is built. Starting some research on this topic, I used this site to begin. Basically, I begin with a simple Cartesian grid, as shown below.

The website I used suggested building a hex grid out of a rectangular grid. This is basically the same as a Cartesian grid, except the grid is stretched along the x-axis. My particular transformation basically multiplied the width by two, so I have (x', y') → (2x, y). This generates the grid shown below (overlaid on top of the Cartesian grid).

The red is the rectangular grid. The blue is the underlying Cartesian grid, which has been stretched.

Now, over-top of this I draw the hex grid, with a particular tiling relative to the rectangular grid, which I'll describe next.

Now, in order to do all this, I have to make a choice about what coordinates on the rectangular grid the hex coordinates will map to. I have chosen the coordinate of the first full rectangular block on the bottom-left of the hexagon, and colored these blocks gray so they stand out.

In addition to this, I've chosen a particular tiling for the hex grid to simplify our mathematics. From this point on, I'll use the notation R(x,y) to indicate a particular rectangular coordinate, C(x,y) to indicate a particular Cartesian coordinate, and H(x,y) to indicate a particular hex coordinate.

There is a highlighted rectangular block at the coordinate R(0,0). This is no accident. I have chosen this particular location so we can have the mapping H(0,0) → R(0,0). This means we won't have to translate the result of our transformation from the hex grid to the rectangular grid.

Now that we have that out of the way, we have to define our coordinate system for the hex grid. Often, when people attempt this, they try and emulate the Cartesian coordinate system. Basically, assume our drawing is on a piece of paper. The common method is define the x-axis and y-axis emulating, exactly, the underlying Cartesian system. The problem with this is that it results in alternating rows of hexagons having different x values, because in a hex grid you can't move straight 'up' into another hexagon; you have to move two rows to do this.

As it turns out, this particular pattern is not very optimal. For one, it's just plain wonky. Two, it doesn't allow for nice translations to a Cartesian grid. The basic idea isn't flawed, though. Once again, with our paper example, there's no real problem with having an x-axis that increases from left-to-right as you move along the bottom of the paper, and there's no problem in having a y-axis that increases as you move bottom-to-top along the side of the paper. What you can do to rectify this, though, is have the x-axis move diagonally, through the hexagons. This results in the coordinate system below.

The orange lines are the x-coordinates. The green lines are the y-coordinates. The thick lines indicate x-coordinates and y-coordinates of 0. The origin is where these intersect

Using this particular orientation, we now see that, indeed, H(0,0) → R(0,0).

Now, we need to define our linear transformation that converts our hex coordinates into rectangular coordinates. The concept is much, much more nuanced than this, but basically our particular linear transformation boils down to this. There exist constants a,b,c,d such that R(x', y') → H(ax + by, cx + dy).

To do this, we need to find a few sample points on our grid to test. Really, we only need two, though it helps to not choose the sample points H(0,0) → R(0,0). I'm going to choose the sample points H(0,1) → R(1,3) and H(-1,-1) → R(-3,-3). You can verify these yourself.

Now, our linear transformation is as follows:
x' → ax + by
y' → cx + dy

We have two sets of sample data that for each of these. We know x, x', y, and y', so we plug these in. For H(0,1) → R(1,3) we get
1 → 0a + 1b
3 → 0c + 1d
and for H(-1,-1) → R(-3,-3) we get
-3 → -1a + -1b
-3 → -1c + -1d
This allows us to create two systems of equations:
1 = 0a + 1b
-3 = -1a + -1b

3 = 0c + 1d
-3 = -1c + -1d
Solving this system of equations gets us the following constants:
a = 2
b = 1
c = 0
d = 3

Thus, we get the transformation R(x', y') = H(2x + y, 3y). If we plug in our sample points, we see that we get what we should. H(0,1) → R(1,3), H(-1,-1) → R(-3,-3), H(0,0) → R(0,0).

The thing is, we would like the Cartesian coordinates, not the rectangular coordinates. We're working on a Cartesian grid, after all. This happens to be very simple. Above I noted (using slightly-different notation), C(x',y') → R(2x, y). Because we Know R(x',y') → H(2x + y, 3y), we can just plug in the Rectangle-to-Cartesian transformation into the Hex-to-Rectangle transformation: C(x',y') → H(2(2x + y), 2(3y)) = H(4x + 2y, 6y). Thus, to transform between hex coordinates and Cartesian coordinates, we have C(x',y') → H(4x + 2y, 6y). Simple enough.

Lastly, we will likely want to convert from Cartesian coordinates to Hex coordinates. This could be complicated depending on the transformation. Luckily for us, it's simple. We can use the transformation we already have. Basically, we have the following equations above (after swapping the variables around):
x = 4x' + 2y'
y = 6y'
And now we solve for, in the first equation, x', and in the second equation y'. For the second equation, this is simple:
y' = y/6
The second equation gives us
x' = (x - 2y')/4 = (x - 2y/6)/4) = x/4 - y/12
Thus, our transformation is H(x',y') → C(x/4 - y/12, y/6). This transformation will, though, will generate non-integer values, which are not actually meaningful for our hexadecimal coordinate system. Thus, we simply need to floor the resultant values: C( floor(x/4 - y/12), floor(y/6) ). This gives our transformation. Once again, you can test with a few sample points, like those above, to verify this is true.

Now, because BYOND uses a positive Cartesian grid (meaning that BYOND only uses the first quadrant of a Cartesian grid), this isn't necessarily the best layout to use. In fact, it may be better to shift the hex grid up by one, so that the very hexagon at H(0,0) is completely on the map. This means that when we convert from Hex coordinates to Cartesian coordinates, we need to subtract one from the transformation, and add one when we convert from Cartesian coordinates to Hex coordinates. These leaves our transformations as follows:

C(x',y') → H(4x + 2y - 1, 3y)
H(x',y') → C(x',y') → ( floor(x/4 - y/12 + 1), floor(y/6) )
As it happens, this means our translation is no longer a linear transformation (in fact, it becomes an affine transformation), but this doesn't matter for most applications, and it greatly simplifies things.

And thus, we have the mathematics of one potential regular hexagon grid and coordinate system in BYOND. This isn't necessarily the best for every game. For example, someone may want to have the flat portion of the hexagons be at the bottom, rather than the sides, which requires different mathematics. Or they may want differently-sized hexagons. Still, using this you should be able to get a start on what the mathematics of the transformations for your system need to be!

Dark Matter

Tue, 06 Dec 2011 01:34:58 +0000

I HATE, HATE, HATE people who compare dark matter to luminiferous aether. It just shows how ignorant of science, theory, and evidence they are.