fantasy 0.1.13 → 0.1.17

data/lib/fantasy/background.rb

@@ -1,9 +1,90 @@
+# frozen_string_literal: true
+
+# Represents on static image that will be rendered on every frame.
+# Replicable (by default).
+# The position is relative to `Camera.main`.
+# ```
+# on_game do
+#   background = Background.new(image_name: "beach")
+#   # background.replicable = false # if you don't want the image to replicate
+#   background.scale = 6
+# end
+# ```
 class Background
-  attr_accessor :scale, :color, :visible, :position, :layer, :replicable
 
+  # In which layer the image of the Background is rendered.
+  # Smaller numbers are rendered behind higher numbers.
+  #
+  # Default `-100`.
+  #
+  # @example Set layer
+  #   background = Background.new("image")
+  #   background.layer = -50
+  attr_accessor :layer
+
+
+  # Coordinates object where x and y represent the position of the Background in the World
+  # (no necessarily in the Screen).
+  #
+  # Default `Coordinates.zero`.
+  #
+  # @example Setting position
+  #   background = Background.new("image")
+  #   background.position = Coordinates.new(10, 20)
+  #   background.position.x # => 10
+  #
+  # @example Modify position
+  #   background.position.x +=  1
+  #   background.position.x # => 11
+  attr_accessor :position
+
+  # [Boolean] When `true` the image will replicate itself to cover all the screen. Default `true`.
+  #
+  # Default `true`.
+  #
+  # @example Setting replicable
+  #   background = Background.new("image")
+  #   background.replicable = false
+  attr_accessor :replicable
+
+  # The value to scale the image of the Background when drawn.
+  # If the value is `2` the image will rendered at double of size.
+  # If the value is `0.5` the image will rendered at half of size.
+  #
+  # @note this value affects the attributes `width` and `height`
+  #
+  # Default `1`.
+  #
+  # @example Set scale
+  #   background = Background.new("image")
+  #   background.scale = 6
+  attr_accessor :scale
+
+  # When `false` the Background won't be rendered in the next frame.
+  #
+  # Default `true`.
+  #
+  # @example Set visible
+  #   background = Background.new("image")
+  #   background.visible = false
+  attr_accessor :visible
+
+  # Generates an Background with all the below default values:
+  # - **position**: `Coordinates.zero`.
+  # - **scale**: `1`.
+  # - **draggable_on_debug**: `true`.
+  # - **layer**: `-100`.
+  # - **image**: The Image generated by `image_name`
+  # - **name**: Same as `image_name`
+  # - **visible**: `true`
+  # - **replicable**: `true`
+  #
+  # @param image_name [string] the name of the image file from `./images/*`
+  # @return [Background] the Background
+  # @example Instantiate a new Background
+  #   background = Background.new("background")
   def initialize(image_name:)
     @image = Image.new(image_name)
-    @name = image_name
     @position = Coordinates.zero
     @scale = 1
     @visible = true
@@ -15,18 +96,19 @@ class Background
     Global.backgrounds.push(self)
   end
 
+  # @return [Fixnum] the Background width in pixels
   def width
-    @image.width() * @scale
+    @image.width * @scale
   end
 
+  # @return [Fixnum] the Background height in pixels
   def height
-    @image.height() * @scale
+    @image.height * @scale
   end
 
-  def position_in_camera
-    @position - Global.camera.position
-  end
+  # rubocop:disable Style/GuardClause
 
+  # @!visibility private
   def draw
     if @visible
       if @replicable
@@ -36,18 +118,31 @@ class Background
       end
     end
   end
+  # rubocop:enable Style/GuardClause
 
-  def draw_normal
-    @image.draw(x: position_in_camera.x, y: position_in_camera.y, scale: @scale)
+  # Destroy this Background and it will not longer be rendered
+  #
+  # @example Destroy a Background
+  #   background = Background.new("background")
+  #   background.destroy
+  def destroy
+    Global.backgrounds.delete(self)
+  end
+
+  private
+
+  def position_in_camera
+    @position - Camera.main.position
   end
 
   # Camera relative Tiles
+  # rubocop:disable Metrics/AbcSize
   def draw_replicable
     tiles_delta_x = (position_in_camera.x % width) - width
     tiles_delta_y = (position_in_camera.y % height) - height
 
-    tiles_needed_horizontal = ((SCREEN_WIDTH - (tiles_delta_x + width)) / width.to_f).ceil + 1
-    tiles_needed_vertical = ((SCREEN_HEIGHT - (tiles_delta_y + height)) / height.to_f).ceil + 1
+    tiles_needed_horizontal = ((Global.screen_width - (tiles_delta_x + width)) / width.to_f).ceil + 1
+    tiles_needed_vertical = ((Global.screen_height - (tiles_delta_y + height)) / height.to_f).ceil + 1
 
     tiles_needed_horizontal.times do |index_horizontal|
       tiles_needed_vertical.times do |index_vertical|
@@ -55,8 +150,9 @@ class Background
       end
     end
   end
+  # rubocop:enable Metrics/AbcSize
 
-  def destroy
-    Global.backgrounds.delete(self)
+  def draw_normal
+    @image.draw(x: position_in_camera.x, y: position_in_camera.y, scale: @scale)
   end
 end

data/lib/fantasy/base.rb

@@ -1,60 +1,172 @@
+# frozen_string_literal: true
+
+# Here there are all the methods that can be used in the root level
+
 Global.setup_proc = nil
 Global.loop_proc = nil
 
+# Defines the presentation Scene
+#
+# ```
+# 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
+# ```
 def on_presentation(&block)
   Global.presentation_proc = block
 end
 
+# Defines the game Scene
+#
+# ```
+# on_game do
+#   # [...]
+#   if player.dead
+#     Global.go_to_end
+#   end
+# end
+# ```
 def on_game(&block)
   Global.game_proc = block
 end
 
+# Defines the end Scene
+#
+# ```
+# 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
+# ```
 def on_end(&block)
   Global.end_proc = block
 end
 
+# @!visibility private
 def on_setup(&block)
   Global.setup_proc = block
 end
 
+# Executes on every frame. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_loop do
+#     Global.references.time = Time.at(Global.seconds_in_scene).utc.strftime("%M:%S")
+#   end
+# end
+# ```
 def on_loop(&block)
   Global.loop_proc = block
 end
 
+# @!visibility private
 def on_button(&block)
   Global.button_proc = block
 end
 
+# Triggered any time space bar key is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_space_bar do
+#     shoot_gun # for example
+#   end
+# end
+# ```
 def on_space_bar(&block)
   Global.space_bar_proc = block
 end
 
+# Triggered any time cursor up key is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_cursor_up do
+#     look_ups # for example
+#   end
+# end
+# ```
 def on_cursor_up(&block)
   Global.cursor_up_proc = block
 end
 
+# Triggered any time cursor down key is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_cursor_down do
+#     look_down # for example
+#   end
+# end
+# ```
 def on_cursor_down(&block)
   Global.cursor_down_proc = block
 end
 
+# Triggered any time cursor left key is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_cursor_left do
+#     look_left # for example
+#   end
+# end
+# ```
 def on_cursor_left(&block)
   Global.cursor_left_proc = block
 end
 
+# Triggered any time cursor right key is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_cursor_right do
+#     look_right # for example
+#   end
+# end
+# ```
 def on_cursor_right(&block)
   Global.cursor_right_proc = block
 end
 
+# Triggered any time mouse left button is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_mouse_button_left do
+#     show_menu # for example
+#   end
+# end
+# ```
 def on_mouse_button_left(&block)
   Global.mouse_button_left_proc = block
 end
 
+# Triggered any time mouse right button is pressed. To be used inside one of the scene blocks (`on_presentation`, `on_game`, `on_end`)
+# ```
+# on_game do
+#   on_mouse_button_right do
+#     show_menu # for example
+#   end
+# end
+# ```
 def on_mouse_button_right(&block)
   Global.mouse_button_right_proc = block
 end
 
+# Starts the game. This method has to be called when all the desired scene blocks (`on_presentation`, `on_game`, `on_end`) have been declared.
+# ```
+# on_game do
+#   # do game stuff
+# end
+#
+# start!
+# ```
 def start!
+  raise "'SCREEN_WIDTH' and 'SCREEN_HEIGHT' both have to be set at the beginning of the program" unless defined?(SCREEN_WIDTH) && defined?(SCREEN_HEIGHT)
+
   Global.setup
-  Global.game = Game.new
+  Global.game = Game.new(SCREEN_WIDTH, SCREEN_HEIGHT)
   Global.game.show
 end

data/lib/fantasy/camera.rb

@@ -1,31 +1,115 @@
+# frozen_string_literal: true
+
+# Represents Coordinates of the camera and it affects the screen position of all Actors and Backgrounds.
+# There is only one active Camera and it is acceded by `Camera.main`. This Camera is initialized automatically
+# and it is already accessible. It can also be changed by another `Camera` instance.`
+#
+# @example Set the camera position
+#   Camera.main.position = Coordinates.new(0, 100)
+#
+# @example Camera follows player vertically
+#   on_game do
+#     player = Actor.new("image")
+#
+#     on_loop do
+#       Camera.main.position.y = player.position.y - (SCREEN_HEIGHT / 2)
+#     end
+#   end
+#
+# @example Switching between cameras
+#   camera_1 = Camera.new
+#   camera_2 = Camera.new(position: Coordinates.new(0, 10))
+#   Camera.main = camera_1
+#   Camera.main = camera_2
 class Camera
-  include MoveByCursor
 
-  attr_accessor :position, :direction, :speed
+  # Coordinates object where x and y represent the position of the Camera in the World (no necessarily in the Screen).
+  #
+  # Default `Coordinates.zero`.
+  #
+  # @return [Coordinates] the actual position
+  #
+  # @example Setting position
+  #   Camera.main.position = Coordinates.new(10, 20)
+  #   Camera.main.position.x # => 10
+  #
+  # @example Modify position
+  #   Camera.main.position.x +=  1
+  #   Camera.main.position.x # => 11
+  attr_accessor :position
+
+  # Controls the direction in which the Camera will move in the next frame.
+  #
+  # Default `Coordinates.zero`.
+  #
+  # @return [Coordinates] the actual direction
+  #
+  # @note The the pixels per second is represented by the `@speed` attribute
+  #
+  # @example Set direction
+  #   Camera.main.direction = Coordinates.right
+  attr_accessor :direction
+
+  # Controls the pixels per second which the Camera will move in the next frame.
+  #
+  # Default `0`.
+  #
+  # @return [Float] the actual speed
+  #
+  # @note The the direction is represented by the `@direction` attribute
+  #
+  # @example Set speed
+  #   Camera.main.speed = 10
+  attr_accessor :speed
 
+  # Generates a Camera with all the default attribute values
+  # @example Generate an Camera
+  #   camera = Camera.new
+  #   camera.position # => Coordinates.zero
+  #   camera.direction # => Coordinates.zero
+  #   camera.speed # => 0
+  #
+  # @param position [Coordinates] the initial position of the camera. Default `Coordinates.zero`
+  # @return [Camera] the Camera
   def initialize(position: Coordinates.zero)
     @position = position
     @direction = Coordinates.zero
     @speed = 0
-    @moving_with_cursors = false
     @on_after_move_callback = nil
   end
 
-  def move_with_cursors
-    @moving_with_cursors = true
-  end
-
+  # @!visibility private
   def move
-    calculate_direction_by_cursors if @moving_with_cursors
-
     if @direction != Coordinates.zero && !@speed.zero?
-      @position = @position + (@direction * @speed * Global.frame_time)
+      @position += (@direction * @speed * Global.frame_time)
     end
 
-    @on_after_move_callback.call unless @on_after_move_callback.nil?
+    @on_after_move_callback&.call
   end
 
+  # Triggered on every frame after the move has been executed
+  # @example Avoid Camera to move over limits
+  #   Camera.main.on_after_move do
+  #     if Camera.main.position.x > 100
+  #       Camera.main.position.x = 100
+  #     end
+  #   end
   def on_after_move(&block)
     @on_after_move_callback = block
   end
+
+  class << self
+    # @return [Camera] The active Camera
+    attr_accessor :main
+
+    # @!visibility private
+    def initialize
+      reset
+    end
+
+    # @!visibility private
+    def reset
+      @main = Camera.new
+    end
+  end
 end

data/lib/fantasy/clock.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 class Clock
   attr_accessor :persistent
   attr_reader :thread
@@ -29,9 +31,9 @@ class Clock
     times_executed = 0
     @thread =
       Thread.new do
-        while(times_executed < times)
+        while times_executed < times
           @block.call
-          times_executed += 1;
+          times_executed += 1
 
           seconds_to_sleep = seconds.is_a?(Range) ? rand(seconds) : seconds
           sleep(seconds_to_sleep)