GridWorlds

Animation Chains with jQuery

Jason Gibb — Sun, 09 Nov 2008 21:30:39 +0000

Using the animate() function built into the core jQuery library, you can generate complex, multi-step movement or visual effects using any element on your Web page. No Flash or Silverlight is needed, just the CSS and JavaScript capabilities built into your browser. The secret to complex animations is jQuery’s ability to “chain” multiple functions together to apply actions sequentially. Here’s a sample:

In the animation above, notice how the missile first travels from the avatar to the monster, then turns into a starburst that fades out and disappears. This effect is actually three separate animate() functions chained together. Let’s break it apart to see how it works.

First, Some Setup

I have placed three images on the page: an avatar graphic, a monster graphic, and a missile graphic which is initially hidden (display: none). I actually put all three of them inside a div to keep them together, but this is not strictly necessary — they can be anywhere on the page. I also give each tag a unique id I can reference later.

Bring On jQuery

Now I pull in jQuery from Google’s AJAX Libraries API page. Google has made many of the most popular JavaScript libraries freely available for developers via hosted URLs so you don’t even need to download and install them on your server. That’s just awesome.

I have chosen the minified version of jQuery 1.2.6, but you can get the latest version automatically if you prefer.

Where’s the Missile?

For convenience I assign the missile image (selected with that unique id I set above) to a $missile variable. Now I need to figure out where to send the missile. JQuery provides a method to find the position of any element named, oddly enough, position(). I select the gauth and assign the position object to a $end variable. The position object contains two properties: top and left.

Build 42 Released

Jason Gibb — Wed, 24 Sep 2008 03:50:08 +0000

Here is a summary of this release: Yesterday I deployed build number 42 to my DreamHost server. Everything was broken, so I rolled back to build 31. Everything was still broken. Today, I re-deployed 42 and everything works again. So, what happened?

Untyped and Unterminated

After deployment, I was getting “untyped binary data” errors on random pages in Firefox (also known as the dreaded “application/octet-stream” issue on the Windows side) and “unterminated string literal” errors in all my Ajax calls. I spent much time and effort pulling out my hair trying to figure out how code that worked so smoothly on my MacBook Pro could die so spectacularly in production. Did I forget to check something in? Did I not test enough? Am I just unlucky?

As is often the case, the problem was the server configuration and not the code. I have been using FastCGI on DreamHost since I launched GridWorlds, and for a while now it has been working well. All that changed recently, which apparently caused my application to wig out quite badly.

Enter Passenger

Thankfully, the solution was at hand. I have been meaning to switch over to Passenger (also known as “mod_rails”) since DreamHost announced it earlier this year. Since I had no idea what was wrong with FastCGI, and I absolutely hate messing with obscure server configuration problems (and yes, I was desperate to find a solution), I thought I’d give it a try sooner rather than later.

DreamHost has a wonderful “one-click” Passenger setup that is 100% seamless and actually works beautifully. I didn’t have to change one thing in my Rails app to make it work, and all the weird errors I was seeing magically vanished. Switching to Passenger reminded me why I enjoy working with Rails in the first place: it’s easy to set up, and you don’t have to go digging in XML files to get your application to run.

What’s In This Release?

This time around, I added a whole bunch of new features to GridWorlds, including combat with animation and sound effects (yes, you can finally kill things!), character creation, and automatic saved games. I also added a lot of “polish” with clearer screen flow, better error handling, and nicer form layout. Here are the highlights:

Implemented a combat system, including animation, sound effects, damage, and death
Built a character creation screen to customize your new character’s attributes, HP, starting gold, etc.
Replaced JS prompt()-based talk feature with an in-line text editing talk mode (much more immersive)
Enhanced inhabitant talk options to include random responses, hello and goodbye responses (and no more |-delimited text)
Reworked inhabitant “behavior” system to allow for changing behaviors after being attacked (so a friendly inhabitant will turn nasty if you take a swing at him)
Added an avatar stats box, so you can see details about your avatar during game play
Applied a new layout to all forms
Cleaned up validation and error message styling
Simplified navigation and screen flow to make things clearer for new players (fewer things to click, less confusing)
Added a “Rest” command to allow the avatar to heal — but it only works when there are no monsters around
Implemented a save game feature, which stores the current state of each map. There’s also an auto-save feature that automatically saves the game every time the avatar enters a new map.
And of course, tons of bug fixes, refactored code, etc.

42

The number 42 has a certain significance that will not be lost upon most who read this. I didn’t plan to release a build number 42, it just happened that way. Kinda spooky, isn’t it?

Secrets of Links in Rails

Jason Gibb — Mon, 25 Aug 2008 02:40:06 +0000

Rails provides a handy method for creating a link in your views:

link_to "Home Page", "http://gridworlds.com"
=>  Home Page

Of course, if this were all the link_to() method did, there would be little reason to use it instead of just typing the HTML directly. This method makes it easy to generate links that tie directly to controllers and actions. For example:

link_to :Edit, :controller => :user, :action => :edit
=>  Edit

If you leave out the controller, Rails assumes the controller that called the view:

link_to :Edit, :action => :index
=>  Edit

Conditional Links

The UrlHelper module includes several other methods to make linking easier. Sometimes you need to display a link conditionally. For example, in a navigation menu you may not want to link the active navigation item for the current page. You could always wrap a link in an if/then statement, like this:

if navigation != active
  link_to "FAQ", "/faq"
end

But why use three statements when one will do?

link_to_if navigation != active, "FAQ", "/faq"

Rails includes two other conditional link methods you may find useful: link_to_unless() and link_to_unless_current().

Secret Life of Links

The secret of link_to() is that it uses url_for() to generates these URLs. The url_for() method allows you to generate only a URL without the corresponding tag. When would you do this? How about in a JavaScript onclick handler:


I want this whole div to be clickable

url_for() also includes a bunch of options for setting the host, protocol, anchor, generating absolute or relative links, etc. Check out the Rails docs for full details.

What About Query Parameters?

Both link_to() and url_for() provide an undocumented way to include additional query parameters in your URLs. While it is easy to include an ID, like this…

link_to "Edit User", :controller => :user, :action => :edit, :id => 12
=>  Edit User

…what if you want to generate a URL with both an ID and separate query parameters? Just tack on additional parameters at the end, like this:

link_to "Edit User", :controller => :user, :action => :edit, :id => 12, :firstname => "Joe", :lastname => "Smith"
=>  Edit User

There’s one gotcha here: Rails tries to guess which parameters are options for the link_to() or url_for() methods and which should be converted to query parameters. If you aren’t explicitly using {:curley => :brackets} in your method call, Rails may interpret your options as query parameters. Here’s a good example:

link_to :Test1, :controller => :user, :action => :edit, :id => 12, :confirm => "Are you sure?"
=>  Test1

link_to :Test2, { :controller => :user, :action => :edit, :id => 12 }, :confirm => "Are you sure?"
=>  Test2

Notice in the first example the :confirm symbol is just another query parameter, while in the second example :confirm is a JavaScript dialog. The only difference between the two is the addition of curly brackets to make the confirm explicit.

Build 31 Released

Jason Gibb — Mon, 26 May 2008 17:50:27 +0000

What’s been happening with GridWorlds lately? Another three months have passed since the last update, and while I’m not trying to do quarterly releases it seems to be happening unintentionally.

This release brings a fairly major architectural change to GridWorlds, which partially explains the delay. Since the early days I had been trying to turn this into a multi-player game, so different avatars could interact and explore the same dungeons. That’s a great idea for a big client-server game with lots of powerful servers and network bandwidth (I’m talking about you, WoW), but not so practical for a small, Web-based game like this one.

As I added new features for the next release, I noticed the game becoming slower and slower, until it no longer resembled a real-time RPG so much as a tedious turn-based game. A few tests quickly showed that even a handful of gamers playing simultaneously would bring almost any server to its knees.

Therefore, I reluctantly gave up on the idea of multi-player, and switched to a much simpler single-player implementation. While this removes some of the cool features like real-time chatting with other avatars, I think it returns to the roots of games like Ultima that I have been trying to emulate all along. Not only will this speed up game play, but it has dramatically simplified the code base. This will make it much easier to build out game features more quickly, rather than wrestling with multi-player performance issues.

Besides, single-player games can be just as much fun as multi-player! Try out this new version, and let me know if you agree.

Build 31 includes the following updates:

Stripped out all of the multi-player code, which streamlined everything considerably
Converted worlds into groups of maps - each world has a default map so avatars always enter the world at the same location and map editors can create separate “campaigns” (unfortunately, this forced me to wipe out any existing maps people may have already created… sorry about that)
Modified maps to support multiple tilesets (mix and match tiles on the same map!)
Implemented spawning of random encounters (so new monsters can appear on the map over time)
Implemented different movement patterns for inhabitants and encounters, including wandering, approaching, and avoiding
Added a “Look” command to view info about anything on the map
Added an “Attack” command to kill things on the map (no real combat yet - they die instantly and don’t defend themselves)
Added a handy “edge of the map” border line on the map editor
Implemented a much better cross-browser JS-only player for sound effects (thank you, Zwitserloot)
Improved drawing routines to speed up maps and eliminate flicker in Firefox
Implemented Rails single-table inheritance for denizens to handle the distinction between inhabitants and encounters more cleanly
Added drag-and-drop in map editor to easily move portals, messages, inhabitants, and encounters (using the very slick jQuery UI library)
Upgraded to Rails 2.0.2 to eliminate annoying JSON bugs, convert to cookie-based sessions, and take advantage of other framework improvements
Upgraded to jQuery 1.2.5 just for the heck of it
Moved most of the JavaScript code under a single “grid” global variable to avoid potential namespace collisions (see Global Domination blog entry for more info)
Tracked down a major performance issue with Safari 3 and reported it to the WebKit team: rapidly swapping out dozens of background images will quickly eat up lots of memory
Added the bundle-fu plug-in to merge JS and CSS files into bundles for much better performance
Numerous other small bug fixes and enhancements

Build 21 Released

Jason Gibb — Sat, 16 Feb 2008 03:11:07 +0000

After a considerable hiatus since my last update (according to Subversion it’s been almost three months), I finally deployed a new release this morning. This update combines several smaller checkins, but includes some larger features including talking to NPC inhabitants and directional talk with avatars so you can now chat privately with other players nearby. This release also lays the the foundation for adding random encounters with monsters later on — which brings the game one step closer to combat.

Build 21 includes the following updates and fixes:

Updated navigation and screen flow, flash messages, and delete confirmations
Added random encounter maintenance for the world editor (monsters are still not showing up during play, but that’s next)
Refactored monster-related code to separate from inhabitants
Refactored avatar controller to move logic into avatar, inhabitant, and message models
Implemented click to view on map grid
Implemented talking to an inhabitant by choosing a direction when standing next to him/her/it (T + arrow key)
Implemented talking to another avatar by choosing a direction when standing next to him/her (T + arrow key) or by yelling (Y) so every avatar nearby can hear you
Prepopulating contact info in contact form if user is logged in
Linked blog post titles for better SEO
Changed title tag to put “GridWorlds” at the end (for better SEO)
Added unique meta description for each public page for SEO
Verified site via Google’s webmaster tools by adding empty verification file
Fixed double-message bug when entering a world on a sticky message
Fixed vertical spacing issues in blog styles
Fixed bug in inhabitant icon picker (was not showing correct icon groups)
Fixed inconsistent main navs in blog template
Set up missing macFFBgHack.png reference for Thickbox
Lots of other small changes and refactorings

Delete or delete? Removing things in Rails

Jason Gibb — Fri, 15 Feb 2008 12:00:02 +0000

Yesterday, while I was refactoring some code, I inadvertently confused myself about the various delete and destroy methods in Ruby and Rails. Between the two, there are over 20 different ways to remove objects, so I suppose I shouldn’t feel too bad I didn’t pick the right one. If you ever wanted to know the best way to make things go away in Rails, you’ve come to the right article.

Let’s start with an array of message objects, like this:

messages = Message.find(:all)

If I want to remove an element from this collection, it’s easy enough using the Ruby array.delete method. If I pass in an object and it matches one of the objects in the array, it is removed (or if the object doesn’t exist in the array, it just returns nil).

messages.delete(message)

Now let’s say I have a World model that has_many :messages, and I want to create a method to delete a message. My first thought is to use the same Ruby delete function:

class World < ActiveRecord::Base
    has_many :messages
    def remove_message(message_to_delete)
        messages = Message.find(:all)
        messages.delete(message_to_delete)
    end
end

The tricky part here is that message_to_delete is removed from the array in memory, but ActiveRecord knows nothing about it — message_to_delete is still sitting in the database, untouched. Then it occurred to me: because I set up a has_many relationship, my world instance already has a collection of messages just waiting for me, and ActiveRecord knows all about it! I don’t have to bother instantiating a collection of messages with the find method:

class World < ActiveRecord::Base
    has_many :messages
    def remove_message(message_to_delete)
        messages = Message.find(:all)
        messages.delete(message_to_delete)
    end
end

Rails Persistence Inconsistence

However, there’s another problem here, and it has to do with how Rails persists changes to collections managed by ActiveRecord. The message I want to delete is removed from memory, but Rails does not actually delete it from the database. Instead, Rails breaks the relationship between the message and the world by setting the world_id to null for that message. Here’s the SQL that Rails generates for the messages.delete call above:

UPDATE messages SET world_id = NULL WHERE (world_id = 1 AND id IN (1))

In other words, message_to_delete is not actually deleted, it is orphaned in the database. Far be it from me to question the wisdom of the Rails Gods^TM, but this seems like an odd choice. Preserving data integrity starts with managing foreign key relationships — and avoids leaving unattached data cluttering up my tables. If I delete something, it should be gone.

Realization Sets In

However, then I realized my real mistake: I was using Ruby’s array.delete rather than one of the handy methods provided by ActiveRecord::Base in Rails. There are several choices:

Class.delete(id)
Class.delete_all(conditions)
object.destroy
Class.destroy(id)
Class.destroy_all(conditions)

The ones that start with “Class” are all static class methods, so I might use them like this:

Message.delete(message_to_delete.id)
Message.delete_all(:conditions => ["world_id = ?", world.id])

What’s the difference between delete and destroy methods? The delete methods all send SQL delete statements directly to the database without instantiating any objects. The destroy methods first instantiate objects to trigger any callbacks and filters before the record is deleted. Of course, destroy is much less efficient than delete, but it lets you perform any cleanup operations on an object before it goes away forever.

Destruction is the answer

What have I learned? Since my message object has already been instantiated, the correct method is the instance destroy method. The finished product looks like this:

class World < ActiveRecord::Base
    has_many :messages
    def remove_message(message_to_delete)
        message_to_delete.destroy
    end
end

I hope this clarifies some of the ways that Rails handles the elimination of objects. Now that you have this knowledge, go forth and destroy.

Date and Time Calculations in Rails

Jason Gibb — Tue, 01 Jan 2008 19:21:58 +0000

Calculating dates and times has always been a challenge for programmers. How many days until the next New Years Eve party (oh, did you forget 2008 is a leap year)? How long ago was the last backup (convert that to GMT, please)? What day of the week is 19 days, 42 hours, and 374 minutes from now (and how many milliseconds is that again)? And don’t even get me started on Y2K!

Almost all programming languages or frameworks provide some facilities for date and time calculations, but they often amount to instantiating multiple date objects and calling obscure methods. Many inexperienced coders end up rolling their own, either out of ignorance or due to the sheer complexity of existing date/time libraries.

Get on Rails Time

Due to Ruby’s inherent “everything is an object” design, the ActiveSupport libraries in Rails makes date and time calculations, if not trivial, at least radically easier. Let’s take a look at some examples — you can follow along by firing up an irb console for your favorite Rails app, like so:

cd /path/to/your/favorite/rails/app
script/console

Now type this in the irb shell:

>> 15.minutes.ago

You should see something like this:

=> Tue Jan 01 12:17:51 -0600 2008

Very nice! “15.minutes.ago” is functionally equivalent to:

Time.now.advance(:minutes => -15)

But as you can see, the former is much easier to read than the latter.

Rails Time Calculations

Time calculations in Rails are just as easy. For example:

>> (19.days + 42.hours + 374.minutes).seconds.from_now
=> Tue Jan 22 13:02:06 -0600 2008

For convenience, Rails automatically converts everything to seconds, which means I can chain the seconds() and from_now() methods to get the exact date and time in the future.

Simple Time Zone Adjustments

Although time zone conversions are inherently nasty, Rails handles them as smoothly as possible. Say, for instance, I want to convert a time value into GMT. First, I would set up a new time_zone instance, like so:

>> time_zone = TimeZone.new(0)
=> #

This creates a time zone object with an offset of zero (in Casablanca, no less). Next, I would pass a time to the adjust() method on that time_zone:

>> time_zone.adjust(15.minutes.ago)
=> Tue Jan 01 18:51:16 -0600 2008

There you have it — date and time calculations, including time zone adjustments, that won’t give you a headache!

Working With Thickbox

Jason Gibb — Sun, 25 Nov 2007 20:26:50 +0000

I’ve recently had the pleasure of working with Thickbox, a lightbox implementation using the excellent jQuery JavaScript library. There are dozens of lightbox options available, so why did I choose Thickbox?

Simplicity, Thy Name is Thickbox

Thickbox is the slickest lightbox I have seen — it has a great user interface and it is trivially easy to set up. Here is some example code:

The first three lines pull in jQuery, the Thickbox library, and the Thickbox CSS. The last line is where the magic happens: the tag wrapping the image includes a reference to a “thickbox” class which will trigger the lightbox effect when clicked. That’s it! There’s nothing else to set up, although you can include an optional title attribute if you want a caption on the image.

Since it is built on top of jQuery (46K minified), the Thickbox code is extremely lightweight and fast loading (less than 5K minified). Browser compatibility is also excellent due to jQuery — supported browsers include IE 6 and 7, Firefox 2, Safari 2 and 3, and Opera 9.

It’s Flexible Too

Thickbox includes baked in support for all of the most common ways to use a lightbox-style dialog:

A single image
Multiple images in a gallery
HTML content within the page
HTML content from another page or site (as an iframe)
HTML content loaded dynamically via Ajax

I won’t bore you with the details of each one. Check out the documentation for examples.

Calling Thickbox via JavaScript

It is also possible to create a Thickbox dialog programmatically via JavaScript, but this technique is strangely undocumented. At first I thought this might not be easy to do, but after cracking open the Thickbox source code (the un-minified version, thank you very much), I immediately noticed this function:

tb_show(caption, url, imageGroup)

This makes it easy to trigger a Thickbox dialog in code or via an event by passing in a caption string and a URL. The optional imageGroup parameter can also be used to pass in an array of images for a single or multiple image slide show gallery.

The only tricky part is constructing a URL, which needs to include the frame size and any other attributes you might need. Say, for example, you want to display some HTML content in a 300×200 dialog, you might do something like this:

You can pass in any custom parameters in the URL string, as long as they are before the “TB_iframe” parameter.

Go Easy on the Lightbox

One final note: a lightweight, easy-to-implement user interface effect like Thickbox gives Web developers another tool in their toolbox of rich UI elements. But as much as I love cool Web effects like this one, there is always a danger that they will become overused. Thickbox is one of the best lightbox implementations I have seen, but remember to use it only when it makes sense.

How To Calculate Text Size in JavaScript

Jason Gibb — Fri, 19 Oct 2007 03:37:11 +0000

Here’s a JavaScript challenge: find the height and width of a string of text. Sounds easy, right? But there is more to this problem than meets the eye. Let’s say I have some text on the page:

How big is this text?

There is no way to get the size of the text itself, but I can get the size of an element wrapped around it. So let’s wrap the text in a span tag with an id:

How big is this text?

Okay, now I can use the clientHeight and clientWidth properties to find the size of the span, right?

var box = document.getElementById('howbig');
alert(box.clientWidth + ' x ' + box.clientHeight);

Let’s try it out:

How big is this text?

If you’re using Safari 2, you should see this:

However, with Firefox 2 and IE 7 you will see something like this:

Browser Inconsistencies

What’s going on here? Firefox and IE always set clientHeight and clientWidth to 0 for relatively positioned inline elements. This leaves me with three alternatives:

Use offsetHeight and offsetWidth properties instead of clientHeight and clientWidth.
Change my inline element (span) into a block-level element (div).
Switch my element to absolute positioning.

The first option will work fine; however, the offset properties include borders in their size, which may not always be desirable. Changing to a relatively-positioned div means the box will expand to fill any available horizontal space, like this:

How big is this text?

Instead of the width of the text, clientWidth is now giving me the width of the div (588px) in Firefox and Safari, and 0 in IE. That’s certainly not what I want! The third option, switch to absolute positioning, is the best alternative since it will work with both inline and block-level elements — plus the width of the element will always match the width of the text.

Playing Hide the Element

However, I still have a problem: I now have an absolutely positioned element floating on top of my other content. I could hide it by setting display to none, like this:

How big is this text?

Try this one out (the span is hidden, but the button will still test it):

How big is this text?

Now all three browsers are giving me problems:

Clearly I can’t hide the span with “display:none,” but there is another option: z-index. In Firefox a z-index of -1 will hide an element. The element will still be visible in Safari and IE, but it’s easy enough to position it behind another element on the page to conceal it (under a logo or content area, for example).

Putting It All Together

Here’s the final version, which includes absolute positioning and a z-index of -1:

How big is this text?

You won’t be able to see the span text “hidden” on this page, but click the button to try it out:

How big is this text?

How To Replace innerHTML with DOM methods

Jason Gibb — Wed, 10 Oct 2007 04:03:34 +0000

JavaScript’s innerHTML method is a handy way to grab or update text from any element within your HTML document. Here’s how it works:

// set the text
var welcome = document.getElementById("hello");
welcome.innerHTML = "Howdy!";

// get the text
alert(welcome.innerHTML); // displays "Howdy!"

It’s simple to use, works great in every modern browser, and even has good backward compatibility with older browsers. There’s just one little problem: innerHTML is not a W3C standard.

Enter the DOM

To maintain standards-compliance in your JavaScript code, you need to use Document Object Model (DOM) methods to access text nodes within your HTML document. Here are some of the attributes and methods you can use (for a complete list, check out the tutorial on the “How to Create” site):

parent.firstChild - returns the first element under the “parent” node
parent.hasChildNodes() - returns true if the “parent” node has any children
node.nodeValue - returns the value of the node (if it is a text node or attribute)
createTextNode(”the text”) - creates new text you can add to your document
appendChild(parent) - inserts a node into the DOM tree under a parent node
replaceChild(newNode, oldNode) - replaces the old node with new

Unfortunately, with all this talk of “nodes” and “DOM trees,” using these methods is not quite as straightforward as innerHTML. The key is to think of the text you want to manipulate as just another element within your HTML document. Using getElementById() and these methods, you can target and modify specific text elements within the page.

Get Text with DOM Methods

Let’s start with a simple example. Let’s say I have a

with some text somewhere on my page:

Hello World

If I want to grab that text and display it in an alert, I can do this:

Notice how I have to specify firstChild.nodeValue to get at the text? Unlike innerHTML, which indiscriminately grabs whatever is between

and

, these DOM methods don’t assume the content is always text (it could be other HTML elements, for example). The child element is considered just another node in the tree, which in this case happens to be text.

However, what if my

is empty? This presents a problems, because it means the node I’m looking for doesn’t actually exist! This example will error out because it can’t find the “firstChild” node:

The solution is to check whether your element has any children before accessing it:

if (welcome.hasChildNodes()) {
    alert(welcome.firstChild.nodeValue);
}

Update Text with DOM Methods

Okay, so I can get text from my HTML document, but how do I change it on the fly? Changing text is a two-part operation:

Create a new text node
Replace the current text node with the new text node

Here’s an example:

Hello World

Let’s step through it: First I start with a

containing my original “Hello World” text that I want to replace. Next I call createTextNode() with my new “Howdy!” message. At this point the text node is floating somewhere in DOM-space and I need to attach it to something, so I target the

using getElementById(). Finally, I call replaceChild() to swap the old text with the new text.

I can simplify this a little by merging the call to createTextNode() into the replaceChild() method, like so:

var welcome = document.getElementById("hello");
welcome.replaceChild(document.createTextNode("Howdy!"), welcome.firstChild);

Another Gotcha

Once again, empty nodes create problems. The replaceChild() method works just fine if the target element already contains text, but it will error out if the element is empty. We can solve this by adding the text node using appendChild() if it doesn’t exist. As before, hasChildNodes() comes to our rescue:

var welcome = document.getElementById("hello");
if (welcome.hasChildNodes()) {
    welcome.replaceChild(document.createTextNode("Howdy!"), welcome.firstChild);
} else {
    welcome.appendChild(document.createTextNode("Howdy!"));
}

In other words, if the

is not empty, replace the old text node with a new one, otherwise append a new text node.

I hope this gives you a little more insight into manipulating text in the DOM — without resorting to innerHTML.