Why Raphaël.js Exists
SVG is an XML-based language for describing objects and scenes, with built-in primitives such as circles and rectangles plus text support. While SVG itself isn't new, HTML5 removed a long-standing friction point: SVG objects can now be embedded directly in a page without wrapping them in <object> or <embed> tags, putting it on par with canvas. Raphaël.js is a JavaScript library that builds SVG scenes programmatically through a unified API. It transparently falls back to VML on Internet Explorer versions before IE9.
Primitives and Attributes
Creating a scene starts with instantiating a Raphaël object, either by inserting it into a specific HTML element with a given width and height or by letting Raphaël append it to the DOM. From there, primitive shapes are drawn by supplying coordinates and dimensions: a rectangle takes x, y, width, and height; a circle takes coordinates and a radius.
var paper = Raphael("sample-1", 200, 75);
var rect = paper.rect(10, 10, 50, 50);
var circle = paper.circle(110, 35, 25);
rect.attr({fill: "green"});
circle.attr({fill: "blue"});
Every SVG object accepts attributes covering color, rotation, stroke color, stroke size, and more. The full attribute list is in the Raphaël reference.
Paths for Custom Shapes
Paths are a series of instructions the renderer follows to create objects. Think of it like drawing with a pen on graph paper: you can lift the pen and move to a new position (move to), draw a line (line to), or draw a curve (arc to). Because paths are resolution-independent, SVG renders them with the same level of detail at any scale. When you issue a command like "draw a curve," SVG accounts for the original and final scaled size, computing intermediate points mathematically to produce a smooth curve.
var paper = Raphael("sample-2", 200, 100);
var rectPath = paper.path("M10,10L10,90L90,90L90,10Z");
var curvePath = paper.path("M110,10s55,25 40,80Z");
rectPath.attr({fill:"green"});
curvePath.attr({fill:"blue"});
Path commands are single letters followed by coordinates. M moves the pen, L draws a line from the current position, and s draws a smooth Bezier curve with a given control point and endpoint using relative coordinates. Z closes the path. Uppercase letters denote absolute coordinates; lowercase, relative. M/m and Z/z behave identically in either case. All path instructions are documented in the SVG specification.
Drawing Text as Objects
Raphaël offers two distinct text approaches. The text method takes x/y coordinates plus the string, but renders in the default font and size with little control over styling.
The print method instead renders text as a collection of paths, making individual glyphs editable. The example below colors the numeral 5 with an orange fill, gives "ROCKS" a bluish fill, and adds a thicker stroke to simulate bold—using a custom font at 40pt.
var paper = Raphael("sample-4", 600, 100);
var t = paper.text(50, 10, "HTML5ROCKS");
var letters = paper.print(50, 50, "HTML5ROCKS", paper.getFont("Vegur"), 40);
letters[4].attr({fill:"orange"});
for (var i = 5; i < letters.length; i++) {
letters[i].attr({fill: "#3D5C9D", "stroke-width": "2", stroke: "#3D5C9D"});
}
Raphaël ships with no fonts. Most fonts come as TrueType (TTF) or OpenType (OTF), so they must be converted with Cufon, which exports regular, bold, italic, and other font styles for use with Raphaël. The Google Font Directory is a solid source of freely licensed fonts.
Event Handling
SVG elements subscribe to the standard mouse events: click, dblclick, mousedown, mousemove, mouseout, mouseover, mouseup, and hover. Raphaël also lets you attach custom methods to the canvas or to individual elements, so nothing prevents adding gesture support for mobile browsers.
for (var i = 5; i < letters.length; i++) {
letters[i].attr({fill: "#3D5C9D", "stroke-width": "2", stroke: "#3D5C9D"});
letters[i].click(function(evt) {
this.rotate(45);
});
}
The snippet above binds a click handler that rotates one letter in "ROCKS" by 45 degrees.
SVG vs Canvas
The two drawing technologies take fundamentally different approaches. Canvas is an immediate-mode API; each stroke is a raster operation on a bitmap. You can clear or destroy parts of the drawing, but you can't revert or alter a previous stroke by default, and scaling causes pixelation.
SVG, by contrast, is retained and resolution-independent, and each object is scriptable. For games, the deciding factor is sprite count. SVG fits what could be called low-fidelity games: those with limited concurrent object movement, creation, and removal. Board games like Chess, Checkers, Battleship, and card games like BlackJack and Poker fit this description. A common thread is that players move arbitrary objects, and SVG's scriptability makes object picking straightforward.
Authoring Tools
Hand-authoring paths isn't required. Two tools stand out: Inkscape and svg-edit.
svg-edit
svg-edit is a browser-based SVG editor written in JavaScript. Its interface resembles GIMP or MS Paint and is best suited for tweaking existing SVG drawings rather than building complex art from scratch, though it supports both graphical creation and direct SVG code entry.
Inkscape
Inkscape is a cross-platform, full-featured vector graphics editor comparable to CorelDraw or Adobe Illustrator. It benefits from an active plugin ecosystem and a mature codebase dating back to 1999, when its predecessor was developed. Inkscape serves well for both vector and bitmap assets.
Legacy IE Support Note
Internet Explorer versions before IE9 don't support SVG on Windows. Instead, IE uses VML (Vector Markup Language), which offers much of the same functionality. Raphaël detects the environment and renders scenes using SVG or VML accordingly, providing cross-platform support through a single API.
