Gemthief

A Ruby Roguelike Framework

Gemthief is a framework for building roguelike games using the Ruby programming language. Its architecture takes many cues from the Ruby on Rails web framework, in the sense that it establishes a strong set of conventions so that users can focus more on building their game. To that end, it makes heavy use of ActiveSupport, and takes many cues from Rails.

Installation

Add this line to your application's Gemfile:

gem 'gemthief'

And then execute:

$ bundle

Or install it yourself as:

$ gem install gemthief

Usage

There are three main 'components' of a Gemthief roguelike: Scenes, Views, and the Executive.

The Executive

The Executive is the "central hub" of your game- when you start your game, it initializes Curses, instantiates the initial_scene and its view, and then enters the main game loop.

During the main game loop, it gets input from the user and hands it off to the active_scene for processing. After that input is processed, it tells the scene to refresh its view, and then refreshes Curses.

# /game/executive.rb
#  An example Executive
class Executive < Gemthief::Executive
  initial_scene(:dungeon) do |scene|
    scene.generate_layout!
    scene.add_monsters!
  end
end

TODO: The Executive will also responsible for scene transitions. The planned structure for this is to have the /game/executive.rb file define a scene transition graph, which describes how the game transitions between different types of Scene. Then, after a Scene handles input, it can provide a signal (the name of an edge) to the Executive to request transitioning to another Scene.

(Roughly equivalent to Rails::Application)

Scenes

Scenes are your game's bread and butter. Scenes have two major responsibilities: handling input, and tracking their state.

Don't let the terminology fool you- while these are called Scenes, they don't just represent the 'gamelike' parts of your game- they can also represent menus (perhaps a class selection or an inventory screen). If you need a certain part of your game to handle input in a unique way AND/OR track its state independently, use a Scene.

Scenes consist of two lifecycle events:

• handle_input(input)
• render!

In the handle_input step, you should determine what the user wants to do and update your Scene's state accordingly. Then, in the render! step, you should manipulate your View to reflect that state. For example, if I received an 'h' input, the handle_input might update my hero's position, moving them one step to the left. Then, in render!, I would tell my view to update the screen with the hero's new coordinates.

Multiple instances of a particular Scene class are allowed- this is how we might, for instance, keep track of several 'floors' of a dungeon. Each floor would be an instance of some type of "FloorScene". However, only one scene instance is the "active scene" at any given time. Also note that Scene instances are persistent- you don't lose one Scene's state when you transition to another one.

TODO: Scenes might be responisble for too much. In the interest of not introducing too much abstraction, I'm making them responsible for both input interpretation and state tracking. While they're intentionally similar to Rails controllers, the range of allowable inputs is considerably larger and less standardized than Rails' RESTful actions. I'm not sure if I want to introduce a recommendation for state management (i.e. models) just yet. While this framework is sorta MVC, I haven't given the Model part much thought yet. TODO: Read up on desktop MVC/MVVM-type architectures TODO: Can scenes be responsible for both state management and input interpretation? Or should they dispatch off to persistent Models?

(Roughly equivalent to Rails controllers.)

Views

Views are responsible for updating the user interface so that it reflects the state of their associated Scene. View instances are always associated with a specific Scene instance.

An important note: Views should be stateless. During the transition into a Scene instance, the Executive creates a brand-new View instance for it. If you transition out of a Scene, the Executive will finalize it and detach it from the scene instance, creating a new View if/when the game transitions back.

(Roughly equivalent to Rails views)

License

The gem is available as open source under the terms of the MIT License.