Ruby in Fantasy

Simple toolbox library and lean API to build great mini games in Ruby.

An upper layer over Gosu library to offer a more friendly API for an easy and lean game development.

Specially intended to use Ruby as a learning language to introduce children into programming.

Attention: This project is in early development phase, right now it is just an experiment

Use

Hello World

require "fantasy"

SCREEN_WIDTH = 320
SCREEN_HEIGHT = 240

on_game do
  message = HudText.new(position: Coordinates.new(10, 10))
  message.text = "Hello, World!"
  message.size = "big"
end

start!

Action game

This is a full playable game. Maybe not too challenging though :)

# Add assets dependencies
# ./images/spaceship.<any>
# ./images/laser.<any>
# ./sounds/shoot.<any>
# ./sounds/impact.<any>
# ./sounds/game_over.<any>

require "fantasy"

SCREEN_WIDTH = 640
SCREEN_HEIGHT = 360

on_game do
  player = Actor.new("spaceship")
  player.position = Coordinates.new(100, 100)
  player.move_with_cursors
  player.speed = 100

  points = HudText.new(position: Coordinates.new(10, 20))
  points.text = 0

  10.times do
    enemy = Actor.new("enemy")
    enemy.position = Coordinates.new(rand * SCREEN_WIDTH, rand * SCREEN_HEIGHT)
  end

  on_space_bar do
    Sound.play("shoot")
    laser = Actor.new("laser")
    laser.position = player.position + Coordinates.new(0, -10)
    laser.speed = 400
    laser.direction = Coordinates.up
    laser.on_collision do |other|
      if other.name == "enemy"
        Sound.play("impact")
        other.destroy
        laser.destroy
        points.text += 1
      end
    end
  end

  player.on_collision do |other|
    if other.name == "enemy"
      Sound.play("game_over")
      Global.go_to_end
    end
  end
end

on_end do
  HudText.new(position: Coordinates.new(10, 100), text: "You are dead. Press space to re-tart")

  on_space_bar do
    Global.go_to_game
  end
end

start!

Examples

See the Ruby in Fantasy Games Collection. It is a collection of full playable games. For fun and for educational purposes.

Installation

Add this line to your application's Gemfile:

gem "fantasy"

And then execute:

$ bundle install

Or install it yourself as:

$ gem install fantasy

Features

Game Scenes

Easy to configure 3 basic game states:

Game presentation scene
Game game scene
Game end scene
Other scenes, like levels or such (TODO)

Each state should be independent and unique Actors and other elements can be created and configured for each state

Built-in mechanism to move from one state to another.

Actor

Managing game elements which have (optionally) image, movement and collision

Easy to set an image
Managing movement through direction and speed
Built-in movement control through cursors
Collision detection, OnCollision callback, Collision matrix
Jump
Gravity
Animations (TODO)
Possibility to extend Actor class or instantiate it directly for simple characters
Allowing magic instance properties (Like in OpenStruct). So programmer can do actor.stuff = 1 and it is valid (TODO)
Alignment "center" and "top-left" (TODO)

Clock

Create new execution threads to program delayed behaviors, repetitive actions, animations, ...

Run now
Run after a delay
Repeat
Stop
Callback when finished (TODO)

Animations

Add animations to an Actor and activate them when special state triggered

Set frames (TODO)
Duration in seconds (TODO)
Run once (TODO)
Run on loop (TODO)
Stop (TODO)
Callback when finished (TODO)

Events queue / Signals (TODO)

Inspiration from:

LÖVE
Godot

UI

Button (TODO)

Easy to set up a graphical component that responds to mouse hover and click events.

Set image (TODO)
Set image when hover (TODO)
Set image when clicked (TODO)
OnClicked callback (TODO)

HUD Elements

For easy creation of head-up display components.

Text Element
Image Element
Auto update text (observer variable changes) (TODO)

Debug Mode

Press d to activate it. When active debug visuals are shown:

Position
Collider

On top, when debug mode is active, the Actors and HUD elements become draggable. The new position won't be persistent but it will be helpful to identify which should be the desired position.

Camera

Setting up a camera component that we can easily move around and all the active Actors in the game will be rendered in the relative position to this camera.

Allow camera move
Easy to follow one actor

Colors palette

Not deal with RGB or anything, just a list of colors. See Color.palette

Pause Game (TODO)

Pause game, pause Actors, animations, clocks, ... (TODO)

Core run

Move the core functions to the top level hierarchy so I don't need to create a Game::Window class

Sound

Direct and easy way to play a sound
Direct and easy way to play a background music

Background

Simple way to set up:

Background color
Image background
Repeatable image background

Data Persistance

Simple mechanism to save data in disk. For user preferences, game progress, high scores and others

User Inputs

Easy access to keyboard and mouse inputs on any part of the code. Specially in the Actors.

Allow "on_space_bar" and each Actor (TODO)
Allow multiple "on_space_bar" (TODO)
Remove "on_space_bar" when changing scene (TODO)
Detect when key/mouse button is pressed in the actual frame in any part of the code (TODO)

Tilemap (TODO)

For easy creation of:

Top-down map levels
Platformer map levels (TODO)
Allow specific map keys like a=>actor_1, b=>actor_2 (TODO)

Tweens (TODO)

Multiple movement animation effects like in DoTween (TODO)

Externalized Variables (TODO)

Values that can be changed while the game is running. They can be in a Variables file. The game "watch" this file and update the variable in real time.

API

Game Scenes

Configure your game elements on each Scene:

SCREEN_WIDTH = 640
SCREEN_HEIGHT = 360

# (Optional)
on_presentation do
  # Game elements running when the game loads
end

# (Required)
on_game do
  # Game elements running when in game Scene
end

# (Optional)
on_end do
  # Game elements running when game is ended
end

How to go from Scene to Scene:

Global.go_to_presentation
Global.go_to_game
Global.go_to_end

Example

on_presentation do
  HudText.new(position: Coordinates.new(10, 100), text: "Press space to start")

  on_space_bar do
    Global.go_to_game
  end
end

on_game do
  # [...]
  if player.dead
    Global.go_to_end
  end
end

on_end do
  HudText.new(position: Coordinates.new(10, 100), text: "You are dead. Press space to re-tart")

  on_space_bar do
    Global.go_to_presentation
  end
end

Actor

Actor can be used directly:

player = Actor.new("warrior") # ./images/warrior.png
player.position = Coordinates.new(100, 100)
player.solid = true
player.speed = 200
player.layer = 1
player.move_with_cursors
player.collision_with = ["enemy", "bullets"] # default "all"

player.on_collision do |other|
  if other.name == "enemy"
    player.destroy
  end
end

player.on_after_move do
  if player.position.x > Global.screen_width
    player.position.x = Global.screen_width
  end

  if player.position.x < 0
    player.position.x = 0
  end
end

Or in a subclass:

class Player < Actor
  def initialize
    super("warrior") # ./images/warrior.png
    @position = Coordinates.new(100, 100)
    @solid = true
    @speed = 200
    @layer = 1
    @direction = Coordinates.zero
    @collision_with = ["enemy", "bullets"] # default "all"
    move_with_cursors
  end

  def on_collision_do(other)
    if other.name == "enemy"
      destroy
    end
  end

  def on_after_move_do
    if @position.x > SCREEN_WIDTH
      @position.x = SCREEN_WIDTH
    end

    if @position.x < 0
      @position.x = 0
    end
  end
end

Actor settings for a platformer:

player = Actor.new("warrior") # ./images/warrior.png
player.solid = true
player.jump = 150
player.gravity = 200
player.move_with_cursors(left: true, right: true, up: false, down: false, jump: true)

player.on_jumping do
  Sound.play("jump")
  player.image = "warrior_jump"
end

player.on_floor do
  player.image = "warrior"
end

Clock

clock =
  Clock.new do
    enemy.attack
    sleep(1)
    enemy.defend
  end

clock.run_now
clock.run_on(seconds: 2)
clock.repeat(seconds: 2, times: 10)
clock.stop

Background

# Simple color
on_presentation do
  Global.background = Color.new(r: 34, g: 35, b: 35)
end

# Replicable (by default) Image
# position is relative to Camera.main
on_game do
  background = Background.new(image_name: "beach")
  # background.repeat = false # if you don't want the image to replicate
  background.scale = 6
end

Data Persistance

Disk.data.records = [120_000, 11_000, 678]
Disk.data.last_level = 3
Disk.data.sound_volume = 12
Disk.save # data stored in ./disk/data.json

# ... in another session

Disk.data.records # => [120_000, 11_000, 678]
Disk.data.last_level # => 3
Disk.data.sound_volume # => 12

Camera

on_game do
  on_loop do
    # Camera follows player
    Camera.main.position.y = player.position.y - (SCREEN_HEIGHT / 2)
  end
end

Sound

Plays only once:

Sound.play("shoot") # ./sounds/shoot.wav

Plays in loop:

Music.play("music") # ./musics/music.mp3
Music.volume = 0.5
Music.stop

Tilemap

# ./maps/sky.txt
# 0     0
#  0  1
#   0   0
# 0    01

planet = Actor.new("planet")
star = Actor.new("star")
map = Tilemap.new(map_name: "sky", tiles: [planet, star], tile_size: 30)
map.spawn

UI

HUD Text

timer = HudText.new(position: Coordinates.new(SCREEN_WIDTH / 2, 10))
timer.text = 0
timer.alignment = "center"
timer.size = "big"

Clock.new { timer.text += 1 }.repeat(seconds: 1)

HUD Image

icon = HudImage.new(position: Coordinates.new(SCREEN_WIDTH - 220, 8), image_name: "ring")
icon.scale = 4
icon.visible = true

Clock.new { icon.visible = !icon.visible }.repeat(seconds: 1)

Credits for assets

Font: VT323 Project Authors (peter.hull@oikoi.com)

Bugs

When dragging in debug mode new elements are being added to the drag (TODO)
Rubocop is not passing
Tests are missing
Allow Ruby 2.5+

Assets

Images for the test fixtures: https://kenney.nl/

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/fguillen/fantasy.

Documentation

Generate the /docs folder with:

yard doc

License

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