Jax application hierarchy - sinisterchipmunk/jax GitHub Wiki

Jax is an MVC framework. That means it follows a strict programming paradigm: Model, View, Controller.

app/models/

The model is where most of the business logic goes. Models encapsulate nearly all data in a Jax application, particularly as it pertains to objects within the WebGL world. If you are designing a game that includes Grog, the Half-Orc Barbarian, then you'll likely have a model called HalfOrc. The model determines what Grog looks like and the rules governing his behavior (such as when to attack).

  • It is considered best practice to keep the vast majority of your "business logic" within models. Models are the least dependent upon the rest of the system, and this makes them the easiest to write tests for. Leave the views for showing the current state of your applications, and leave the controllers for scene setup and high-level "administrative" work. Let your models handle the nitty-gritty.

app/views/

The view deals strictly with the presentation level. In Jax, views are generated for you and you'll rarely have to modify them, because you'll virtually always want to just clear the screen and draw the next frame. However, it's worth noting that they exist (in the app/views directory) so that you can change them if you need to.

  • A view is processed each and every frame -- roughly 60 times per second, ideally. If you stick to the MVC paradigm and use the view only for rendering and related functions, this shouldn't be a problem. But if you break out of the paradigm and start, say, using the view to prompt for a user's first name, then you may find yourself less than pleased with the result.

app/controllers/

The controller is in charge of setting up the scene and dealing with the end user (e.g. via mouse clicks). A lot of work has gone into making Jax controllers intuitive and concise, while separating them from the data that they require.

app/resources/

There's one more major component of Jax that we haven't yet discussed: resources. These represent the pure data behind your models. Ruby on Rails would store this information in a database; Jax stores it on your file system (in app/resources). Grog, the Half-Orc Barbarian would probably have a resource entry looking a bit like this:

# in file app/resources/half_orc/grog.yml
character_class: Barbarian
mesh: "/path/to/barbarian.json"
attack_damage: 100

Jax is smart enough to figure out from the file name that it's going to use a HalfOrc model called "grog".

app/helpers/

Every time you generate a new controller, Jax will also generate a new helper. Usually, these will be empty and you're free to safely delete them if you feel a compulsion to do so. Helpers simply give you a place to put small JavaScript functions that don't particularly belong anywhere else. They let you keep your code clean and expressive by abstracting the weird, mundane and/or hard-to-read bits.

config/

When an application is generated, Jax stores some meta data about the project in this directory.

pkg/

When you're ready to ship your application, run rake package. Doing so will generate a file called app_name.js in the pkg directory, where app_name is the name of your Jax application.

public/

Here you can store static files such as images, 3D models, and so forth.

script/

Stores the Jax script used for generating controllers, models, resources, et cetera.

spec/javascripts/

Stores your unit tests:

  • spec/javascripts/controllers
    • Place tests for your controllers here.
  • spec/javascripts/helpers
    • Place tests for your helper functions here.
  • spec/javascripts/models
    • Place tests for your models here.
  • spec/javascripts/resources
    • If you wish, you may place tests for your resources here. However, you'll just be validating that the data you set is the data you receive. Useful if you suspect a bug in Jax itself (which may be preventing your model from loading properly), but kind of redundant for anything else.
  • spec/javascripts/support
    • Stores some configuration information for Jasmine. You can customize the HTML template for the test suite, and set some other Jasmine-specific options.

tmp/

Stores files generated by Jax. These files are frequently replaced and store intermediary data such as the JavaScript code that converts your resources into usable objects. Examine these files if you wish, but don't bother modifying them -- you'll lose any changes you make.

Gemfile

Basically pulls Jax into the application. If you need to rely on other Ruby libraries, you can place them here. See Bundler at http://gembundler.com for more information.

Gemfile.lock

Used by Bundler to manage your Ruby dependencies.

Rakefile

Loads the Jax and Jasmine rake tasks used by your application. Commands like rake jasmine invoke this file.