What It Is
The Divinity Engine is an ongoing experiment into the world of 3D graphics rendering. Based heavily on the Ruby on Rails framework, Divinity attempts to do for games what Rails has done for web sites: provide a robust, highly productive environment in which to write your applications.
Divinity provides a lot of the same things that Ruby on Rails brings to the table, largely because it's got a very similar initialization. (OK, yeah, most of the initialization was ripped directly from the Rails source.) For instance, internationalization is in place and works identically to Rails. There are three environments: development, production and test, which are used for similar purposes. Backtrace cleaners aren't quite ready to go, but they're in there waiting to be turned on. You can even declare gem dependencies and freeze them to your Divinity application.
The Divinity Engine follows a Model/View/Controller architecture, and so it should feel very similar to your average Ruby on Rails application. It also carries over the concept of plugins, allowing you to add common content from the community (though as of the this preliminary release, there's no “script/plugin”-like mechanism for installing plugins).
The latest source code can be cloned from github at github.com/sinisterchipmunk/divinity and I maintain a blog at www.divinityengine.com to periodically report on what's going on behind the scenes or make mention of some new functionality.
What It's Not
Divinity is not Rails. Let me be very clear on that. As much as is similar, at least that much is completely different. For instance, models are not based on ActiveRecord (though I'm trying to decide whether this would be a better approach, especially since SQLite can simply carry the database file with the application). They are based on the Resource class, which is entirely of my own design, and which loads the engine data from files.
The vast majority of Divinity does cater to Rails programmers, so that (hopefully) you can take most of the basic Rails idioms and conventions into Divinity. But you need to keep in mind that Divinity and Rails are not the same, and this is reflected under the hood. Behind the scenes, the two frameworks diverge almost instantaneously after the app has been initialized.
As of this release, Divinity is not complete. It is intended to become a full-fledged game engine, and at such time that it is ready to be considered “game-worthy,” a 1.0 release number will be applied. Until then, it's an MVC graphics engine. There's a camera, display lists, and a few of the minor ground-level details that might go into a game, but there currently aren't, for example, particle generators. There's no current support for sound (you need to program this yourself until it's officially implemented). The engine is still a baby, a pre-alpha at best, so be nice and play fair. It's not a magic wand, but, with your help, I hope to turn it into one.
Where To Start
Let's generate an application. I'll pretend I'm on a Windows box, but technically Divinity should run on any platform that supports its dependencies.
C:\projects> gem install divinity #=> installs the Divinity gem. C:\projects> divinity my_shiny_app #=> generates a new Divinity application, just like Rails. C:\projects> cd my_shiny_app C:\projects\my_shiny_app> my_shiny_app #=> the generated app is ready to run, so go ahead and give it a shot. C:\projects\my_shiny_app> rake doc #=> generate Divinity documentation C:\projects\my_shiny_app> script/generate controller world_map #=> let's generate a "world map" controller. C:\projects\my_shiny_app> script/generate model settlement #=> ...and a "Settlement" model.
That should at least give you an idea of how this thing works. You should see the generated documentation for more help.
Like Rails, the Divinity Engine automatically generates unit and functional tests for you. Functional tests actually instantiate the engine (run the program), switch to whatever controller, fire whatever action, and run whatever is in your test code. That code gets run every frame for a set amount of time (defaulting to 1 second to keep the tests moving at a decent speed). You can, of course, stop this early if you need to test something that should only run once.
Unit tests are generated when you create a new model, and are very similar to Rails model unit tests.
Currently, fixtures are not implemented. I started to write them, but I realized that they were essentially just more of Resources (see the Resource class documentation for information on them) and, since Divinity (currently) doesn't make use of any database, it'd just be redundant data and a more confusing framework. So I left them out. I promise, if I make the switch to ActiveRecord (I'd welcome feedback on this, by the way), fixtures will be brought into the mix.
Note on Patches/Pull Requests
Fork the project.
Make your feature addition or bug fix.
Add tests for it. This is important so I don't break it in a future version unintentionally.
Commit, do not mess with rakefile, version, or history. (If you want to have your own version, that's fine, but bump version in a commit by itself so I can ignore it when I pull)
Send me a pull request. Bonus points for topic branches.
The documentation is more sparse at the moment than I want it to be. I'm working on it, I promise.
I think it's basically compatible with Ruby 1.9, but I can't test it because I can't get Rmagick installed on my box. I plan to revisit that issue shortly.
Copyright © 2010 Colin MacKenzie IV. See LICENSE for details.