ruby-warrior: Learn Ruby by Writing an AI for a Tower-Climbing Game

What ruby-warrior Is and Who It Targets

ruby-warrior is a game where the player writes Ruby code, not a game where the player plays with standard controls. You install the gem, initialize a profile, and then edit a single Ruby file called player.rb to instruct the warrior what to do on each turn. The README describes the goal as 'a game designed to teach the Ruby language in a fun and interactive way.' The audience is someone who knows enough Ruby to write a class with a method but has not yet worked with conditionals, state, or object method calls in a real program. The game forces you to learn by failing: if your warrior loses all health, you revise player.rb and try again. There is no feedback loop other than the game output. The gem runs from the command line using the rubywarrior command.

How the Turn-Based Game Loop Works

Each floor of the tower runs as a series of turns. On every turn, the game calls your play_turn method with a warrior object as the argument. You examine the warrior's surroundings with senses, choose an action, and the game advances one step. You cannot change your code during a level. The warrior must be given enough logic up front to survive whatever the floor contains. The README explains this design directly: 'You must give the Warrior enough artificial intelligence up-front to find his own way.' When the warrior reaches the stairs, the floor is complete. Losing all health fails the level. There is no penalty for failure beyond needing to fix the code and replay the level. The README's example of a simple warrior makes the loop concrete: call feel to sense the adjacent space, call enemy? on the space to check for an enemy, then call attack! or walk! based on the result.

Installing and Starting the Game

Installation uses the standard gem command:

gem install rubywarrior

After installation, run the rubywarrior command to create a profile. This places a rubywarrior directory in the current working location with a profile subdirectory containing player.rb. The initial player.rb contains:

class Player
  def play_turn(warrior)
    # your code goes here
  end
end

Fill in play_turn and run rubywarrior again to play the level. Each level's available abilities are listed in a README file inside the profile directory, updated automatically as levels advance. The README notes that as of version 0.2.0, the gem works with Ruby 3.3; if running an older Ruby version, an older gem version may be required.

Actions, Senses, and the Space API

Actions end with an exclamation mark and change the game state. Only one action can be taken per turn. The core actions from the README are: walk! (move in a direction, forward by default), attack! (attack the adjacent unit), rest! (recover 10% of max health), bind! (immobilize an adjacent unit), and rescue! (free a captive, earning 20 points). Senses return information without consuming the action. feel returns a Space object for the given direction. health returns an integer. distance returns the number of spaces to the stairs. listen returns an array of all spaces containing units. Space objects expose methods like empty?, stairs?, enemy?, captive?, wall?, ticking?, and golem?. The ticking? method detects a bomb. Because one turn only allows one action, handling multiple priorities (rescuing a captive while an enemy approaches from another direction) requires state management across turns. The README recommends recording sensed information to track changes between turns, such as detecting when health has decreased to infer an attack.

Scoring, Epic Mode, and Replay

Reaching the stairs is the minimum goal; maximizing score requires more. The README's scoring system awards points for defeating enemies (their max health added to your score), rescuing captives (20 points each), finishing within the bonus time (remaining bonus time added to score), and clearing the floor completely (a 20% overall bonus for defeating all enemies and rescuing all captives). A total score accumulates across all levels. After reaching the top of the tower, the player can re-run the entire tower in what the README calls Epic Mode, where the goal is to replay all levels and optimize the warrior's strategy for the highest total score. This replay loop encourages more careful programming than the first run, where just reaching the stairs on each level is sufficient. The README's advice is explicit: 'Don't be too concerned about scoring perfectly in the beginning.' The level map representation in the README shows the floor layout using ASCII characters where @ is the warrior, > is the stairs, s is a Sludge enemy, S is a Thick Sludge enemy, and C is a captive. Understanding the map format helps when planning how the warrior should handle each encounter.

The Golem: Controlling a Second Unit

Some levels unlock the ability to create a golem, a separate unit that the player also controls. The golem's turn logic is defined in a block:

warrior.form! do |golem|
  golem.attack! if golem.feel.enemy?
end

Complex golem logic can be moved into its own class. Multiple golems can be created per level, but the README notes a specific cost: each golem created takes half of the warrior's max health. Creating multiple golems is therefore a trade-off between having additional controlled units and reducing the warrior's survivability. The golem follows the same actions and senses API as the warrior, so skills learned for the warrior transfer directly. The Space API's golem? method lets the warrior detect whether a golem is occupying a given space, which matters when the warrior and golem need to coordinate movement on the floor.

Maintenance Status and Alternatives

The last push to the ruby-warrior repository was on 2024-03-27. The README notes that version 0.2.0 added Ruby 3.3 compatibility, so the gem runs on current Ruby. No new levels, features, or framework changes should be expected. The README itself has not been updated with new content; the tower structure (floors, enemies, captives, scoring rules) is fixed. For developers who want a similar concept with more active development, Exercism is an alternative: it offers Ruby tracks with practice exercises and community feedback, though it does not use the same game metaphor. CodinGame is another option for code-based games, supporting Ruby among many languages, though its exercises are not specifically Ruby tutorials. ruby-warrior's distinctive value is the single-file, turn-based simulation model that requires no external service.

Editorial conclusion

ruby-warrior is a good starting point for programmers who want to learn Ruby through concrete problems rather than exercises. Each floor forces you to write Ruby code that handles real conditionals, sense the environment, and maintain state across turns. The game has not had a commit since 2024-03-27. Version 0.2.0 added Ruby 3.3 support, according to the README. Expect no new levels or framework updates: this is a complete, self-contained learning artifact.

Frequently asked questions

Official sources

1. Official README
2. Project repository