BlitzMouse Released + Demo

After working my butt-off on my latest game I decided it was time to redirect some love and attention to PixelBlitz. So this weekend I finished off a new class I had planned out a while ago. Introducing… BlitzMouse! This pairs up with BlitzKeyboard to complete the input set, and is a feature rich (and very fast) mouse handling system.

Here’s a very simple demo of it in action:

Press the cursor keys to limit custom mouse pointer movement.

So what can this bad boy do? The aim (as with all things PixelBlitz) is to make working with the mouse in your games easier. Here’s a quick overview of the core features:

Accurate mouse tracking

Keep an eye on that rodent! Easily check if it has left the stage, or re-entered again. Doesn’t use any CPU time processing events that require the mouse if it’s not over the stage!

Button / Click handling

Detect when the mouse button is down, or up.. or being held down. Find out how long it took the user to make that last mouse click (the speed from down to up again). Find out how many clicks the user has made since you last checked. Writing those god-awful “Ninja Finger” style games has never been so simple đŸ˜‰

Mouse stats

Want to know if the mouse is moving up? Just check isMovingUp! You can poll all 4 directions easily and quickly. Want to know how far in pixels the mouse has travelled on the X axis? Call distanceX() – want to know how fast it moved? Call speedX!


To know which angle the mouse is at call angle(), and you can have the result back in degrees or radians. Use the optional “lowerAccuracy” parameter and it uses a much faster calculation, but sacrifice a little accuracy in the process (great for a quick arcade game, not-so for a physics simulation).

You can set the point of the angle calculation (it defaults to the centre of your stage), which allows you to track the angle from anywhere to the mouse. You can even get the angle from any display object to the mouse using angleToObject() (with all the same parameters that angle() supports). This means if you want 3 things all pointing right at the mouse then it’s no problem! (see the demo above) Want to know the distance from any display object to the mouse? Call distanceToObject() and it’ll tell you.

Custom Mouse Pointers

Use changePointer() and you can set the mouse pointer to any display object – with custom X/Y offset support incase the pointer needs aligning differently to the standard top left. As the mouse moves, the display object is updated. If the mouse leaves the stage the display object is made invisible, so you don’t get that “cursor stuck on the edge” problem :)

Movement Limits

Want to limit the movement of the custom pointer? No problem! You can limit it in all four directions (up/down/left/right) with optional snapBack support on both axis. For example if you were making a Pong game (please… don’t) by just calling limitMovement(true, true, false, false) you will lock the bat into only moving up and down with left/right movements ignored.

Want to limit the mouse to a specific area of the stage? Call limit(new Rectangle(x,y,w,h)) – if the mouse goes outside of this zone it will be hidden from view. You can see this in the example above as it hides when it leaves the light grey box. This limit also effects custom pointers. Of course when the mouse leaves the stage there is nothing you can do about that – but we have to work within the limits of Flash here :)

So there we have it – BlitzMouse! Hopefully more useful than you thought when you first read the title, aye? :) I plan to add more features, such as custom events/function calls on mouse actions, the ability to attach as many display objects as you like to it (so they all update at once) and custom zones, so you can have as many “mouse zones” as you want. The code is uploaded to Google, so enjoy :)

Posted on September 15th 2008 at 12:55 am by .
View more posts in PixelBlitz. Follow responses via the RSS 2.0 feed.

6 Responses

Leave a comment
  • September 15th 2008 at 7:21 pm

    Very nice addition! Keep up the good work on the library. I like where it’s heading! Thanks!

  • sergej
    September 16th 2008 at 12:51 pm

    Very Thanks!
    concerning Custom Mouse Pointers and Movement Limits
    1. As pointer leaves specific area, custom cursor is hidden. Standard cursor or another custom cursor must be visible outside specific area.
    2. If I right click on stage, after that both custom and standard cursor are visible on specific area until refresh page.

  • September 16th 2008 at 2:18 pm

    1) Good idea! I have added a new parameter to limit() that lets you control this. You can now control if the custom OR the standard pointers should be hidden when they leave the area. This is now in svn if you want to test it. I’ve updated the SWF on this page to show it in action.

    2) This needs to be handled in your code really. As you pass a DisplayObject into BlitzMouse they don’t have access to the contextMenu, and I don’t want to force you into having to send in only a Sprite or MC. I will post a blog example now showing how to code a fix for it – it’s very simple :) Thanks for your feedback!

  • Okimoki
    January 10th 2009 at 6:56 pm

    This sounds great!!!! I would use it quite some, the only problem i have is.. ammm.. im kinda new to this.. and i cant get it to work..
    Could somebody please post few lines of code of how to set it up? I just want to get the speedX for example..
    I try something like this..

    var m:BlitzMouse = new BlitzMouse();

    What am i doing wrong?

  • January 10th 2009 at 7:30 pm

    Okimoki – You need to do 2 things. First, you need to link the mouse to a display object (typically the stage) like this:

    m.init(stage, true);

    Then you need to tell it to start listening for events with:


    You can start/stop the mouse whenever you want to save on CPU time when it isn’t required.

Make yourself heard