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