Pizazz 1.2.0

Hey there! Long time no type. How’s it been going with you? It’s time for a new release of Pizazz. I’ve been distracted lately, so a lot of these improvements are overdo. Let’s see…

I added a new shortcode that allows you to embed Pizazz into your posts and pages, which will allow you to make store pages and advertise your products where they’re relevant. Are you blogging about asparagus? Then why not embed a Pizazz product feed with a bunch of asparagus T-shifts and mugs? Just type in [pizazz store=asparagus rows=8 columns=3] into your post and you’re ready to go! For the full documentation on Pizazz’s shortcodes, go to Settings->Pizazz and scroll down.

There is also a few more customizations. You can now change the alignment of text or just make it disappear and links can be made to open in new windows and the prices can be displayed right next to your products! This should give you a bit more flexibility while designing your website.

Lastly, the associate ID used to get referrals has been moved from the widget properties into Settings->Pizazz. I was worried that people would have to copy and paste their ID into all of their shortcodes and it would become too difficult to maintain. A dialog box will appear at the top of your administrative control panel after the update to remind you, so don’t fret!

The new release is up at the WordPress plugin repository. I recommend you update and check out these cool new features. Tell me what you think in the comments below and if you need help, check out the support area at WordPress!


Tiny BASIC Compiler

I wrote my first compiler! A few weeks ago, actually… I’ve been procrastinating this blog post because I haven’t been too sure what to say on the subject. It’s a very simple compiler that takes Tiny BASIC code and outputs NASM Assembler that can be compiled into MS-DOS/FreeDOS executables.

TinyBASIC is a simple microcontroller language from back in the days where 4K was a normal amount of RAM. It was popular because it could fit in 3K and still run your reasonably useful programs. It looks like this:


10 LET I = 0
20 LET X = 1
30 LET Y = 0

40 PRINT “FIB: “; I, X

50 LET Z = X
60 LET X = X + Y
70 LET Y = Z

80 LET I = I + 1
90 IF I <= 10 GOTO 40

Pretty neat, eh? It’s actually pretty easy to parse when you get in the hang of things. I read the first few chapters in Jack Crenshaw’s tutorial on compilers, Let’s Build a Compiler to get a basic expression parser running and did the rest on my own. Now, that code above compiles and runs perfectly!

The most important thing I learned from this, after all my previous attempts at writing compilers, is that parser generators are time-wasters from the depths of hell. It takes me three hours to set up something that looks like it might parse the code — not compile, but parse — that throws constant errors while I got a few working statements from my hand-written compiler in one.

The resulting code is much cleaner, too, because you don’t have a parser generator putting in tons of impossible-to-read tables and includes that it shouldn’t even need (Bison WTF is wrong with you?). LALR parsers, from what I understand, are the primary output of most of these parser generators. They seem to have a reputation for being almost unreadable and unwritable by human beings, and I have yet to find an upside to them other than that they are memory-efficient compared to some of the alternative results of parser generators. At the same time, I only use a few global integers in my compiler, and the code is smaller… especially considering that the compiler includes both a scanner and parser in the same code set.

I also found that writing the compiler by hand was much more enjoyable as immediate results were faster to procure and having full control and responsibility for the code felt more challenging. Considering I’m primarily a hobbyist, challenge is one of the most important parts of anything I do.

I targeted MS-DOS/FreeDOS because it has what is quite possibly the cleanest and simplest system call table that I’ve ever encountered (in other words, it was really easy to target). I used DosBox to emulate the MS-DOS kernel on my GNU/Linux machine. By request of a friend of mine, I tested my compiler on Windows and found that the resulting executables ran natively. Now that’s backwards compatibility!

All in all the project was pretty fun and the result was a neat little toy. This new skill should come in handy when it comes time to implement scripting into one of my game projects. Lua is for babies!

The source code is available online under the GNU General Public License version 3 or later. Leave a note in the comments if it helps you figure out how compilers work! If you are really interested in writing your own compiler, I highly recommend Jack Crenshaw’s tutorial. It’s very helpful and spans over topics from expression parsing to interpreters.

Stay tuned: I’m doing some finishing touches on a new release of Pizazz and have been doing some behind-the-scenes work on CANINE!

Pizazz 1.1.1 Released

Ah…the feeling of fixing bugs. It’s very satisfying, but not as satisfying as releasing those fixes to the world. Now is one of those wonderful times for Pizazz.

The first thing I wanted to deal with is that the thumbnail-size property stopped working. Previously, I had used PHP’s str_replace function to change “_125.jpg” to “_theCustomThumbnailSize.jpg”. As it turns out, Zazzle automatically generates the images based on the last number in the filename, hence I was able to implement this nice little feature. However, for some incomprehensible reason Zazzle changed the default number to 152. I’m pretty sure that’s a typo, because the five and two have been switched and that’s it. Generally this would be dangerous for everybody who relies on this default size to use the feed in any of their products.

The fix for this is pretty simple, but I had to fix something else, first. I installed Pizazz on my fresh, new test server and it didn’t work. At all, or at least at all by default. If you chose the lucky tags then it would work perfectly. After awhile I figured out what was wrong: the RSS feed was broken (or, better put, malformed). The titles of the products in some areas contained ampersands (“&”). Normally this is fine, except that they were just ampersands. Under XML (from which RSS derives), the ampersand has a special meaning. It is used to identify special characters; for instance, “&gt;” indicates the greater-than sign (“>”). So, an ampersand on its own is erroneous, and should actually be “&amp;”. Sadly, the XML parser I was using — SimpleXML — isn’t forgiving, and would abort on such lines. Most XML parsers break on these types of things, even Internet Explorer failed to read these feeds (though that browser fails on a lot of things). However, since Pizazz was made for Zazzle, and Zazzle always does things like this, SimpleXML had to go.

I rewrote the parser to use PCRE — Perl-Compatible Regular Expressions — to extract data from the text file without parsing it as true XML. So instead of running the XML parser and pulling out the data from a specialized PHP data structure, I just asked PHP to give me the text in between each “<item>” and “</item>”, then from there pull out the title from “<title><![CDATA[” and “]]></title>”, etc. This also removed the need for a number of verifiers that I wrote in to handle when Zazzle only produces bad RSS every-other request (that happens sometimes). In combination, this results in faster feed-caching and much more forgiving RSS parsing. The number of times that Pizazz abruptly fails due to XML parsing errors has been greatly reduced if not eliminated. Even when Zazzle returns its home page surrounding the RSS data the proper fields can still be extracted!

Great, now I could get back to the bug that I initially wanted to fix: the thumbnail sizer. Well, I could have just changed the parameter for str_replace from 125 to 152, but I’m absolutely sure that Zazzle will change this number again and I’ll have to change that again. So, instead, I just got PCRE to replace “_anyNumberAtAll.jpg” with what I want. That fixed it for now, and should prevent anything like this from happening again.

Then I got a bug report from one of my clients using multisite. Specifically, Pizazz didn’t work on multisite (well, it sort of did). Before, she activated Pizazz on each sub-blog individually, which circumvented the problem where “Network Activate” would crash WordPress’s network dashboard with a E500 Internal Server Error. I was going to fix Network Activate but, considering that there was a way around it and I had other stuff on my mind, I deprioratized it and ended up forgetting about it. Well, she got around to enabling it on the main site, and ended up breaking the network dashboard again. There was no way around this one, so I had to go working on it.

During the first day I successfully fixed the undefined-function error PHP was spewing out by moving Pizazz’s initialization code into a WordPress init-hook, as I technically should have from the beginning. This resulted in a different error: “function get_current_screen is not defined in /…/wp-admin/network/settings.php.”

This one took me 36-hours to debug. I painstakingly scoured the blogs, the WordPress codex, the forums, anywhere Google would take me and never found anything that would solve my problem. Worse off, PHP doesn’t give tracebacks unless you install a debugging plugin, which wasn’t a viable option. I kept on trying new things, including rewriting the settings page entirely. Albeit, the rewrite resulted in a cleaner script and moved the settings into their own page, which was nice, but it was (is) still frustrating.

I ended going onto my client’s server and just putting in a bunch of die calls throughout the source code, trying to pinpoint where everything went wrong. I knew it was in settings.php, and the die calls didn’t help any further. That error kept cropping up in the network dashboard, and I couldn’t figure it out!

Finally, I commented out the code that loaded settings.php because I just wanted to remember what the network dashboard looked like. Then, carelessly, I hovered over and past the Network Settings tab. I froze, then moved my mouse back. I noticed that the Network Settings didn’t have any plugin fields listed. I looked back at the main site dashboard and hovered over the settings there and saw the plugins again. I un-commented the lines that loaded settings.php and looked back. The network dashboard stopped working, but the settings field worked perfectly in the main site dashboard. I wanted to scream.

You can’t register options pages in the network dashboard! As opposed to WordPress raising an error when this was attempted, it prevented the function from being created in the assumption that plugin developers would know what the “undefined function” error meant. They don’t say that you can’t define option tables ANYWHERE in the documentation! I checked, it isn’t there. No wonder so many plugins don’t work in multisite, they don’t document these incompatibilities! All I had to do was change ( is_admin() ) to ( is_admin() and ( ! is_network_admin() ) ) and it worked again. Who the hell manages the codex!

There was much internal screeching, pacing and (for some unhealthy reason) eating that came afterwards. This has to be one of the most frustrating things I have ever had to deal with. One line, one problem that I wouldn’t have had if they had just documented it!

Eh…anyway, here’s the new plugin. All these bugs have been fixed and there are some minor code clean-ups. I don’t remember at which point it was but I rewrote the cache manager to use opendir instead of glob when iterating through the files, because for some reason glob doesn’t always work when opendir does, so that should help any users who had or would of had a problem with this.

Now, I’m going to play with writing a little TinyBASIC compiler to cool off, and when I’m back to Pizazz I’ll implement shortcodes to embed Pizazz product inventories into your posts and pages. Keep tuning in!

Pizazz is available here.

CANINE: Billboards ‘n’ Stuff

Before I get into what progress I’ve made with CANINE, I’d like to start out with mentioning some stuff that I forgot about in the last post. I had learned something very important at the time, and I feel that I should spread the word so that this mistake is made less often: the C math library does not handle degrees. I had so many problems because of this, so many times, and I keep having it. The C standard math library takes and outputs radians. It’s not that its hard to convert from one or the other, degrees to radians is d*M_PI/180 while radians to degrees is d*180/M_PI, it’s just that the math books I’ve grown up on always handled degrees and rarely even mentioned radians. Turns out that’s pretty lame, because I’m constantly encountering radians in the word of applied mathematics. Yet again, OpenGL runs with degrees. What’s up with that?

The only other thing I think is worth mentioning is how to convert from Vandevenne’s direction vectors into an angle. atan2(player_direction_y, player_direction_x) gives it to you in radians; take special note that y comes first! Also, it’s useful to execute gluPerspective(field_of_view_angle, display_width/display_height, 0.2, longest_dimension_in_level) on the projection matrix when rendering the 3-D objects. Vandevenne’s raycaster runs at a field of view angle of 66 degrees — and OpenGL, as I’ve said, does take degrees — and the longest level dimension is used to prevent parts of the game from being clipped by OpenGL’s z-buffer.

Now, back to the present.

It’s taken me a week to figure out how to, but I’ve finally got the sprites to render. In OpenGL terminology they’d be called “billboards,” polygons that always face you, like in Wolfenstein. All of the tutorials I found through Google failed and confused me. At one point I just grabbed Wolfenstein iOS’s source code to see how they did it, and I tried to implement the same technique. It didn’t work…at all. My engine’s implementation seems to be largely incompatible with theirs; not even our coordinate systems are compatible. (Mine’s better, by the way. =P)

Today, I deleted all of the billboard code that I had and started from scratch, clear-headed and focused. Guess what, I figured it out in half an hour. *facepalm*

The first thing I did was just trying to get the sprites to render as northern walls so that I could see them. They rendered all right, but in the wrong coordinates. *sigh* I forgot that my coordinate system is not 100% compatible with OpenGL’s. In order to convert from mine over I have to do -map_width+y. Goody, now I have sprites in the right locations, sort of. As supposed to being in the middle of a tile like the should they’re aligned to the northern-most Y axis and they don’t even rotate.

This turned out to be a simple problem to solve. First off, centering it was as simple as adding 0.5 to the X coordinates. Next, Vandevenne’s usage of vectors for the player location made rotating it towards the player easy, and it’s even cleaner then Wolfenstein’s — probably faster, too! As opposed to dealing with sines and cosines, the polygon coordinates are as simple as:

x1 = x + (1 - player_direction_x) / 2;
y1 = y - 0.5 + player_direction_x / 2;
x2 = x + 1 - (1 - player_direction_y) / 2;
y2 = y - 0.5 - player_direction_x / 2;

Ka-bam! I’ve now implemented a completely functional billboard sprite system. Ah…it feels good. My modification of Vandevenne’s raycaster also let me cull out the invisible sprites by checking if they were standing on visible tiles. Satisfying.

Now for the YouTube-hosted video example. You might notice the walls have a brown edge at the top. I added those to make sure that they were rendering right-side up, and for some reason felt the reason to keep them for this video. Without further ado…

Argh, wait! Just as I started preparing the video I found a problem: in a ring of sprites, at certain angles some of them will only render part of themselves. It seems to be a problem with the transparent border around the other sprites or some such. A quick Google says that I might have to sort them and draw them in order, but I’ll save that for next time. I’ll still show you the video, though. Enjoy!

CANINE: From a Map to a World

Back in the first post where I announced CANINE, all I had was a 2-D grid representing the level that highlighted the parts of the screen that were visible to the player through a theoretical frustum. I have since implemented a three-dimensional world using the same data model. It wasn’t really that hard using OpenGL: the walls can be positioned at real 3-D coordinates, and the graphical processing unit (GPU) will take care of the rest. The main difficulties are figuring out how to store the polygon data and avoiding polygons that won’t even be visible at the player’s current angle. However, this was mostly solved in the 2-D raycaster from my previous post. The only additional polygon-culling I’ve done is glEnable(GL_CULL_FACE), which tells the GPU to ignore polygons drawn in counter-clockwise order (thus only showing polygons that are facing you) and this pseudocode:

if x < player.x: draw_wall (x + 1, y, WEST_WALL)
else if x > player.x draw_wall (x - 1, y, EAST_WALL)

if y < player_y: draw_wall (x, y - 1, NORTH_WALL)
else if y > player_y: draw_wall (x, y + 1, SOUTH_WALL)

This ignores any polygons that would be facing away from you and, thus, hidden by the rest of the wall. I think this actually kind of eliminates the use for glEnable(GL_CULL_FACE), but I don’t think it’s doing any harm to double up here. I’m thinking of having 3-D sprites in the future, in which case glEnable(GL_CULL_FACE) should really help.

Here’s a comparison of Vandevenne’s raycaster (see first post) and mine using solid colors:

(Videos now with Beethoven!)

Just yesterday I added two new cool features to this, both of which reassured me of the superiority of hardware- over software-rendering systems. The first is the addition of textured walls. Under Vandevenne’s software renderer, using only 64×64 textures on a 512×384 display, it runs at about 50 frames-per-second on my Dell Optiplex 745 with Arch  Linux. My hardware-accelerated engine, using 256×256 textures at 1024×768 runs at about 70 frames-per-second. Porting back those dimensions to Vandevenne’s engine, his only runs at 10-20 frames-per-second! Pretty impressive, eh?

Of course, Vandevenne’s limitations are only important for developers who actually want those dimensions, but who wants to be limited like that? Also, OpenGL is automatically stretching textures as needed, while that would have to be directly implemented in Vandevenne’s renderer. This means that under my engine, you could have 64×64, 256×256 or even 100×42 textures all in the same level without having to worry about it.

The second thing is that you can look up and down in my engine now. Albeit, that’s kind of pointless when everything in the game such short walls and items are always at the same level as you, it can be pretty cool (especially if skybox’s come into play — (^-^)).

Disclaimer: I don’t mean to insult Lode Vandevenne and his renderer. Without his tutorial, I wouldn’t have understood raycasting so quickly. His renderer shows all the nitty-gritty details of how raycasting works. It’s an amazing way to speed up hardware rendering, and is required in the equivalent software renderer. It also has some interesting implications in enemy logic (can the enemy see me?).

Raycasting: Wolfenstein’s Goldmine

Do you remember that game from the 90s, where you’d massacre a-hole Nazis in an attempt to escape a castle, and for some reason all the walls were the same height, and everyone was always looking directly at you? Yeah, I’m talking about Castle Wolfenstein 3-D, one of the earliest “3-D” games for MS-DOS, ported to a variety of other platforms. Why do I say “3-D” in quotes, you ask? Technically, it wasn’t 100% 3-D. Although everything was drawn in a way that looked 3-D, it was all represented as a 2-D grid. That’s why you never found anything above anything else and you couldn’t look up or down. This is generally referred to as pseudo-3-D or “2.5-D” technology. It wasn’t until Quake that true 3-D came to the first-person-shooter genre.

Have you ever wondered how they got Wolfenstein to render so quickly on such old computers? It was pretty simple, actually: they used a technique called “raycasting.”

First, think of the game as a 2-D grid, where each cell represents an optional cube, where each side is a wall. Now place a player in one of the empty cells, looking in some random direction. The question is, which walls are on screen and at what angle and distance should they be rendered? Wolfenstein’s process went a little something like this:

For each column on the screen…

  1. Generate an angle to project a ray towards. At the center of the screen, the ray should project perpendicular to the player. It should lean more towards the left the more left the column is and towards right the more right the column is.
  2. Project the ray until it hits the side of a cell. Repeat this until the cell has a cube in it.
  3. Calculate which column of the cube’s wall was hit, calculate its distance and render it to the screen at the current screen column with the appropriate stretching.
  4. Remember the distance of the wall rendered at that column of the screen in a so-called “z-buffer.”

Next, the sprites are rendered:

  1. Sort all of the sprites in order of distance.
  2. For each column of each sprite in closet-to-furthest order…
    1. Determine which point on the screen the sprite’s column would be drawn to.
    2. Ensure that the column actually exists on the screen (i.e. if it’s too far to the left or right).
    3. Ensure that the sprite column is not behind a wall via the z-buffer.
    4. If the previous two conditions are false, then draw the line with appropriate stretching.

Special thanks to Lode Vandevenne for his excellent tutorial on the subject. If you want to see exactly how to implement this technique yourself, his tutorial is a powerful resource.

So, this is all well and good, and I made my own Wolfenstein-style game engine this way. I had one problem with it though: it was a software renderer. Software renderers are inefficient and, by today’s video game standards, almost deprecated. So, I wanted to figure out how to bring this to OpenGL.

Thanks to id Software, who was nice enough to release the source code for the original Wolf3D along with their iPhone port, I discovered a cool way to do this. After a few minutes examining the iPhone port, I discovered that they continued to use a raycaster, but instead of rendering each wall as it was hit and drawing the sprites later, they kept a secondary grid that stated which cells were visible.

At the beginning of the process, every cell was marked as invisible. Then, whenever the raycaster passed over or collided with a cell, that cell was marked as visible. Afterwards, they would just go through each wall and sprite and render them if they were in one of these visible cells. They didn’t have to worry about what was in front of what because OpenGL automatically takes care of z-buffering.

Not only does this use hardware-accelerated graphics, but it also means that you don’t have to go through the rendering process for every single sprite in the game! If the sprite is not in a visible cell, it can be ignored completely. In the old algorithm, even if it was completely hidden by a wall you would have still had to check per-column.

I’ve begun the process of implementing this technique. For the software-rendered version I had used the Simple DirectMedia Layer, but for this I’m using Allegro 5.x. I’m using a modified version of the raycaster I built from Vandevenne’s tutorial, and it’s going pretty well. So far, I’ve managed to get a 2-D map to represent the visibility grid by highlighting cells that the raycaster hit. From what I can tell, it’s showing everything that can be seen and nothing else, exactly as it should. Here’s a video of me playing with it:

This game engine will become the basis of a retro, Wolfenstein-style video game I’m working on, code name CANINE (all-caps for awesomeness). Keep checking the blog or subscribe if you want to see how it goes. I’ll be posting about my progress and all of the cool little programming tricks I’m using on the way.

Happy coding!