jax 0.0.0.9 → 0.0.0.10

data/guides/jax_guides/helpers.rb

@@ -1,29 +0,0 @@
-module JaxGuides
-  module Helpers
-    def guide(name, url, options = {}, &block)
-      link = content_tag(:a, :href => url) { name }
-      result = content_tag(:dt, link)
-
-      if options[:work_in_progress]
-        result << content_tag(:dd, 'Work in progress', :class => 'work-in-progress')
-      end
-
-      result << content_tag(:dd, capture(&block))
-      result
-    end
-
-    def author(name, nick, image = 'credits_pic_blank.gif', &block)
-      image = "images/#{image}"
-
-      result = content_tag(:img, nil, :src => image, :class => 'left pic', :alt => name)
-      result << content_tag(:h3, name)
-      result << content_tag(:p, capture(&block))
-      content_tag(:div, result, :class => 'clearfix', :id => nick)
-    end
-
-    def code(&block)
-      c = capture(&block)
-      content_tag(:code, c)
-    end
-  end
-end

data/guides/jax_guides/indexer.rb

@@ -1,69 +0,0 @@
-require 'active_support/core_ext/object/blank'
-require 'active_support/ordered_hash'
-require 'active_support/core_ext/string/inflections'
-
-module JaxGuides
-  class Indexer
-    attr_reader :body, :result, :warnings, :level_hash
-
-    def initialize(body, warnings)
-      @body     = body
-      @result   = @body.dup
-      @warnings = warnings
-    end
-
-    def index
-      @level_hash = process(body)
-    end
-
-    private
-
-    def process(string, current_level=3, counters=[1])
-      s = StringScanner.new(string)
-
-      level_hash = ActiveSupport::OrderedHash.new
-
-      while !s.eos?
-        re = %r{^h(\d)(?:\((#.*?)\))?\s*\.\s*(.*)$}
-        s.match?(re)
-        if matched = s.matched
-          matched =~ re
-          level, idx, title = $1.to_i, $2, $3.strip
-
-          if level < current_level
-            # This is needed. Go figure.
-            return level_hash
-          elsif level == current_level
-            index = counters.join(".")
-            idx ||= '#' + title_to_idx(title)
-
-            raise "Parsing Fail" unless @result.sub!(matched, "h#{level}(#{idx}). #{index} #{title}")
-
-            key = {
-              :title => title,
-              :id => idx
-            }
-            # Recurse
-            counters << 1
-            level_hash[key] = process(s.post_match, current_level + 1, counters)
-            counters.pop
-
-            # Increment the current level
-            last = counters.pop
-            counters << last + 1
-          end
-        end
-        s.getch
-      end
-      level_hash
-    end
-
-    def title_to_idx(title)
-      idx = title.strip.parameterize.sub(/^\d+/, '')
-      if warnings && idx.blank?
-        puts "BLANK ID: please put an explicit ID for section #{title}, as in h5(#my-id)"
-      end
-      idx
-    end
-  end
-end

data/guides/jax_guides/levenshtein.rb

@@ -1,31 +0,0 @@
-module JaxGuides
-  module Levenshtein
-    # Based on the pseudocode in http://en.wikipedia.org/wiki/Levenshtein_distance.
-    def self.distance(s1, s2)
-      s = s1.unpack('U*')
-      t = s2.unpack('U*')
-      m = s.length
-      n = t.length
-
-      # matrix initialization
-      d = []
-      0.upto(m) { |i| d << [i] }
-      0.upto(n) { |j| d[0][j] = j }
-
-      # distance computation
-      1.upto(m) do |i|
-        1.upto(n) do |j|
-          cost = s[i] == t[j] ? 0 : 1
-          d[i][j] = [
-            d[i-1][j] + 1,      # deletion
-            d[i][j-1] + 1,      # insertion
-            d[i-1][j-1] + cost, # substitution
-          ].min
-        end
-      end
-
-      # all done
-      return d[m][n]
-    end
-  end
-end

data/guides/jax_guides/textile_extensions.rb

@@ -1,61 +0,0 @@
-#require 'active_support/core_ext/object/inclusion'
-#   above file isn't in release yet, so we'll re-code it here -- it's only 1 method
-class Object
-  # Returns true if this object is included in the argument. Argument must be
-  # any object which responds to +#include?+. Usage:
-  #
-  #   characters = ["Konata", "Kagami", "Tsukasa"]
-  #   "Konata".in?(characters) # => true
-  #
-  # This will throw an ArgumentError if the argument doesn't respond
-  # to +#include?+.
-  def in?(another_object)
-    another_object.include?(self)
-  rescue NoMethodError
-    raise ArgumentError.new("The parameter passed to #in? must respond to #include?")
-  end
-end
-
-require File.join(File.dirname(__FILE__), 'common')
-
-module JaxGuides
-  module TextileExtensions
-    def notestuff(body)
-      body.gsub!(/^(IMPORTANT|CAUTION|WARNING|NOTE|INFO)[.:](.*)$/) do |m|
-        css_class = $1.downcase
-        css_class = 'warning' if css_class.in?(['caution', 'important'])
-
-        result = "<div class='#{css_class}'><p>"
-        result << $2.strip
-        result << '</p></div>'
-        result
-      end
-    end
-
-    def tip(body)
-      body.gsub!(/^TIP[.:](.*)$/) do |m|
-        result = "<div class='info'><p>"
-        result << $1.strip
-        result << '</p></div>'
-        result
-      end
-    end
-
-    def plusplus(body)
-      body.gsub!(/\+(.*?)\+/) do |m|
-        "<notextile><tt>#{$1}</tt></notextile>"
-      end
-
-      # The real plus sign
-      body.gsub!('<plus>', '+')
-    end
-
-    def code(body)
-      body.gsub!(%r{<(#{JaxGuides.code_aliases})>(.*?)</\1>}m) do |m|
-        es = ERB::Util.h($2)
-        css_class = $1.in?(['erb', 'shell']) ? 'html' : $1
-        %{<notextile><div class="code_container"><code class="#{css_class}">#{es}</code></div></notextile>}
-      end
-    end
-  end
-end

data/guides/partials/_top_nav.html.erb

@@ -1,17 +0,0 @@
-<div id="topNav">
-  <div class="wrapper">
-    <strong>More at <a href="http://jaxgl.com">jaxgl.com:</a> </strong>
-    <a href="http://blog.jaxgl.com/what-is-jax">Overview</a> |
-    <%if @link_to_guides%>
-      <a href="http://guides.jaxgl.com">Guides</a> |
-    <%end%>
-    <!-- <a href="http://jaxgl.com/download">Download</a> | -->
-    <!-- <a href="http://jaxgl.com/deploy">Deploy</a> | -->
-    <a href="http://github.com/sinisterchipmunk/jax">Code</a> |
-    <%if !@hide_links_to_api_docs%>
-      <a href="http://guides.jaxgl.com/api/js/index.html">Documentation</a> |
-    <%end%>
-    <a href="http://blog.jaxgl.com/forum">Forums</a> |
-    <a href="http://blog.jaxgl.com/">Blog</a>
-  </div>
-</div>

data/guides/source/getting_started.textile

@@ -1,1210 +0,0 @@
-h2. Getting Started with Jax
-
-This guide will show you how to start developing WebGL applications using Jax. It covers the following topics:
-
-* Installing Jax and creating a new Jax application
-* The layout of a Jax application
-* The MVC (Model, View, Controller) architecture and how it applies to Jax
-* How to quickly generate the starting pieces of a Jax application
-  
-endprologue.
-
-NOTE: Paths in this guide are relative to a Jax application unless otherwise specified.
-
-h3. Assumptions
-
-This guide is designed for beginners who want to get started on Jax applications from scratch. It does not assume you have any prior experience with Jax, but it does assume you are a JavaScript developer. Jax is a framework written largely in JavaScript, and without an understanding of basic JavaScript principles, you will be facing a steep learning curve.
-
-The guide also assumes you have the following software installed:
-
-* The "Ruby":http://ruby-lang.org language.
-* The "RubyGems":http://rubyforge.org/frs/?group_id=126 packaging system.
-
-h3. What is Jax?
-
-Jax is a development framework for JavaScript-driven WebGL applications. It is designed to make WebGL application development easier by making assumptions about what every WebGL application must be capable of. For instance, every WebGL application must manage one or more WebGL Contexts. Jax completely automates this task.
-
-Jax has been heavily influenced by the popular Ruby on Rails web application framework, and borrows most of its key philosophies from Rails. These concepts include the following:
-
-* Opinionation. Like Rails, Jax is opinionated software, which means that it makes an assumption that there is a "best" way to do things. If you embrace the approaches that Jax makes, you will likely discover that you can write WebGL applications in a fraction of the time it took without Jax.
-* DRY -- "Don't Repeat Yourself" -- means that constantly repeating the same code is a Bad Thing, and Jax makes every effort to remove the need to do this. JavaScript is itself a not-very-DRY language, (count the number of times you see the word "function"!), so there's a limit to how DRY a Jax application can be. That doesn't stop Jax from trying, however.
-* Convention Over Configuration -- means that Jax is going to make a lot of assumptions about what you want to do and how you want to do it. Jax won't stop you from manual configuration, but it provides a lot of defaults to try and guess what you want before you get that far.
-  
-In addition to these points, Jax makes the assumption that smaller files are easier to maintain. JavaScript code tends to quickly grow very large and unwieldy, and it doesn't take long for it to become so convoluted that even its original authors have trouble maintaining it. Jax resolves this problem by splitting what would be a few monolithic source files into many smaller, more specialized files, and places these files into categories according to their function.
-
-h4. The MVC Architecture
-
-At the heart of Jax is the Model, View, Controller (usually just called MVC) architecture. This cleanly organizes the code base into three distinct regions, making it (usually) plainly obvious where a particular code change should take place and making the entire application far easier to maintain.
-
-h5. Models
-
-Models represent containers for data and the rules governing how that data is to be manipulated. In Jax, once it is determined that an action should take place, it is up to the model to actually perform the action. If, for instance, a "Monster" is expected to take damage from an attack, it is up to the "Monster" model to modify the appropriate data, perhaps begin an appropriate animation sequence, and do anything else related to taking damage.
-
-The bulk of your application's business logic will be concentrated in the models.
-
-h5. Views
-
-Views are a presentation layer; they do not manipulate data, handle user input, or contain any other non-presentation logic. In the case of Jax, views are used to render the current scene and are rarely any different from one another. A view could be changed, for instance, to add motion blur or other visual effects to the scene.
-
-h5. Controllers
-
-Controllers are the managers of your application. They tell models what to do and when to do it; in Jax, they are responsible for setting up the scene and tearing it down. They also handle all forms of user input, and can even be called automatically over time.
-
-h3. Creating a New Jax Project
-
-This guide will walk you through creating a sample application from scratch. The application will create a 3D "dungeon" that the player can move around in. It will be a first-person application, rendered as if through the eyes of the player's character.
-
-Here's a screenshot of the finished dungeon scene:
-
-!images/getting_started/dungeon-complete.png(The Dungeon)!
-
-
-h4. Installing Jax
-
-The first step to creating any Jax application is to make sure Jax itself is installed. Assuming you have already set up its primary dependencies, "Ruby":http://www.ruby-lang.org and "RubyGems":http://rubyforge.org/frs/?group_id=126, this should be as simple as running the following command:
-
-<shell>
-Usually, run this as the root user:
-# gem install jax
-</shell>
-
-This will install Jax and a number of other Ruby Gems that it relies upon.
-
-h4. Creating the Dungeon Application
-
-Now that Jax is installed, we can go ahead and generate the Dungeon application. Start a terminal or command prompt, switch to a directory you have permission to write to, and enter the following command:
-
-<shell>
-$ jax new dungeon
-</shell>
-
-This will create a Jax application called Dungeon in the +dungeon+ directory. You'll want to change into that directory for the remainder of this guide:
-
-<shell>
-$ cd dungeon
-</shell>
-
-The files that Jax has created, and descriptions of what they are for, are given below:
-
-| File/Folder | Purpose |
-| Gemfile     | Specifies the gems your Jax application depends on. |
-| Rakefile    | Contains batch programs that can be run from a terminal with the +rake+ command. |
-| app/        | Contains the majority of your application code, including controllers, models, views, and so forth. |
-| config/     | Contains general application configuration options which control how Jax functions behind the scenes. |
-| public/     | Contains static assets that your application depends on, such as stylesheets, images, 3D models, and so on. Also contains the Jax core javascripts. |
-| script/     | Contains the jax script that starts your application and invokes code generators. You can also place custom scripts here. |
-| spec/       | Contains test files, or _specs_, used to test your Jax application. |
-| tmp/        | Contains temporary files. These files are generated by Jax when building or testing your application, and will be frequently overwritten. |
-
-h4. Installing the Required Gems
-
-Jax applications manage their gem dependencies using "Bundler":http://gembundler.com. Since our application doesn't
-require any dependencies other than Jax itself, we can go ahead and lock in place the version of Jax we intend to use
-by running:
-
-<shell>
-$ bundle install
-</shell>
-
-h3. Jax Lives!
-
-The next thing we need to do is start the Jax application server. Do that with the following command:
-
-<shell>
-$ rake jasmine
-</shell>
-
-_Jasmine_ is the name of the test suite which will be used to run your JavaScript unit tests. You can learn more about Jasmine by "visiting its home on GitHub":https://github.com/pivotal/jasmine-gem.
-
-h4. The Development Environment
-
-In Jax, Jasmine doubles as both the test suite and the development environment. Jax alters the Jasmine run template to include an HTML5 canvas element and the necessary JavaScript code to create a Jax context, so every time you refresh the browser, you'll both run the Jasmine test suite and see your Jax application in action.
-
-Open a browser and point it to the Jasmine suite, "http://localhost:8888":http://localhost:8888, and you will see a white Canvas and some passing (green) unit tests.
-
-!images/getting_started/clean_passing_jasmine_suite.png(The Default Jasmine Suite)!
-
-Let's take a moment to explain what you're seeing. At the top-left, the Jasmine and Jax versions are shown. "Jasmine" is a link to the Jasmine homepage, where you can find more documentation. Below these headers is a green element displaying the number of specs (tests), how many failures were encountered, and how long it took to execute. To the right of this same element is a link that you can click to re-run the test suite, and above that are some checkboxes you can use to change what Jasmine is showing you.
-
-When tests fail, they take up a large chunk of the screen. The idea is that you should never have failing specs, unless you're in the middle of making them pass. If the specs are passing, then they'll take up a minimum of real estate on the screen and leave room for the Jax context, where you can _see_ your code in action.
-
-By default, the Jax development environment is purposely kept very simple. You can customize the HTML elements by altering the file +spec/javascripts/support/spec_layout.html.erb+, if your Jax application expects certain additional HTML elements to exist.
-
-TIP. You should almost never have to restart the Jasmine server. Every time you reload the test suite, Jax rebuilds your application, so the resulting JavaScript file is always up-to-date.
-
-h4. Tea Time
-
-One of the most common tests you'll find in graphics programming is rendering the obligatory Teapot. Many frameworks have the Utah Teapot built into them, and Jax is no exception. (If you want, you can also read some interesting information on the "origin of the Utah Teapot":http://en.wikipedia.org/wiki/Utah_teapot back in 1975.)
-
-h5. Generating the Controller
-
-So let's get started on this graphical "Hello, World". First, we need to generate a controller, which will be responsible for setting up the teapot scene. By convention, we'll name the controller after the type of scene it represents:
-
-<shell>
-$ jax generate controller teapot index
-</shell>
-
-Notice we added an extra argument: +index+. Controllers consist of JavaScript functions called _actions_, and this extra argument tells Jax to create an action in our Teapot controller called +index+. Actions are used by controllers to accomplish a given task. By convention, the +index+ action will be used to set up a scene for the first time. In this case, it will be responsible for creating a Teapot and positioning it within the scene.
-
-h5. Setting the Default Route
-
-When you generated the Teapot controller, you may have noticed that Jax inserted a line into the +config/routes.rb+ file. The line it inserted will register the controller with Jax so that it knows how to find the controller when it is needed. However, it doesn't actually tell Jax _when_ the controller is needed. Instead of doing this manually, we'd prefer Jax to start at the Teapot controller by default. Therefore, we need to edit the +config/routes.rb+ file and add a _root_. Add the following to the second line of this file:
-
-<ruby>
-root 'teapot'
-</ruby>
-
-Your +config/routes.rb+ file, with the automatically-generated comments omitted, should now look like this:
-
-<ruby>
-Dungeon.routes.map do
-  root 'teapot'
-  map 'teapot/index'
-end
-</ruby>
-
-h5. Adding the Teapot
-
-Refreshing your development page, you should see the Jax canvas turn from white to black. This means that Jax is now invoking your controller, and is causing WebGL to render to the canvas. Unfortunately, there's nothing to render because your controller hasn't yet set up the scene, so the result is just a black image.
-
-In order to add some color, you need to edit your +app/controllers/teapot_controller.js+ file. Inside of the +index+ function, add the following JavaScript code:
-
-<js>
-var teapot = new Jax.Model({
-  position: [0, 0, -5],
-  mesh: new Jax.Mesh.Teapot()
-});
-this.world.addObject(teapot);
-</js>
-
-By default, Jax positions the camera at the origin at (0, 0, 0), looking along the negative Z axis. (This is in line with OpenGL and, more importantly, WebGL standards.)
-
-Therefore, the above code will create a new Teapot object, position it 5 units in "front" of the camera, and add it to the scene (which Jax calls +world+).
-
-Reload your suite again, and you'll see the fruits of your labor!
-
-!images/getting_started/teapot-white.png(The Default Teapot)!
-
-h5. Using Materials for Color
-
-We have a teapot, but we don't have a very _impressive_ teapot. In fact, it looks rather flat, uninspiring and _white_.
-Let's change that. In a terminal, run the following command within your Jax application:
-
-<shell>
-$ jax generate material teapot
-</shell>
-
-This will generate a Jax material. By default, Jax will also add in support for scene lighting.
-
-TIP: This guide won't cover Jax materials in depth, but they're very powerful and very versatile. For more information regarding Jax materials, see the "Jax Material Guide":materials.html.
-
-Edit the newly-generated material file, +app/resources/material/teapot.yml+. Under +ambient+ coloring, change the +green+ and +blue+ values to 0.0, and leave the +red+ and +alpha+ values at 1.0.
-
-<yaml>
-ambient:
-  red: 1.0
-  green: 0.0
-  blue: 0.0
-  alpha: 1.0
-</yaml>
-
-Again, edit the +app/controllers/teapot_controller.js+ file and alter this line:
-
-<js>
-  mesh: new Jax.Mesh.Teapot()
-</js>
-
-Replace it with the following:
-
-<js>
-  mesh: new Jax.Mesh.Teapot({ material: Material.find("teapot") })
-</js>
-
-This will produce a completely opaque, red teapot. It looks depressingly two-dimensional because it's composed entirely of a single color. Next, we'll make it look more like the 3D object it really is!
-
-<img src="images/getting_started/teapot-red-nolight.png" style="width:300px;height:200px;float:left;margin-right:2em;"/>
-<img src="images/getting_started/teapot-red-spot-point-directional.png" style="width:300px;height:200px;clear:right;"/>
-
-h4. Using Light Sources
-
-To add a more realistic shading effect to the teapot, we'll need to add some light sources. Jax supports three kinds of lights:
-
-* Directional
-* Point
-* Spot
-
-TIP: Lighting support requires a fair number of shader variables. Nearly all video cards on the market should support it, but it _does_ exceed the theoretical lowest potential limit on shader variables. Jax will automatically drop lighting support if it can't be used, and render the scene without it. If, after completing this section, your model still looks "flat", try viewing it on a different machine.
-
-h5. Directional Lights
-
-Directional lights have no point of origin. They shine in the same direction upon every object in the scene. In the real world, they don't exist, but in the virtual world, they are useful for simulating very powerful, distant entities such as the sun.
-
-Let's start simple by adding a directional light to our scene. First, from the command line, use the light source generator:
-
-<shell>
-$ jax generate light sun directional
-</shell>
-
-Next, we need the controller to add it to the scene. Edit your controller file at +app/controllers/teapot_controller.js+ and add the following line to the +index+ action:
-
-<js>
-index: function() {
-  // ...
-  this.world.addLightSource(LightSource.find("sun"));
-}
-</js>
-
-Now edit the file the generator created, +app/resources/light_sources/sun.yml+, and change the +direction+ field to look like this:
-
-<yaml>
-direction:
-  x: -1
-  y: -1
-  z:  1
-</yaml>
-
-This tells the light to shine left, down, and backward relative to world space.
-
-INFO: Remember that, currently, our camera is unmodified, so world space and camera space are the same thing. When we get around to rotating the camera, the difference between camera and world space will become more important. For more information about the various spaces and the differences between them, take a look at the "Matrices Guide":matrices.html.
-
-Reload your scene, and you should finally be starting to see some detail!
-
-!images/getting_started/teapot-red-directional.png(Teapot With Directional Light)!
-
-
-h5. Point Lights
-
-These are omnidirectional lights that have an origin at a specific point in world space. They shine in all directions from their position, and every object (indeed, every pixel) is lit at a different angle. In the real world, this is technically the only kind of light.
-
-Point lights are useful for simulating relatively small light sources like candles. Let's add one now. Once again, run the light source generator:
-
-<shell>
-$ jax generate light candle point
-</shell>
-
-Again, add the light source to the scene from the controller +app/controllers/teapot_controller.js+:
-
-<js>
-index: function() {
-  // ...
-  this.world.addLightSource(LightSource.find("candle"));
-}
-</js>
-
-And again, edit the generated file, +app/resources/light_sources/candle.yml+, and change the +position+ field to look like this:
-
-<yaml>
-position:
-  x: -1.2
-  y: -1.2
-  z: -4.0
-</yaml>
-
-This will position the candle very close to the teapot indeed -- just barely to the left, bottom, and front of it.
-
-In the same file, let's alter the color of the light itself. Candles are often a reddish-yellow color, so let's make ours the same:
-
-<yaml>
-color:
-  ambient:
-    red: 0.6
-    green: 0.6
-    blue: 0.0
-    alpha: 1.0
-
-  diffuse:
-    red: 1.0
-    green: 1.0
-    blue: 0.0
-    alpha: 1.0
-
-  specular:
-    red: 0.2
-    green: 0.2
-    blue: 0.0
-    alpha: 1.0
-</yaml>
-
-Reload the scene again and you should see your candle's effect upon the teapot.
-
-!images/getting_started/teapot-red-directional-point.png(Teapot With Directional and Point Lights)!
-
-
-h5. Spot Lights
-
-These are just like point lights, except they have a cutoff angle. In the real world, they're analogous to flashlights in that their lit area is cone-shaped and has a specific direction. They are useful for simulating flashlights, automobile headlights, and so on.
-
-We'll use the spot light to simulate a searchlight.
-
-Generate the spot light in the same manner as the last two:
-
-<shell>
-$ jax generate light searchlight spot
-</shell>
-
-Like the others, add this light to the scene in +app/controllers/teapot_controller.js+:
-
-<js>
-index: function() {
-  // ...
-  this.world.addLightSource(LightSource.find("searchlight"));
-}
-</js>
-
-This time, we'll alter the position and direction to shine toward, but not directly upon, the teapot; we'll also alter the color, the angle of the spotlight (that is, the width of the cone), and the spot exponent, which represents how fast light fades out from the center of the cone. With a spot exponent of zero, the spotlight's cone should be quite clearly defined.
-
-The file to edit is +app/resources/light_sources/searchlight.yml+:
-
-<yaml>
-position:
-  x: 0
-  y: 0
-  z: -3.25
-
-direction:
-  x: 0.05
-  y: -0.025
-  z: -1
-
-type: SPOT_LIGHT
-
-# the cone is approx. 20 degrees wide, in radians
-angle: 0.349
-
-# this light has fairly sharp edges.
-spot_exponent: 8
-
-attenuation:
-  constant: 1.0
-  linear: 0
-  quadratic: 0
-
-color:
-  ambient:
-    red: 0
-    green: 0
-    blue: 0.4
-    alpha: 1
-
-  diffuse:
-    red: 0
-    green: 0
-    blue: 1.0
-    alpha: 1.0
-
-  specular:
-    red: 0
-    green: 1
-    blue: 0
-    alpha: 1.0
-</yaml>
-
-Once again, you're ready to reload the scene. Note how the spotlight is bright in the center, but begins to fade a little bit toward the edges. The amount of fading is controlled with the +spot_exponent+ setting. In general, a higher number will produce a spotlight that fades more quickly, while a lower number will produce sharper edges. A spotlight with a spot exponent of 0 will have extremely sharp edges.
-
-Take some time to alter the various lighting settings, above, and note the differences in the results.
-
-WARNING: Jax supports an arbitrary number of light sources; that is, there's no hard limit on how many lights you can have in your scene. However, be aware that the scene must be rendered once <em>for each light source</em>, so you can expect to take a significant performance hit by simply tossing lights around without carefully considering the implications. Always keep in mind the quality of the hardware you're targeting; the more light sources you activate, the lower the framerate on your clients' systems.
-
-!images/getting_started/teapot-red-spot-point-directional.png(Teapot With Directional, Spot and Point Lights)!
-
-
-h4. Making the Most of Models
-
-So far, we've only made use of the controller and the view. (We've only actually altered the controller, because the view that Jax generates is fine for most applications.)
-
-Now we'd like to add some lower-level business logic to our application. In particular, we'll make the teapot rotate in
-place. This sort of logic is exactly what models are designed to encapsulate.
-
-So far, we've been using a model created on-the-fly with the following code:
-
-<js>
-var teapot = new Jax.Model({
-  position: [0, 0, -5],
-  mesh: new Jax.Mesh.Teapot({
-    material: Material.find("teapot")
-  })
-});
-</js>
-
-There's nothing wrong with doing this as long as you don't need any logic beyond what Jax.Model gives you. However,
-the code to cause the model to rotate is very much model-specific behavior. It would be bad form to define this within
-the controller, even if we're defining it on the model. (Note that this is very much possible -- it's just bad practice.)
-
-h5. Generating the Model
-
-Instead, let's generate an appropriate Teapot model from the terminal:
-
-<shell>
-$ jax generate model teapot
-</shell>
-
-This will generate a model file at +app/models/teapot.js+ as well as a <em>default resource</em> at +app/resources/teapots/default.yml+.
-
-h5. Resources
-
-Models in Jax actually result from the combination of two files: first is the model source code, the JavaScript file which determines the rules governing how the model can be used; second is the resource file, which specifies the raw data behind a given model.
-
-A good way to think of resources is as database entries, even though they actually occupy a file on the file system. While the model itself may represent a database table, the resource files each describe exactly one record within that table.
-
-When a model is first generated, Jax also generates a <em>default resource</em>. The default resource is loaded for <em>each and every resource</em>, and specifies <em>default values</em> for the various fields. This allows the individual resource files to completely omit certain attributes, instead allowing the <em>default resource</em> to specify what those attributes should default to.
-
-In the case of our teapot, we're going to set a default size and speed of rotation for all Teapot models to use. First, edit the resource file. You'll see that, save for a few comments, it's completely empty. Add the following:
-
-<yaml>
-size: 1.0
-rotation_speed: 1.0 # in radians per second
-</yaml>
-
-Now, create a new file alongside +app/resources/teapot/default.yml+ called +app/resources/teapot/actual.yml+. Inside that file, we'll specify the position of the teapot we plan to use:
-
-<yaml>
-position:
-  x: 0
-  y: 0
-  z: -5
-</yaml>
-
-You'll notice that we've specified the exact same position that the current teapot already occupies.
-
-h5. Model Source
-
-Now that we have some attributes to deal with, we need to add a little bit of logic to the model source in +app/models/teapot.js+. Open that file up and add the following code to the +after_initialize+ function:
-
-<js>
-this.mesh = new Jax.Mesh.Teapot({
-  size: this.size,
-  material: Material.find("teapot")
-});
-</js>
-
-The above code will pass the teapot's +size+ attribute into its mesh.
-
-TIP: The mesh is used for rendering -- we'll discuss it in detail later on. For now, just understand that without a Mesh, a model technically _exists_, but it is invisible. The Mesh is the actual 3D data used by WebGL to draw the object, in this case a teapot.
-
-NOTE: Notice that we didn't do anything with the +position+ attribute, which we created in +app/resources/teapot/actual.yml+. This is because Jax is smart enough to use basic attributes such as +position+ and +direction+ to orient the model without the need for us to explicitly get involved. If we _did_ want to deal with the +position+ attribute directly, we'd have to be careful about it because it is only specified on an _instance_ of the model; the <em>default resource</em> doesn't include the +position+ attribute, so it's quite possible to create a teapot that has no +position+. (In that case, Jax would place it at the origin.)
-
-h5. Using the Model
-
-We've now done all the setup necessary to expose our new model to Jax. The only thing left is to _use_ it. Edit your controller, +app/controllers/teapot_controller.js+, and replace the following code:
-
-<js>
-var teapot = new Jax.Model({
-  position: [0, 0, -5],
-  mesh: new Jax.Mesh.Teapot({
-    material: Material.find("teapot")
-  })
-});
-this.world.addObject(teapot);
-</js>
-
-with:
-
-<js>
-this.world.addObject(Teapot.find("actual"));
-</js>
-
-Now, when you reload your Jax suite, you should see exactly the same image as before -- except that now, the teapot is being loaded from a resource file instead of being created on-the-fly.
-
-In addition to being more organized, less confusing and easier to maintain, this gives you a strong foundation upon which to build more complicated model-specific logic. Perfect, because that's what we're going to do next.
-
-IMPORTANT: When you call +Teapot.find+, Jax is actually <em>creating a new instance</em> of the resource. That means, if you call +Teapot.find+ twice with the same name, you'll get two completely separate instances of the same model! This is quite powerful for creating many instances of a model that are all expected to look and act similarly, such as generic monsters, but can be confusing if you assume that +Teapot.find+ will return a single instance more than once.
-
-h5. Adding Model Logic
-
-Once again, edit the +app/models/teapot.js+ model source file. Following the +after_initialize+ method, add a new one called +update+. It takes a single +timechange+ argument. Don't forget to put a comma after the closing curly-brace for +after_initialize+, or you'll have a JavaScript syntax error! Here's what your entire model file should now look like:
-
-<js>
-/**
- * class Teapot < Jax.Model
- *
- **/
-var Teapot = (function() {
-  return Jax.Model.create({
-    after_initialize: function() {
-      this.mesh = new Jax.Mesh.Teapot({
-        size: this.size,
-        material: Material.find("teapot")
-      });
-    },
-
-    update: function(timechange) {
-      // we're going to add more code here!
-    }
-  });
-})();
-</js>
-
-As the comment in the model file indicates, we're going to insert some code into the +update+ function. But first, let's talk about that function.
-
-+update+ is a special function made available to all models _and_ all controllers. If Jax detects that such a method exists, it will call the +update+ method every few milliseconds. The +timechange+ argument is the amount of time, in seconds, since the last time +update+ was called.
-
-NOTE: The +timechange+ argument is crucial because you can use it to track changes over time. For instance, when we calculate an object's rotation, we'll multiply the total amount of rotation by +timechange+. If you don't do this, the code will still work, but it will run faster on some computers than it will on others (dependent upon framerate). By multiplying against time elapsed, you control the speed of rotation so that it is the same on all devices, regardless of the relative speed of the device.
-
-Add the following code to the +update+ method to cause the teapot to rotate at the speed specified in its resource file:
-
-<js>
-var rotation_axis = [0, 1, 0];
-this.camera.rotate(this.rotation_speed * timechange, rotation_axis);
-</js>
-
-This will cause the teapot to rotate about the Y axis at a speed of +rotation_speed+ radians per second. Because the speed was specified in the resource files, you now have enough code in place to actually create several different teapots rotating at different speeds! Just add resource files for each teapot you intend to use; remember to set the individual teapots up in the +teapot_controller.js+ file, and you're all set!
-
-h3. Handling Input
-
-Nearly every application is going to have to deal with user input at one time or another. If it doesn't, it can never become more than yet another WebGL demo with a rotating globe.
-
-Since we're working toward creating a dungeon in which the user can freely navigate, it would be a good idea to go ahead and add those navigational controls now. We already have a point of reference -- the rotating teapot -- but our scene has not gotten too complex yet, so this is a perfect time to think about camera controls.
-
-User input is meant to be handled entirely within the controller, so edit +app/controllers/teapot_controller.js+. We'll be focusing on the controller pretty explicitly for awhile.
-
-h4. Mouse Events
-
-For this guide, we're going to allow the user to _rotate_ the camera in-place (as if turning their head) only when the mouse is _dragged_. Jax actually supports virtually every possible mouse event, and they are all handled identically to what we're about to do.
-
-NOTE: Most first-person applications track whether the mouse was _moved_ instead of just when it was _dragged_, but this is a bit of a sticking point with WebGL. The HTML5 standard provides no way to capture mouse input once the mouse itself is blocked from movement; that is, if you move the mouse to the left-hand side of the screen and continue to move it leftward, there will be no way to tell when you are attempting to move it past the edge of the screen. Similarly, there is no way under the current standard to reposition the mouse toward the center of the screen; this would pose too many security issues. Therefore, traditional "mouse-look" is not currently possible because mouse events will suddenly stop firing when the mouse becomes blocked by the screen dimensions. A cheap and cumbersome, but theoretically workable, solution is to listen to mouse _drag_ events instead of mouse _move_ events. This forces the user to move the mouse back to its origin before dragging again, thus not breaking the application. (This issue alone is probably going to pose significant design frustrations for WebGL-based first-person application developers.)
-
-In your controller, define a new action called +mouse_dragged+. It takes a single +event+ argument:
-
-<js>
-mouse_dragged: function(event) {
-  this.player.camera.rotate(0.01, [event.diffy, -event.diffx, 0]);
-  this.player.camera.orient(this.player.camera.getViewVector(), [0,1,0]);
-}
-</js>
-
-This simply rotates 0.01 radians for every pixel the mouse is moved. The reason we use the mouse Y axis for the rotation X axis and vice versa, is because we are specifying the axis to rotate _about_. In 3D, rotating about the Y axis results in camera movement along the X axis (looking "left" or "right"). Conversely, rotating about the X axis results in movement along the Y axis (looking "up" or "down").
-
-A good way to remember the difference is to hold your hands out in front of you, as if holding a ball. (Hold a real ball, if you have one handy!) Rotate the "ball" left and right; which axis are you pivoting on? It's the up/down axis that holds still, so it's the up/down (Y) axis that you're actually rotating _about_.
-
-Rotating about the Z axis is to rotate about a line drawn straight out in front of you, and results in a "tilt" clockwise or counter-clockwise.
-
-If you reload your test suite, you'll now see that you can drag the mouse to cause the appropriate rotation.
-
-The last line in the mouse_dragged function may be a bit confusing. The most effective way to see what it does is to simply comment that last line out, reload your test suite, and see how the camera functions. You'll notice that first of all, you can rotate the camera into a completely upside-down state; not ideal for a first-person application, but quite appropriate for a flight simulator.
-
-The second thing you may notice with the last line commented out is that the camera has a way of losing its "up" axis, as if you'd rotated about the Z axis. This is due to floating point imprecision. In many applications, it's no big deal, but it's probably not a good thing to allow players to lose their sense of "up" in a first-person environment. A quick and dirty, but effective, way to work around this is to explicitly reorient the camera so that "up" is always pointing in the same hard-coded direction (usually, along the positive Y axis). That's what that last line was responsible for. After doing the appropriate camera rotations, it gathered the new view direction from the camera, and restricted it to be in line with the world "up" axis.
-
-As we eluded to before, Jax can handle a lot more than +mouse_dragged+ events. Here's the full list:
-
-| Event         | Condition |
-| mouse_entered | When the mouse enters the WebGL canvas |
-| mouse_exited  | When the mouse exits the WebGL canvas |
-| mouse_clicked | When the mouse is clicked over the WebGL canvas |
-| mouse_moved   | When the mouse is moved while no buttons are pressed |
-| mouse_dragged | When the mouse is moved while at least one button is pressed |
-| mouse_pressed | When a button on the mouse is pressed |
-| mouse_released| When a button on the mouse is released |
-
-Any or all of these can be handled just like the +mouse_dragged+ example, above, by merely defining a function of the appropriate name. In all cases, the function may take a single +event+ argument.
-
-h4. Keyboard Events
-
-Keyboard events are generally easier to map because there's no need to worry about translating two-dimensional movements into three; however, handling them properly involves a little more source code than mouse events.
-
-The best way to handle keyboard events is to detect when a key is pressed and when it is released, _not_ to continually poll whether it is "currently pressed". However, this approach, while more efficient, is more difficult to code for, because it involves setting tracking variables which determine the amount of total movement to apply.
-
-For instance, if the user presses the "forward" key, but then simultaneously presses the "backward" key, they should cancel each other out. On the other hand, pressing the "forward" key while simultaneously pressing the "strafe right" key should produce a diagonal forward-right movement.
-
-In your +app/controllers/teapot_controller.js+ file, add the private tracking variable just above the +return+ statement. The first few lines of the controller should now look like this:
-
-<js>
-//= require "application_controller"
-
-var TeapotController = (function() {
-  var movement = { forward: 0, backward: 0, left: 0, right: 0 };
-
-  return Jax.Controller.create("teapot", ApplicationController, {
-    /* the rest of the controller code */
-</js>
-
-With this variable in place, create two more actions for handling +key_pressed+ and +key_released+ events:
-
-<js>
-key_pressed: function(event) {
-  switch(event.keyCode) {
-    case KeyEvent.DOM_VK_W: movement.forward = 1; break;
-    case KeyEvent.DOM_VK_S: movement.backward = -1; break;
-    case KeyEvent.DOM_VK_A: movement.left = -1; break;
-    case KeyEvent.DOM_VK_D: movement.right = 1; break;
-  }
-},
-
-key_released: function(event) {
-  switch(event.keyCode) {
-    case KeyEvent.DOM_VK_W: movement.forward = 0; break;
-    case KeyEvent.DOM_VK_S: movement.backward = 0; break;
-    case KeyEvent.DOM_VK_A: movement.left = 0; break;
-    case KeyEvent.DOM_VK_D: movement.right = 0; break;
-  }
-},
-</js>
-
-NOTE: If you're an experienced JavaScript keyboard-input-handling guru, you'll note that the +KeyEvent+ object exists only in FireFox. Well, fret not! Jax has already looked into this potential gotcha, and defines a compatibility layer for you. So code on!
-
-If you reload your test suite, you won't get any errors, but nothing will _happen_. That's because all we're doing is updating our tracking variable; we're not actually using it.
-
-To make use of the tracking variable, add one more method:
-
-<js>
-update: function(timechange) {
-  var speed = 1.5 * timechange;
-
-  this.player.camera.move((movement.forward + movement.backward) * speed);
-  this.player.camera.strafe((movement.left + movement.right) * speed);
-},
-</js>
-
-Similarly to the +update+ method of our +Teapot+ model, the controller's +update+ method will be called by Jax once every few milliseconds. In it, we simply move in the total direction represented by the combination of our four tracking values: forward and backward, left and right. Since one is always negative (if pressed) and the other is always positive (if pressed), they will cancel each other out if both are pressed at once, and the camera will not move.
-
-If the camera _does_ move, it will do so at a speed of 1.5 units per second.
-
-NOTE: Astute readers will note that there's nothing technically keeping us from maintaining a handle to the +Teapot+ that we added in the +index+ action, and simply rotating it from the controller's +update+ method rather than doing so from within the model. While this is technically true, it would be considered bad practice to manipulate the model that way because you would in effect be moving model-level logic into the controller. If, however, you were to move the model based on <em>user input</em>, then it would be perfectly acceptable to do so via the controller. In general, only deal with set-up, tear-down and user input within the controller. Virtually everything else should happen in the models.
-
-Here is a table listing the keyboard events you can handle within a Jax application, and the conditions under which they are fired:
-
-| Event        | Condition |
-| key_pressed  | Fired when a physical keyboard button is pressed. Do not confuse this with +key_typed+. If the button is held down, additional +key_pressed+ events are *not* fired. |
-| key_typed    | Fired when a character is typed. If the button is held down, additional +key_typed+ events will be fired -- one for each corresponding character. |
-| key_released | Fired when a physical keyboard button is released. |
-
-IMPORTANT: Unlike mouse events, which only fire in direct relation to the HTML +canvas+ element, keyboard events will fire whenever the corresponding event occurs anywhere in the document -- _except_ when a form input element is focused. If an element is accepting input from the user, Jax will not capture those events, so you'll have to revert to standard HTML event capturing.
-
-h3. Scaffolding
-
-You've just completed a very common process in Jax. So common, in fact, that it has its own generator. We can generate a _scaffold_ to have Jax build a controller, model and material for us. As you can imagine, scaffolding is most useful in situations where the controller name and the model name are the same, as is the case with our Dungeon:
-
-<shell>
-$ jax generate scaffold dungeon
-</shell>
-
-The _scaffold_ generator will create the following files:
-
-| File                                                    | Purpose |
-| app/models/dungeon.js                                   | The +Dungeon+ model |
-| app/controllers/dungeon_controller.js                   | The +DungeonController+ |
-| app/views/dungeon/index.js                              | The +DungeonController+'s primary view |
-| app/helpers/dungeon_helper.js                           | Helper code for +DungeonHelper+ |
-| app/resources/dungeons/default.yml                      | The default resource for the +Dungeon+ model |
-| app/resources/materials/dungeon.yml                     | A default material for the +Dungeon+'s mesh |
-| config/routes.rb                                        | Inserts the route mapping for the +DungeonController+ |
-| spec/javascripts/models/dungeon.js                      | Tests for the +Dungeon+ model |
-| spec/javascripts/controllers/dungeon_controller_spec.js | Tests for the +DungeonController+ |
-| spec/javascripts/helpers/dungeon_helper.js              | Tests for the +DungeonHelper+ helper |
-
-h3. Helpers
-
-In both models and controllers, it's easy to end up duplicating previous efforts. For instance, in this example we're going to use exactly the same keyboard and mouse input handling for the +Dungeon+ controller as we have already implemented for the +Teapot+ controller.
-
-Though it might seem tempting to copy-and-paste the code from one controller into the other, Jax frowns upon this. As an interpreted language, one of JavaScript's greatest strengths is also its greatest weakness. Code is not evaluated until it is time to execute it, so if there is an error in the code, you won't know it until it actually runs. Therefore, every line of additional code in an application should be carefully thought out because every line of code potentially introduces another point of failure. Following this line of thought, copy and paste is a very dangerous tool that should only be done in extreme circumstances. What's more, copying code in this way is a quick path to a maintenance nightmare; if you have to change anything, you'll have to make the same changes elsewhere, and this problem only grows more complex as more controllers and models are added to the mix.
-
-Fortunately, Jax presents a solution to this redundancy problem: Helpers.
-
-Helpers are modules of code which can be easily mixed in with other elements of your project. You can name helpers whatever you want and create as many as you want. By default, whenever you generate a controller, Jax creates a corresponding helper to go with it. You can rename this file if you like, or completely remove it.
-
-By default, even if a helper is named similarly, it will not be used. If you wish to take advantage of a helper, you must ask for it explicitly. This is easy to do, and it's the exact same process to include a helper into a model as it is to include one into a controller.
-
-NOTE: A special exception is the +ApplicationHelper+, which is one of the default files generated with every Jax application. The +ApplicationHelper+ will automatically be mixed into _all_ controllers and models, unless you delete the +ApplicationHelper+.
-
-h4. Extract the Code
-
-First, we need to extract the code we want into the helper we want to use. Create a new file called +app/helpers/user_input_helper.js+ and make it look like this:
-
-<js>
-var UserInputHelper = (function() {
-  return Jax.Helper.create({
-
-  });
-})();
-</js>
-
-Cut all of the mouse and keyboard input code, including the +update+ method, out of the +Teapot+ controller, and paste it into the +UserInputHelper+. Don't forget to include the tracking variable +movement+!
-
-The complete +UserInputHelper+:
-
-<js>
-var UserInputHelper = (function() {
-  var movement = { forward: 0, backward: 0, left: 0, right: 0 };
-
-  return Jax.Helper.create({
-    mouse_dragged: function(event) {
-      this.player.camera.rotate(0.01, [event.diffy, -event.diffx, 0]);
-      this.player.camera.orient(this.player.camera.getViewVector(), [0,1,0]);
-    },
-
-    key_pressed: function(event) {
-      switch(event.keyCode) {
-        case KeyEvent.DOM_VK_W: movement.forward = 1; break;
-        case KeyEvent.DOM_VK_S: movement.backward = -1; break;
-        case KeyEvent.DOM_VK_A: movement.left = -1; break;
-        case KeyEvent.DOM_VK_D: movement.right = 1; break;
-      }
-    },
-
-    key_released: function(event) {
-      switch(event.keyCode) {
-        case KeyEvent.DOM_VK_W: movement.forward = 0; break;
-        case KeyEvent.DOM_VK_S: movement.backward = 0; break;
-        case KeyEvent.DOM_VK_A: movement.left = 0; break;
-        case KeyEvent.DOM_VK_D: movement.right = 0; break;
-      }
-    },
-
-    update: function(timechange) {
-      var speed = 1.5 * timechange;
-
-      this.player.camera.move((movement.forward + movement.backward) * speed);
-      this.player.camera.strafe((movement.left + movement.right) * speed);
-    }
-  });
-})();
-</js>
-
-h4. Call the Helper
-
-With all of the copied code removed from the +Teapot+ controller, it should now be looking pretty sparse once more. Don't worry -- we're about to pull all of that functionality right back into the controller, but we're going to do it in a more modular way.
-
-Since Jax won't just automatically include the helper for us, we need to tell it to do so. Define a new function in your controller called +helpers+. It's a very simple function that just returns a hard-coded array of helpers:
-
-<js>
-helpers: function() {
-  return [ UserInputHelper ];
-}
-</js>
-
-That's it! Jax will detect the presence of this function and use it to mix in the helper methods with this controller <em>as if they were defined by the controller itself</em>.
-
-If you reload your Jax suite, you'll see that you can still navigate around the rotating teapot just as before. There's no logical difference, but the code is much more organized, easier to maintain and introduces fewer points of failure by virtue of requiring less code.
-
-h3. The Dungeon
-
-We're now ready to build up our dungeon. First, we need a way to tell Jax what the dungeon should look like. It would also be a good idea to mark out where we plan to place light sources, where the player should start, and what direction the camera should be facing at the start of the demo. All of these things represent dungeon data, so we can put them into our resource file.
-
-h4. Define the Resource
-
-Create the file +app/resources/dungeons/first.yml+ and add the following content:
-
-<yaml>
-map:
-  - XXXXXXXXX
-  - X XXX  'X
-  - X'    X X
-  - XXXXXXXXX
-  
-starting:
-  position: 1, 1
-  direction: 0, 1
-</yaml>
-
-NOTE: It's usually a good idea to define the obvious components of a model in its resource file before starting to add any model logic. By the time you've decided what data to store, you'll often have a good idea of how you want to parse it. This doesn't mean you can't come back and alter it as needed, of course.
-
-As you can see, we've decided to have an attribute +map+ which is an array of strings. Each character in each string can be one of the letter X, empty space, or an apostrophe ('). The apostrophes will represent point lights, which we'll use to light up the dungeon. The X's mark walls, while white space represent passable hallways.
-
-The other attribute we've created is called +starting+, and contains two sub-attributes: +position+ and +direction+. Notice that we've specified both of these as vectors in two dimensions, not three. This is because the map itself is laid out in two dimensions; we'll do the necessary conversions into 3D (by simply setting the third component to 0) in a moment.
-
-h4. Write Some Tests
-
-After you decide on a format for your resources, you should write some basic tests to make sure that it is parsed as you expect it to be. This provides a little added peace-of-mind that Jax is doing its job, but more importantly, it exposes the layers of functionality that you have yet to write. You may be surprised to find that quite a bit of your "work" has already been taken care of for you!
-
-NOTE: This guide will only touch on the basics of unit testing in Jax; for a much more detailed guide on testing your Jax applications, see the "testing guide":testing.html.
-
-Deciding on what level of detail to test is a minor black art. If you write tests that are too vague, you'll end up with flimsy specs that let you get away with writing unstable code and introduce hard-to-debug issues. On the other hand, if the tests are too specific, you'll find yourself having to go back and modify the them every time you make a minor change to the resource, such as setting +position+ to (1, 2) instead of (1, 1). Worse, constantly switching back and forth between tests and data often leads developers to begin ignoring their tests entirely, which is just as bad as not testing at all.
-
-As a rule of thumb, try to test the _structure_ of your resource without testing its _content_. For example, instead of making sure an array contains the values [1, 0, 1], simply make sure that it _is_ an array, and that it contains exactly three values.
-
-There are 3 basic conditions that we should spec out for our +Dungeon+ resource. They are:
-
-# It should have a map, which should be an array of strings
-# It should have a starting position and direction
-# The starting position and direction should both be converted into 3-dimensional vectors, not left as strings or 2-dimensional vectors.
-
-Edit your +spec/javascripts/models/dungeon_spec.js+ file. Just after the +var model;+ declaration, we'll create a test specifically for the _first_ +Dungeon+ resource. Insert the following code beginning on line 3:
-
-<js>
-describe("'first' resource", function() {
-  beforeEach(function() { model = Dungeon.find("first"); });
-  
-  it("should have a map, which should be a an array of strings", function() {
-    var map = model.map;
-    expect(map.length).toBeGreaterThan(0);
-    for (var i = 0; i < map.length; i++)
-      expect(typeof map[i]).toEqual('string');
-  });
-  
-  it("should have a 3-element starting position", function() {
-    expect(model.starting.position.length).toEqual(3);
-  });
-  
-  it("should have a 3-element starting direction", function() {
-    expect(model.starting.direction.length).toEqual(3);
-  });
-});
-</js>
-
-Reloading your suite, you'll now have some failing tests. Notice that only two are failing, however. The first one is passing! This is because Jax has automatically converted the dungeon's +map+ attribute into an array of strings.
-
-h4. Adding Business Logic
-
-Two of our tests are still failing because the model doesn't know how to translate the starting +position+ and +direction+ attributes into 3-dimensional vectors.
-
-Open your +app/models/dungeon.js+ file. On line 6, just above <tt>return Jax.Model.Create ...</tt>, add the following private method:
-
-<js>
-function parse(str) {
-  var vec = str.split(/,\s*/);
-  return [parseFloat(vec[0]), 0.0, parseFloat(vec[1])];
-}
-</js>
-
-This method is _private_ because it is declared within a generic function (see the line just preceding it), making it accessible only to code that is _also_ in the same function. That limits the scope of the +parseVectorString+ function just to the +Dungeon+ model.
-
-Now, on line 12, within the +after_initialize+ method body, add the following:
-
-<js>
-if (this.starting) {
-  this.starting.position = parse(this.starting.position);
-  this.starting.direction = parse(this.starting.direction);
-}
-</js>
-
-WARNING: The reason we test to see if +this.starting+ exists is because we didn't add a corresponding entry to the dungeon's +default.yml+ file. This means that it's possible to instantiate a dungeon without any +starting+ attribute. Had we moved the +starting+ attribute into the +default+ resource, we would not have to make this check.
-
-Here's the complete +app/models/dungeon.js+ source code listing:
-
-<js>
-/**
- * class Dungeon < Jax.Model
- *
- **/
-var Dungeon = (function() {
-  function parse(str) {
-    var vec = str.split(/,\s*/);
-    return [parseFloat(vec[0]), 0.0, parseFloat(vec[1])];
-  }
-
-  return Jax.Model.create({
-    after_initialize: function() {
-      if (this.starting) {
-        this.starting.position = parse(this.starting.position);
-        this.starting.direction = parse(this.starting.direction);
-      }
-    }
-  });
-})();
-</js>
-
-h4. The Mesh
-
-As you saw with the _Teacup_ example, in order to draw on the screen, we must first define a Mesh. Meshes represent the 3D data used by WebGL. Previously, we used a built-in type of Mesh -- the +Teapot+. There are a growing number of built-in meshes that you can use for simple objects, and they are listed in the table below:
-
-| Mesh type | Description | Usage Example |
-| Cube      | Six perpendicular Quads forming a closed box. The faces of the Cube point outward. | <tt>new Jax.Mesh.Cube({width:1, height:2, depth:3});</tt> |
-| Plane     | An arbitrary number of Quads placed adjacently to form one large, multi-polygon square. | <tt>new Jax.Mesh.Plane({width:500, height:500, x_segments:20, y_segments:20});</tt> |
-| Quad      | A single-polygon square. | <tt>new Jax.Mesh.Quad({width:1, height:1});</tt> |
-| Sphere    | A multi-polygon mesh approximating the shape of a ball. Slices and stacks comprise the number of polygons; the more slices and stacks, the more perfect the sphere will be. | <tt>new Jax.Mesh.Sphere({slices:30, stacks:30, radius:1});</tt> |
-| Teapot    | A Jax implementation of the "Utah Teapot":http://en.wikipedia.org/wiki/Utah_teapot. | <tt>new Jax.Mesh.Teapot({size:1});</tt> |
-| Torus     | A "donut"-shaped mesh. The number of polygons is comprised of the number of sides and rings; the more polygons, the more perfect the torus will be. | <tt>new Jax.Mesh.Torus({inner_radius:0.6, outer_radius:1.8, sides:128, rings:256});</tt> |
-
-Unfortunately, no graphics library can pre-build every possible mesh -- and besides, you probably wouldn't want them to try. Whether you store your meshes in static files and load them with AJAX, or write algorithms to build them dynamically, one way or another you're going to need to know how to build your own Mesh.
-
-WARNING: Meshes are confusing. You're going to need to deal with raw 3D data and you're going to need to use some math to put it all together. If you are new to graphical programming, you should brush up on the principles of basic mesh construction before continuing.
-
-h5. A Simple Mesh Example
-
-As mesh construction goes, Jax is pretty easy to use. Here's how you would create a Quad mesh:
-
-<js>
-var QuadMesh = Jax.Class.create(Jax.Mesh, {
-  init: function(vertices, colors, textureCoords, normals, vertexIndices) {
-    this.draw_mode = GL_TRIANGLE_STRIP;
-    
-    var size = 1.0; // 1 unit high, 1 unit wide
-    var width = size / 2, height = size / 2;
-    
-    vertices.push(-width,  height, 0);
-    vertices.push(-width, -height, 0);
-    vertices.push( width,  height, 0);
-    vertices.push( width, -height, 0);
-
-    colors.push(1,1,1,1);
-    colors.push(1,1,1,1);
-    colors.push(1,1,1,1);
-    colors.push(1,1,1,1);
-        
-    textureCoords.push(0, 1);
-    textureCoords.push(0, 0);
-    textureCoords.push(1, 1);
-    textureCoords.push(1, 0);
-    
-    normals.push(0,0,1);
-    normals.push(0,0,1);
-    normals.push(0,0,1);
-    normals.push(0,0,1);
-    
-    vertexIndices.push(0, 1, 2, 3);
-  }
-});
-</js>
-
-Most of the above should look familiar if you've ever dealt with 3D models before.
-
-First, we tell Jax to create a new mesh type by inheriting from the base +Jax.Mesh+ class. There's nothing special about this that you haven't seen elsewhere already.
-
-We only need to add one function, +init+, to the mesh. When Jax determines that it's time to build (or rebuild) the mesh, it will call +init+ with a number of arguments. All of these arguments are arrays. Although they are all effectively optional, omitting them will limit their compatibility with certain shaders:
-
-| Argument   | Description                       | If Empty... |
-| +vertices+ | Vertex coordinate data. Must be stored in multiples of 3 (X, Y, Z). | ... the mesh can't be rendered. |
-| +colors+   | Per-vertex color information. Must be stored in multiples of 4 (red, green, blue, alpha transparency) and must have one color per vertex stored in +vertices+. | ... the color data will default to all 1's (pure white, completely opaque). |
-| +textureCoords+ | Texture coordinate information. Multiples of 2 (U, V). Must specify one texture coordinate per vertex. Individual materials may scale these numbers as needed. | ... the mesh cannot be rendered with any texture-based shaders. Attempting to do so will probably result in a GL_INVALID_OPERATION error. |
-| +normals+ | Directional vectors representing the direction each vertex is pointing. Multiples of 3 (X, Y, Z). Must specify one normal per vertex. | ... the mesh cannot be lit effectively, and trying to render with lighting support or any other normals-based shader may result in a GL_INVALID_OPERATION error. Also, since tangent space cannot be calculated without normal data, normal maps and other shaders relying on tangent vectors will probably fail. |
-| +vertexIndices+ | Vertex index data. Stored in multiples of 1, each index is an integer value pointing to a vertex to be drawn. For instance, index 0 represents <tt>vertices[0..2]</tt>; index 1 represents <tt>vertices[3..5]</tt>; and so on. Note that each index corresponds identically to color index, textureCoords index, and so on. | If left empty, Jax will automatically use the +vertices+ data sequentially as if the vertex indices were equal to <tt>[0, 1, 2, ... n]</tt>. No errors should occur, though the mesh may not be rendered properly if the vertex data is not meant to be rendered sequentially. |
-
-INFO: In order to achieve maximum compatibility, you should do your best not to leave any of the data arrays empty, except perhaps +vertexIndices+ if your mesh doesn't rely on vertex indices.
-
-h5. The Dungeon Mesh
-
-Now that you have enough information to construct a mesh in Jax, it's time for us to build the mesh to be used for the dungeon. Remember the +map+ attribute of the +Dungeon+ model? We're now going to iterate through that map and dynamically build our dungeon mesh from it.
-
-INFO: Meshes do not have to be dynamically generated in the same way as we are doing with the +Dungeon+, but they do need to be given data from _somewhere_. You could load this data directly from a JSON file retrieved via AJAX, or build the mesh in a completely different way. The best approach to mesh building depends entirely upon the needs and expectations of your application.
-
-In the +after_initialize+ method of your +app/models/dungeon.js+ file, add the following code:
-
-<js>
-if (this.map) {
-  var map = this.map;
-  this.mesh = new Jax.Mesh({
-    init: function(vertices, colors, texcoords, normals, indices) {
-      var ofs = 0.5; // offset from center of each grid node
-      var row;
-
-      function drawSideWall(x, z, side) {
-        x += ofs*side;
-        //             triangle 1                                  triangle 2
-        vertices.push (x,-ofs,z-ofs,  x,-ofs,z+ofs,  x,ofs,z-ofs,  x,ofs,z-ofs,  x,-ofs,z+ofs,  x,ofs,z+ofs);
-        colors.push   (1,0,0,1,       1,0,0,1,       1,0,0,1,      1,0,0,1,      1,0,0,1,       1,0,0,1);
-        texcoords.push(0,0,           1,0,           0,1,          0,1,          1,0,           1,1);
-        normals.push  (-side,0,0,     -side,0,0,     -side,0,0,    -side,0,0,    -side,0,0,     -side,0,0);
-      }
-
-      function drawFrontWall(x, z, side) {
-        z -= ofs*side;
-        //             triangle 1                                  triangle 2
-        vertices.push (x-ofs,-ofs,z,  x+ofs,-ofs,z,  x-ofs,ofs,z,  x-ofs,ofs,z,  x+ofs,-ofs,z,  x+ofs,ofs,z);
-        colors.push   (0,0,1,1,       0,0,1,1,       0,0,1,1,      0,0,1,1,      0,0,1,1,       0,0,1,1);
-        texcoords.push(0,0,           1,0,           0,1,          0,1,          1,0,           1,1);
-        normals.push  (0,0,side,      0,0,side,      0,0,side,     0,0,side,     0,0,side,      0,0,side);
-      }
-
-      for (var y = 0; y < map.length; y++) {
-        row = map[y];
-        for (var x = 0; x < row.length; x++) {
-          var ch = row[x];
-          if (ch == 'X') {
-          } else {
-            /* walls */
-            if (x == 0            || row[x-1]    == 'X') drawSideWall(x, y, -1);   // left
-            if (y == 0            || map[y-1][x] == 'X') drawFrontWall(x, y, 1);   // front
-            if (x == row.length-1 || row[x+1]    == 'X') drawSideWall(x, y, 1);    // right
-            if (y == map.length-1 || map[y+1][x] == 'X') drawFrontWall(x, y, -1);  // back
-
-            /* floor */
-            vertices.push(x-0.5,-0.5,y+0.5,  x-0.5,-0.5,y-0.5,  x+0.5,-0.5,y-0.5); // tri 1
-            vertices.push(x-0.5,-0.5,y+0.5,  x+0.5,-0.5,y-0.5,  x+0.5,-0.5,y+0.5); // tri 2
-            colors.push(1,1,1,1,  1,1,1,1,  1,1,1,1,  1,1,1,1,  1,1,1,1,  1,1,1,1);
-            texcoords.push(0,1,  0,0,  1,0,  0,1,  1,0,  1,1);
-            normals.push(0,1,0,  0,1,0,  0,1,0,  0,1,0,  0,1,0,  0,1,0);
-
-            /* ceiling */
-            vertices.push(x-0.5, 0.5,y+0.5,  x-0.5, 0.5,y-0.5,  x+0.5, 0.5,y-0.5); // tri 1
-            vertices.push(x-0.5, 0.5,y+0.5,  x+0.5, 0.5,y-0.5,  x+0.5, 0.5,y+0.5); // tri 2
-            colors.push(1,1,0,1,  1,1,0,1,  1,1,0,1,  1,1,0,1,  1,1,0,1,  1,1,0,1);
-            texcoords.push(0,1,  0,0,  1,0,  0,1,  1,0,  1,1);
-            normals.push(0,-1,0,  0,-1,0,  0,-1,0,  0,-1,0,  0,-1,0,  0,-1,0);
-          }
-        }
-      }
-    }
-  });
-  
-  this.mesh.material = Material.find("dungeon");
-}
-</js>
-
-h4. Drawing the Scene
-
-Now that we have our mesh, our model, its basic material and some input handling code in place, all we have to do is call these components from the controller. Doing so involves nothing you haven't already seen before in this guide. Here's the complete source code for +app/controllers/dungeon_controller.js+:
-
-<js>
-//= require "application_controller"
-
-var DungeonController = (function() {
-  return Jax.Controller.create("dungeon", ApplicationController, {
-    index: function() {
-      var dungeon = Dungeon.find("first");
-      this.world.addObject(dungeon);
-      this.player.camera.setPosition(dungeon.starting.position);
-      this.player.camera.setDirection(dungeon.starting.direction);
-    },
-    
-    helpers: function() { return [UserInputHelper]; }
-  });
-})();
-</js>
-
-Don't forget to change the +root+ in +config/routes.rb+. Your +config/routes.rb+ file should now look like:
-
-<js>
-Dungeon.routes.map do
-  map 'dungeon/index'
-  map 'teapot/index'
-  root 'dungeon'
-end
-</js>
-
-After making this change and reloading your Jax suite, you should be standing within (and able to walk / look around in) your new, brightly-colored Dungeon!
-
-!images/getting_started/dungeon-rainbow.png(A Brightly Colored Dungeon)!
-
-
-h3. Adding Texture
-
-The dungeon is functional, but it's not very believable. In fact, a rainbow-colored dungeon isn't much of a dungeon at all! We made each wall a starkly different color for the purposes of this tutorial, but realistically, you'd probably never do this. Instead, you'd make it look more like the environment you're targeting, and the most basic way to do this is with texturing.
-
-h4. Updating the Material
-
-When we generated our +Dungeon+ scaffold, Jax created a basic material for us. However, that material only supports basic color and lighting. We could edit the material file by hand, but there are a lot of options, and they're different from shader to shader. Rather than force you to commit them all to memory or constantly look up the Jax documentation, you can rerun the Jax +material+ generator with the <tt>--append</tt> option:
-
-<shell>
-$ jax generate material dungeon texture --append
-</shell>
-
-NOTE: Any shaders that you invoke using the <tt>--append</tt> command will be _added_ to the list of shaders used by +material+. This command won't replace any shaders and cannot be used to remove any. Running the example above twice will produce a material that expects two separate textures.
-
-h4. Selecting a Texture
-
-We're going to use the texture below for the walls of the dungeon. Save this image into your Jax application as +public/images/rock.png+:
-
-!images/getting_started/rock.png(The Dungeon Wall Texture)!
-
-Now edit the +app/resources/materials/dungeon.yml+ file. Scroll to the bottom, and change the texture's +path+ to the path of the dungeon texture:
-
-<yaml>
-- type: Texture
-  path: /images/rock.png
-  # ...
-</yaml>
-
-Reload, and you'll see textured walls! However, all is not quite ideal. The walls of the dungeon are now textured, but they are still tinged with their original colors. This is because the per-vertex color data hasn't changed. Jax, receiving conflicting information about the mesh, has merged the two data sets. Actually, it's pretty normal for a graphics library to do this, because it allows you to do special coloring on a mesh irrespective of the textures used.
-
-<strong>To undo the colored walls, simply edit the +app/models/dungeon.js+ file and replace all the 0's in calls to +colors.push(...)+ to 1's. Reload, and all of the walls should be the expected color.</strong>
-
-<img src="images/getting_started/dungeon-rainbow-textured.png" style="width:300px;height:200px;margin-right:2em;float:left;" />
-<img src="images/getting_started/dungeon-textured.png" style="clear:right;width:300px;height:200px;" />
-
-
-h3. Light Sources
-
-Our dungeon is looking good, but we're not quite there, yet. We still need to add our point lights to the scene. Fortunately, as you saw with the Teacup example, adding lights is a piece of cake! First we need to generate the light source:
-
-<shell>
-$ jax generate light torch point
-</shell>
-
-Now we just need to add the light source to the appropriate locations in the scene. However, the appropriate locations are determined by the model. The controller shouldn't necessarily care about where the lights are positioned, as long as they are positioned appropriately. Since these lights are directly associated with the dungeon, it makes sense for the controller to delegate this job to the dungeon.
-
-In the +index+ action of the +app/controllers/dungeon_controller.js+ file, add the following line:
-
-<js>
-dungeon.addTorches(this.world);
-</js>
-
-h4. More Model Logic
-
-We've just instructed the controller to call a method of +Dungeon+ that doesn't exist. Obviously, the next step is to define that method in +app/models/dungeon.js+:
-
-<js>
-addTorches: function(world) {
-  var map = this.map;
-  if (map) {
-    for (var z = 0; z < map.length; z++) {
-      var row = map[z];
-      for (var x = 0; x < row.length; x++) {
-        // each apostrophe (') represents a light source
-        if (row[x] == "'") {
-          var torch = LightSource.find("torch");
-          torch.camera.setPosition(x, 0, z);
-          world.addLightSource(torch);
-        }
-      }
-    }
-  }
-}
-</js>
-
-What this code does is search through the map looking for light sources (denoted by an apostrophe). When it finds one, it instantiates a new point light form the +torch+ resource, sets its position and then adds it to the scene. Since all the walls and floors are offset by half a unit in each direction, the point light will be positioned directly in the middle of the hallway.
-
-INFO: Nearly every tangible object in Jax has an internal camera. This tracks its position as well as its orientation. Models, light sources, anything that can be added to the world can be positioned and oriented in exactly the same way. In addition, since each Camera tracks its own frustum, (you don't need to know what this is right now), each object can "see" the other objects in the scene. This is very useful for AI programming.
-
-!images/getting_started/dungeon-textured-lighting.png(Dungeon with Texture and Lighting)!
-
-
-h3. Finishing Touches
-
-There are a few things we could do to improve the Dungeon scene somewhat. First of all, the torch lights work well but some areas are rather dark. Instead of just adding more apostrophes to the map, we could create one additional point light that follows the player around as if they were holding a torch.
-
-Second, it would be nice to add even more detail to the scene. Even state-of-the-art hardware can only model so much complexity, but we can fake it by adding normal mapping.
-
-h4. The Lantern
-
-It might be preferable for the player to hold a light source somewhat different than those attached to the walls, just in case we need to tweak the color, attenuation, and so forth. Since it's not particularly troublesome to do so, let's just generate a new point light called +lantern+:
-
-<shell>
-$ jax generate light lantern point
-</shell>
-
-Now, add it to the world via the controller in the +index+ action of +app/controllers/dungeon_controller.js+:
-
-<js>
-this.player.lantern = LightSource.find("lantern");
-this.world.addLightSource(this.player.lantern);
-</js>
-
-Now that the light source _exists_, we need to make it follow the player around. Since our +update+ method is part of the +UserInputHelper+, we'll want to add a condition to verify that the player actually _has_ a lantern, or else we'll accidentally break our Teapot demo.
-
-NOTE: This, incidentally, is why unit testing is so important for both models and controllers. We're skipping a lot of testing in order to reduce the length and complexity of this guide, but in a real-world application you should absolutely be testing every possible component. You are encouraged to take a look at the "Testing Guide":testing.html when you have completed this one.
-
-Add this code to the end of the +update+ method in the +app/helpers/user_input_helper.js+ file:
-
-<js>
-if (this.player.lantern) {
-  // reposition the lantern to the player's location
-  this.player.lantern.camera.setPosition(this.player.camera.getPosition());
-}
-</js>
-
-Perfect! Now it's a quite well-lit dungeon indeed. If you prefer a darker dungeon, you can make the lights less illuminating by playing with the attenuation and color settings for the light sources. To get the most out of lights, you should also take a look at the "Lighting Guide":lighting.html.
-
-h4. Normal Mapping
-
-Normal mapping, also called DOT3 bump mapping, is a technique that converts a specially-encoded texture image into directional vectors, or _normals_, which are then used in lighting calculations. The end result is a surface that looks far more detailed than it really is. If you look at a single-polygon Quad with normal mapping, it may _look_ like it is composed of many thousands of polygons; however, if you look at that same quad from a severe angle, you'll see that it is still, in fact, quite flat. Normal mapping makes the (usually correct) assumption that these extreme angles will be few and far between, and manages to pull off some very impressive-looking effects without sacrificing much in the way of graphics processing power.
-
-In order to implement normal mapping, we'll first need a normal map. Save this image to +public/images/rock_normal.png+:
-
-!images/getting_started/rock_normal.png(The Dungeon Wall Normal Map)!
-
-Now append a +normal_map+ shader to your existing dungeon wall material:
-
-<shell>
-$ jax generate material dungeon normal_map --append
-</shell>
-
-Finally, edit the +app/resources/materials/dungeon.yml+ file and set the path to the normal map image:
-
-<yaml>
-- type: NormalMap
-  path: /images/rock_normal.png
-  # ...
-</yaml>
-
-You're done setting up normal mapping! We've already got all of our lights, meshes and whatnot in place, so all you have to do now is reload your application to see the normal map in action.
-
-!images/getting_started/dungeon-normal-map.png(Dungeon with Normal Mapping)!