jax 1.1.1 → 2.0.0

data/lib/assets/javascripts/jax/mvc/model.js

@@ -0,0 +1,302 @@
+/**
+ * class Jax.Model
+ * 
+ * Models encapsulate virtually all business logic. If a Monster knows how to attack, the logic
+ * that makes it do so is held within the +Monster+ model. If the terrain has trees and other
+ * vegetation, the +Terrain+ model is responsible for setting that up.
+ *
+ * While controllers generally have only high-level code such as initial scene set-up and
+ * processing of user input, models handle nearly everything else.
+ *
+ * Models also contain the actual game data. Jax further splits models into two components: the
+ * Model itself and its Resources.
+ *
+ * Define a model like so:
+ *
+ *     var Monster = Jax.Model.create({
+ *       after_initialize: function() {
+ *         // code to be run automatically after a monster is instantiated
+ *       },
+ * 
+ *       update: function(time) {
+ *         // code to be run automatically every few milliseconds
+ *       },
+ *
+ *       dealDamageTo: function(otherModel) {
+ *         // custom method, called only when you invoke it
+ *         otherModel.takeDamage(this.attack_damage);
+ *       }
+ *     });
+ *
+ * Once defined, you can add data easily:
+ *
+ *     Monster.addResources({"ogre": {
+ *       hit_points: 100,
+ *       attack_damage: 75
+ *     }});
+ *
+ * You can instantiate a model whose resources already exist like so:
+ *
+ *     var ogre = Monster.find("ogre");
+ *
+ * Note that subsequent calls to +Model.find+ will return unique objects. For instance, the
+ * following code will add 3 separate "ogres" to the world:
+ *
+ *     world.addObject(Monster.find("ogre"));
+ *     world.addObject(Monster.find("ogre"));
+ *     world.addObject(Monster.find("ogre"));
+ * 
+ **/
+(function() {
+  function initProperties(self, data) {
+    // to make sure sub-properties of data are standalone objects, so that the original data can't be tainted
+    data = Jax.Util.normalizeOptions(data, {});
+    
+    var attribute;
+        
+    if (data) {
+      for (attribute in data) {
+        switch(attribute) {
+          case 'position':    self.camera.setPosition(Jax.Util.vectorize(data[attribute])); break;
+          case 'direction':   self.camera.setDirection(Jax.Util.vectorize(data[attribute])); break;
+          case 'mesh':
+            if (data[attribute].isKindOf(Jax.Mesh)) self.mesh = data[attribute];
+            else throw new Error("Unexpected value for mesh:\n\n"+JSON.stringify(data[attribute]));
+            break;
+          default:
+            self[attribute] = data[attribute];
+        }
+      }
+    }
+  }
+  
+  Jax.Model = (function() {
+    return Jax.Class.create({
+      /**
+       * new Jax.Model(data)
+       * - data: a set of attributes to be assigned to this instance of the model.
+       *
+       * Anything can be in the data, or you may supply no data at all to instantiate
+       * a model with its default attributes.
+       *
+       * The following attributes have special meanings:
+       *
+       * * +position+ : sets the position of this model in world coordinates.
+       * * +direction+ : sets the direction this model is facing, in world coordinates.
+       * * +mesh+: an instance of +Jax.Mesh+
+       * * +shadow_caster+ : true or false; specifies whether this model can cast shadows.
+       * * +lit+ : true or false; specifies whether this model is affected by nearby lights.
+       *
+       **/
+      initialize: function(data) {
+        this.camera = new Jax.Camera();
+        
+        initProperties(this, Jax.Model.default_properties);
+        if (this._klass && this._klass.resources)
+          initProperties(this, this._klass.resources['default']);
+        initProperties(this, data);
+        
+        if (this.after_initialize) this.after_initialize();
+      },
+      
+      /**
+       * Jax.Model#isShadowCaster() -> Boolean
+       *
+       * Returns true if this model casts shadows upon other models in the scene. Note that
+       * even if true, shadows will only be cast upon models which utilize +Jax.Material+s that support
+       * both the +Lighting+ and +ShadowMap+ effects.
+       *
+       **/
+      isShadowCaster: function() { return this.shadow_caster; },
+
+      /**
+       * Jax.Model#render(context) -> undefined
+       * 
+       * Renders this model with the given context. If the model doesn't have a mesh,
+       * nothing is rendered.
+       **/
+      render: function(context, options) {
+        if (this.mesh)
+        {
+          var self = this;
+          context.pushMatrix(function() {
+            context.multModelMatrix(self.camera.getTransformationMatrix());
+            self.mesh.render(context, options);
+          });
+        }
+      },
+      
+      /**
+       * Jax.Model#getBoundingCube() -> Object
+       *
+       * Returns an object describing the cubic dimensions of this model.
+       * 
+       * Example:
+       *
+       *     var bounds = new Jax.Model({mesh:new Jax.Mesh.Cube()}).getBoundingCube();
+       *     // 'bounds' contains the following:
+       *     {
+       *       left: -0.5,
+       *       right: 0.5,
+       *       bottom: -0.5,
+       *       top: 0.5,
+       *       front: 0.5,
+       *       back: -0.5,
+       *       width: 1.0,
+       *       height: 1.0,
+       *       depth: 1.0
+       *     }
+       * 
+       **/
+      getBoundingCube: function() {
+        if (!this.mesh) return {left:0,right:0,bottom:0,top:0,front:0,back:0,width:0,height:0,depth:0};
+        if (!this.mesh.built) this.mesh.rebuild();
+        return this.mesh.bounds;
+      },
+      
+      /**
+       * Jax.Model#getBoundingSphereRadius() -> Number
+       *
+       * A sphere can be defined with two values: a position and a radius. A model's
+       * position is always known via its camera (see +Jax.Model#camera+).
+       *
+       * This method returns the radius of its bounding sphere. A bounding sphere is
+       * guaranteed to contain the furthest-away point from the model's position. It is less
+       * accurate than +Jax.Model#getBoundingCube+, but using it is much faster.
+       *
+       **/
+      getBoundingSphereRadius: function() {
+        var b = this.getBoundingCube();
+        return Math.max(b.width, Math.max(b.height, b.depth));
+      },
+      
+      /**
+       * Jax.Model#dispose() -> undefined
+       *
+       * Disposes of this model and its mesh.
+       *
+       * Note that both models and meshes _can_ be reused after disposal; they'll just
+       * be silently re-initialized. This means it is safe to dispose of models while
+       * they are still being used (although this is slow and not recommended if at all
+       * avoidable).
+       **/
+      dispose: function() {
+        if (this.mesh)
+          this.mesh.dispose();
+      },
+      
+      /**
+       * Jax.Model#isLit() -> Boolean
+       *
+       * Returns true if this model can be lit by other light sources. Note that even
+       * if this is true, the +Jax.Material+ used by its +Jax.Mesh+ must support the
+       * +Lighting+ effect in order to actually perform the lighting effect.
+       *
+       **/
+      isLit: function() {
+        return this.lit;
+      },
+
+      /**
+       * Jax.Model#inspect() -> String
+       * 
+       * Returns the JSON representation of the attributes in this model.
+       * Unlike JSON.stringify(), this method will omit function definitions so
+       * that only actual data elements are returned in the resulting JSON string.
+       * 
+       **/
+      inspect: function() {
+        result = {};
+        for (var i in this)
+          if (!Object.isFunction(this[i]) && i != "_klass")
+            result[i] = this[i];
+        return JSON.stringify(result);
+      }
+    });
+  })();
+  
+  var model_class_methods = {
+    /**
+     * Jax.Model.find(id) -> Jax.Model
+     * - id (String): the unique identifier of the model to be found
+     * 
+     * Finds the resource with the specified name, instantiates its model and returns it.
+     * 
+     * Note that this is a class method of the model in question, and not of Jax.Model itself.
+     * 
+     * For example, this would be correct:
+     * 
+     *     Character.find('bad_guy')
+     *     
+     * while this would be *incorrect*:
+     * 
+     *     Jax.Model.find('bad_guy')
+     *     
+     **/
+    find: function(id) {
+      for (var resource_id in this.resources) {
+        if (id == resource_id)
+          return new this(this.resources[id]);
+      }
+      throw new Error("Resource '"+id+"' not found!");
+    },
+
+    /**
+     * Jax.Model.addResources(resources) -> undefined
+     * - resources (Object): the resources to be added
+     * 
+     * Adds the resources to the specified model. These resources can then be found using
+     * Jax.Model.find(id).
+     * 
+     * Note that this is a class method of the model in question, and not of Jax.Model itself.
+     * 
+     * For example, this would be correct:
+     * 
+     *     Character.addResources({'bad_guy': {...}})
+     *     
+     * while this would be *incorrect*:
+     * 
+     *     Jax.Model.addResources({'bad_guy': {...}})
+     *     
+     **/
+    addResources: function(resources) {
+      this.resources = this.resources || {};
+      for (var id in resources)
+        if (this.resources[id]) throw new Error("Duplicate resource ID: "+id);
+        else this.resources[id] = resources[id];
+    }
+  };
+  
+  Jax.Model.default_properties = {
+    lit: true,
+    shadow_caster: true
+  };
+  
+  /**
+   * Jax.Model.create(inner) -> klass<Jax.Model>
+   * - inner (Object): a set of methods the class will contain.
+   * Jax.Model.create(superclass, inner) -> klass<Jax.Model>
+   * - superclass (Jax.Model): an optional superclass. Defaults to +Jax.Model+.
+   * - inner (Object): a set of methods the class will contain.
+   * 
+   * Creates a new Jax class inheriting from Jax.Model. If a superclass is given,
+   * the model will inherit from the given superclass instead. The superclass is,
+   * in turn, expected to be a subclass of Jax.Model.
+   *
+   * Examples:
+   *
+   *     var Person = Jax.Class.create({ ... });
+   *     var Colin = Jax.Class.create(Person, { ... });
+   *
+   **/
+  Jax.Model.create = function(superclass, inner) {
+    var klass;
+    if (inner) klass = Jax.Class.create(superclass, inner);
+    else       klass = Jax.Class.create(Jax.Model, superclass);
+    
+    klass.addMethods({_klass:klass});
+
+    Object.extend(klass, model_class_methods);
+    return klass;
+  };
+})();

data/lib/assets/javascripts/jax/mvc/route_set.js

@@ -0,0 +1,148 @@
+/**
+ * class Jax.RouteSet
+ * 
+ * Manages routing for Jax. All routes are mapped through the route set, and
+ * the route set is responsible for recognizing routes and dispatching them
+ * to the appropriate destination.
+ * 
+ * A route is generally represented as a string of the form
+ * "controller_name/action_name", where controller_name is the short name of
+ * the controller and the action name is the action to be triggered. For
+ * example, a route matching the #index action of the WelcomeController
+ * would look like:
+ * 
+ *     "welcome/index"
+ *   
+ * A special case is the root route, which is always mapped to "/". This is
+ * used to give Jax applications a default starting point. If omitted, it
+ * will be necessary to invoke the appropriate controller manually. You
+ * can do this by calling Jax.RouteSet#dispatch.
+ **/
+Jax.RouteSet = (function() {
+  return Jax.Class.create({
+    initialize: function() {
+      this.clear();
+    },
+    
+    /**
+     * Jax.RouteSet#clear() -> Jax.RouteSet
+     *
+     * Removes all routes registered with this Jax.RouteSet and then
+     * returns this RouteSet.
+     **/
+    clear: function() {
+      this._map = {};
+      return this;
+    },
+
+    /**
+     * Jax.RouteSet#root(controller, actionName) -> undefined
+     * - controller (Jax.Controller): the controller that will be routed to
+     * - actionName (String): the name of the action to be invoked by this route
+     * 
+     * Note that the controller is expected to be a subclass of Jax.Controller.
+     * 
+     * Example:
+     * 
+     *     Jax.routes.root(WelcomeController, "index");
+     * 
+     **/
+    root: function() {
+      throw new Error("Jax.RouteSet#root is deprecated. Instead, please use "+
+                        "`new Jax.Context(canvas, {root:'controller/action'})` "+
+                      "or redirect explicitly with "+
+                        "`context.redirectTo('controller/action')`");
+    },
+    
+    /**
+     * Jax.RouteSet#map(path, controller) -> undefined
+     * 
+     * Sets up routing so that the specified name points to the given controller class.
+     * Action names are not looked up until a call to #recognizeRoute is received.
+     * This way, actions can be added to the controller's prototype at any time.
+     **/
+    map: function(path, controller) {
+      if (!path) throw new Error("path is required");
+      var parts = path.split(/\//);
+      var controller_name = parts[0];
+
+      this._map[controller_name.toLowerCase()] = controller;
+
+      if (!Jax.views.exists(controller_name+"/index"))
+        Jax.views.push(controller_name+"/index", function() {
+          this.glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
+          this.world.render();
+        });
+    },
+    
+    /**
+     * Jax.RouteSet#getControllerNames() -> Array
+     *
+     * Returns an array of controller names registered with this route set.
+     **/
+    getControllerNames: function() {
+      return Jax.Util.properties(this._map);
+    },
+    
+    /**
+     * Jax.RouteSet#recognizeRoute(path) -> Object
+     * - path (String): the route path to be recognized
+     * 
+     * Recognizes the specified path, returning an object with properties
+     * 'controller' and 'action'. If the route cannot be recognized, an
+     * error is thrown.
+     *
+     * The route path can be either the name of the controller, or
+     * the format 'controller_name/action_name'. Examples:
+     *
+     *     'welcome'        => {controller:WelcomeController, action:'index'}
+     *     'welcome/index'  => {controller:WelcomeController, action:'index'}
+     *     'welcome/about'  => {controller:WelcomeController, action:'about'}
+     *
+     **/
+    recognizeRoute: function(path) {
+      var parts = path.split(/\//);
+      if (parts.length > 2 || parts.length == 0)
+        throw new Error("Invalid path format. String should look like 'controller/action'.");
+      var controller_name = parts[0];
+      var action_name = parts[1] || "index";
+      
+      var controller_class = this._map[controller_name.toLowerCase()];
+      if (!controller_class || !controller_class.prototype)
+        throw new Error("Route not recognized: '"+path+"' (controller not found)");
+        
+      if (!controller_class.prototype[action_name])
+        throw new Error("Invalid action name '"+action_name+"' for controller '"+controller_name+"'.\n\n"+
+                        "Valid action names: "+JSON.stringify(Jax.Util.properties(controller_class.prototype)));
+      
+      return {
+        controller: controller_class,
+        action: action_name
+      };
+    },
+
+    /**
+     * Jax.RouteSet#isRouted(path) -> Boolean
+     * - path (String): the route path to be recognized
+     * 
+     * Returns true if the specified path can be routed, false otherwise.
+     **/
+    isRouted: function(path) {
+      return !!self._map[path];
+    },
+
+    /**
+     * Jax.RouteSet#dispatch(path) -> Jax.Controller
+     * - path (String): the route path to be recognized
+     * 
+     * Recognizes the given path as a route and invokes its controller and action.
+     * After the controller has been invoked, the controller instance itself is
+     * returned.
+     **/
+    dispatch: function(path, context) {
+      var route = this.recognizeRoute(path);
+      
+      return route.controller.invoke(route.action, context);
+    }
+  });
+})();

data/lib/assets/javascripts/jax/mvc/view.js

@@ -0,0 +1,43 @@
+/**
+ * class Jax.View
+ * 
+ * Provides a container class around which View functions can be stored.
+ * 
+ * This is useful because other parts of Jax will set up helper methods and
+ * delegation methods for a View to make use of.
+ * 
+ * For example, one of the most common tasks for a View is to clear the
+ * rendering canvas:
+ * 
+ *     this.glClear(GL_COLOR_BIT | GL_DEPTH_BUFFER_BIT);
+ *     
+ * The _glClear_ method is delegated into the Jax.Context associated with
+ * this view.
+ * 
+ * By default, in addition to all WebGL methods, the following delegates and
+ * properties are created by Jax:
+ * 
+ *   * *world*   - the instance of Jax.World that houses all of the objects in
+ *                 the scene
+ *   * *player*  - the instance of Jax.Player for this context containing information
+ *                 about the human user.
+ *   * *context* - the instance of Jax.Context that this view is associated with.
+ * 
+ **/
+Jax.View = (function() {
+  return Jax.Class.create({
+    initialize: function(view_func) {
+      this.view_func = view_func;
+    },
+    
+    /**
+     * Jax.View#render() -> Jax.View
+     *
+     * Renders this View. Returns itself.
+     **/
+    render: function() {
+      this.view_func();
+      return this;
+    }
+  });
+})();

data/lib/assets/javascripts/jax/mvc/view_manager.js

@@ -0,0 +1,65 @@
+/**
+ * class Jax.ViewManager
+ * 
+ * Maintains a registry of all Jax views and the paths to them.
+ **/
+Jax.ViewManager = (function() {
+  return Jax.Class.create({
+    initialize: function() {
+      this.views = {};
+    },
+
+    /**
+     * Jax.ViewManager#push(path, view) -> undefined
+     * - path (String): the view path to be stored
+     * - view (Function): a function to be called when rendering the view
+     * 
+     * If the path is already stored, the current one will be replaced.
+     **/
+    push: function(path, view) {
+      this.views[path.toLowerCase()] = view;
+    },
+    
+    /**
+     * Jax.ViewManager#get(path) -> Object
+     * - path (String): the view path to be returned.
+     * 
+     * Note that every call to this method produces a new instance of Jax.View,
+     * so be aware that this can cause efficiency problems and memory leaks
+     * if not handled appropriately.
+     **/
+    get: function(path) {
+      if (this.views[path.toLowerCase()])
+        return new Jax.View(this.views[path.toLowerCase()]);
+      else throw new Error("Could not find view at '"+path+"'!");
+    },
+
+    /** alias of: Jax.ViewManager#get
+     * Jax.ViewManager#find(path) -> Object
+     * - path (String): the view path to be returned.
+     * 
+     * Note that every call to this method produces a new instance of Jax.View,
+     * so be aware that this can cause efficiency problems and memory leaks
+     * if not handled appropriately.
+     **/
+    find: function(path) { return this.get(path); },
+    
+    /**
+     * Jax.ViewManager#remove(path) -> Object | undefined
+     * - path (String): the view path to be removed.
+     *
+     * Removes the specified view path and, if it existed to begin with, returns it.
+     * Otherwise undefined is returned.
+     **/
+    remove: function(path) { var result = this.views[path]; delete this.views[path]; return result; },
+    
+    /**
+     * Jax.ViewManager#exists(path) -> Boolean
+     *
+     * Returns true if a view exists for the specified view path, false otherwise.
+     **/
+    exists: function(path) {
+      return !!this.views[path];
+    }
+  });
+})();