Class: Ruby2D::Sprite

Inherits:
Object
  • Object
show all
Includes:
Renderable
Defined in:
lib/ruby2d/sprite.rb

Overview

Sprites are special images that can be used to create animations, kind of like a flip book. To create a sprite animation, first you’ll need an image which contains each frame of your animation.

Instance Attribute Summary collapse

Attributes included from Renderable

#color, #z

Instance Method Summary collapse

Methods included from Renderable

#add, #contains?, #remove

Constructor Details

#initialize(path, atlas: nil, show: true, width: nil, height: nil, x: 0, y: 0, z: 0, rotate: 0, color: nil, colour: nil, opacity: nil, loop: false, time: 300, animations: {}, default: 0, clip_x: 0, clip_y: 0, clip_width: nil, clip_height: nil) ⇒ Sprite

Create a sprite via single image or sprite-sheet.

Parameters:

  • path (#to_s) —

    The location of the file to load as an image.

  • width (Numeric) (defaults to: nil) —

    The width of drawn image, or default is width from image file

  • height (Numeric) (defaults to: nil) —

    The height of drawn image, or default is height from image file

  • x (Numeric) (defaults to: 0)
  • y (Numeric) (defaults to: 0)
  • z (Numeric) (defaults to: 0)
  • rotate (Numeric) (defaults to: 0) —

    Angle, default is 0

  • color (Numeric) (defaults to: nil) —

    (or colour) Tint the image when rendering

  • opacity (Numeric) (defaults to: nil) —

    Opacity of the image when rendering

  • show (Boolean) (defaults to: true) —

    If true the image is added to Window automatically.

  • loop (Boolean) (defaults to: false) —

    Sets whether animations loop by default when played (can be overridden by play method)

  • time (Numeric) (defaults to: 300) —

    The default time in millisecond for each frame (unless overridden animation within frames)

  • animations (Hash{String => Range}, Hash{String=>Array<Hash>}) (defaults to: {}) —

    Sprite sheet map to animations using frame ranges or individual frames

  • default (Numeric) (defaults to: 0) —

    The default initial frame for the sprite

  • clip_x (Numeric) (defaults to: 0)
  • clip_x (Numeric) (defaults to: 0)
  • clip_width (Numeric) (defaults to: nil)
  • clip_height (Numeric) (defaults to: nil) 


34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/ruby2d/sprite.rb', line 34

def initialize(path, atlas: nil, show: true, width: nil, height: nil,
               x: 0, y: 0, z: 0, rotate: 0, color: nil, colour: nil, opacity: nil,
               loop: false, time: 300, animations: {}, default: 0,
               clip_x: 0, clip_y: 0, clip_width: nil, clip_height: nil)
  @path = path.to_s

  # Coordinates, size, and rotation of the sprite
  @x = x
  @y = y
  @z = z
  @rotate = rotate
  self.color = color || colour || 'white'
  self.color.opacity = opacity unless opacity.nil?

  # Dimensions
  @width  = width
  @height = height

  # Flipping status
  @flip = nil

  # Animation attributes
  @loop = loop
  @frame_time = time
  @animations = animations
  @current_frame = default

  _setup_texture_and_clip_box atlas, clip_x, clip_y, clip_width, clip_height
  _setup_animation

  # Add the sprite to the window
  add if show
end

Instance Attribute Details

#clip_height ⇒ Object

Returns the value of attribute clip_height.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def clip_height
  @clip_height
end

#clip_width ⇒ Object

Returns the value of attribute clip_width.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def clip_width
  @clip_width
end

#clip_x ⇒ Object

Returns the value of attribute clip_x.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def clip_x
  @clip_x
end

#clip_y ⇒ Object

Returns the value of attribute clip_y.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def clip_y
  @clip_y
end

#data ⇒ Object

Returns the value of attribute data.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def data
  @data
end

#height ⇒ Object

Returns the value of attribute height.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def height
  @height
end

#loop ⇒ Object

Returns the value of attribute loop.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def loop
  @loop
end

#path ⇒ Object (readonly)

Returns the value of attribute path.



11
12
13
 
# File 'lib/ruby2d/sprite.rb', line 11

def path
  @path
end

#rotate ⇒ Object

Returns the value of attribute rotate.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def rotate
  @rotate
end

#width ⇒ Object

Returns the value of attribute width.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def width
  @width
end

#x ⇒ Object

Returns the value of attribute x.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def x
  @x
end

#y ⇒ Object

Returns the value of attribute y.



12
13
14
 
# File 'lib/ruby2d/sprite.rb', line 12

def y
  @y
end

Instance Method Details

#draw(x:, y:, width: (@width || @clip_width), height: (@height || @clip_height), rotate: @rotate, clip_x: @clip_x, clip_y: @clip_y, clip_width: @clip_width, clip_height: @clip_height, color: [1.0, 1.0, 1.0, 1.0]) ⇒ Object

Parameters:

  • width (Numeric) (defaults to: (@width || @clip_width)) —

    The width of drawn image

  • height (Numeric) (defaults to: (@height || @clip_height)) —

    The height of drawn image

  • x (Numeric)
  • y (Numeric)
  • rotate (Numeric) (defaults to: @rotate) —

    Angle, default is 0

  • color (Numeric) (defaults to: [1.0, 1.0, 1.0, 1.0]) —

    (or colour) Tint the image when rendering

  • clip_x (Numeric) (defaults to: @clip_x)
  • clip_x (Numeric) (defaults to: @clip_x)
  • clip_width (Numeric) (defaults to: @clip_width)
  • clip_height (Numeric) (defaults to: @clip_height) 


182
183
184
185
186
187
188
189
190
191
192
193
194
195
 
# File 'lib/ruby2d/sprite.rb', line 182

def draw(x:, y:, width: (@width || @clip_width), height: (@height || @clip_height), rotate: @rotate,
         clip_x: @clip_x, clip_y: @clip_y, clip_width: @clip_width, clip_height: @clip_height,
         color: [1.0, 1.0, 1.0, 1.0])

  Window.render_ready_check
  render(x: x, y: y, width: width, height: height, color: Color.new(color), rotate: rotate, crop: {
           x: clip_x,
           y: clip_y,
           width: clip_width,
           height: clip_height,
           image_width: @img_width,
           image_height: @img_height
         })
end

#elapsed_time ⇒ Object

Calculate the time in ms



134
135
136
 
# File 'lib/ruby2d/sprite.rb', line 134

def elapsed_time
  (Time.now.to_f - @start_time) * 1000
end

#flip_sprite(flip) ⇒ Object

Flip the sprite

Parameters:

  • flip (nil, :vertical, :horizontal, :both) —

    Direction to flip the sprite if desired



102
103
104
105
106
107
108
109
110
111
 
# File 'lib/ruby2d/sprite.rb', line 102

def flip_sprite(flip)
  # The sprite width and height must be set for it to be flipped correctly
  if (!@width || !@height) && flip
    raise Error,
          "Sprite width/height required to flip; occured playing animation `:#{@playing_animation}`
           with image `#{@path}`"
  end

  @flip = flip
end

#play(animation: :default, loop: nil, flip: nil, &done_proc) ⇒ Object

Start playing an animation

Parameters:

  • animation (String) (defaults to: :default) —

    Name of the animation to play

  • loop (Boolean) (defaults to: nil) —

    Set the animation to loop or not

  • flip (nil, :vertical, :horizontal, :both) (defaults to: nil) —

    Direction to flip the sprite if desired



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/ruby2d/sprite.rb', line 72

def play(animation: :default, loop: nil, flip: nil, &done_proc)
  unless @playing && animation == @playing_animation && flip == @flip
    @playing = true
    @playing_animation = animation || :default
    @done_proc = done_proc

    flip_sprite(flip)
    _reset_playing_animation

    loop = @defaults[:loop] if loop.nil?
    @loop = loop ? true : false

    set_frame
    restart_time
  end
  self
end

#reset_clipping_rect ⇒ Object

Reset frame to defaults



114
115
116
117
118
119
 
# File 'lib/ruby2d/sprite.rb', line 114

def reset_clipping_rect
  @clip_x      = @defaults[:clip_x]
  @clip_y      = @defaults[:clip_y]
  @clip_width  = @defaults[:clip_width]
  @clip_height = @defaults[:clip_height]
end

#restart_time ⇒ Object

Restart the timer



139
140
141
 
# File 'lib/ruby2d/sprite.rb', line 139

def restart_time
  @start_time = Time.now.to_f
end

#set_frame ⇒ Object

Set the position of the clipping retangle based on the current frame



122
123
124
125
126
127
128
129
130
131
 
# File 'lib/ruby2d/sprite.rb', line 122

def set_frame
  frames = @animations[@playing_animation]
  case frames
  when Range
    reset_clipping_rect
    @clip_x = @current_frame * @clip_width
  when Array
    _set_explicit_frame frames[@current_frame]
  end
end

#stop(animation = nil) ⇒ Object

Stop the current animation and set to the default frame



91
92
93
94
95
96
97
98
 
# File 'lib/ruby2d/sprite.rb', line 91

def stop(animation = nil)
  return unless !animation || animation == @playing_animation

  @playing = false
  @playing_animation = @defaults[:animation]
  @current_frame = @defaults[:frame]
  set_frame
end

#update ⇒ Object

Update the sprite animation, called by render



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/ruby2d/sprite.rb', line 144

def update
  return unless @playing

  # Advance the frame
  unless elapsed_time <= (@frame_time || @defaults[:frame_time])
    @current_frame += 1
    restart_time
  end

  # Reset to the starting frame if all frames played
  if @current_frame > @last_frame
    @current_frame = @first_frame
    unless @loop
      # Stop animation and play block, if provided
      stop
      if @done_proc
        # allow proc to make nested `play/do` calls to sequence multiple
        # animations by clearing `@done_proc` before the call
        kept_done_proc = @done_proc
        @done_proc = nil
        kept_done_proc.call
      end
    end
  end

  set_frame
end