Class: SFML::Animation

Inherits:
Object
  • Object
show all
Defined in:
lib/sfml/graphics/animation.rb

Overview

A frame-based animation that drives a Sprite's texture_rect over time. Pair it with a SpriteSheet or TextureAtlas.

sheet  = SFML::SpriteSheet.load("hero.png", frame_size: [32, 32])
walk   = sheet.animation(fps: 12, loop: true)

def update(dt)
walk.update(dt)
end

def draw
window.draw(walk.sprite)
end

Animation is a self-contained drawable — it builds its own internal Sprite and advances texture_rect on each #update. Use #sprite to access the current frame's Sprite for transform setters (position=, rotation=, etc.), or call Animation#draw_on(target) directly.

frames may be:

  • An Array of SFML::Rect — used as texture_rects in order.
  • An Array of Integer indexes paired with sprite_sheet:.
  • Constructed implicitly via SpriteSheet#animation or TextureAtlas#animation (see those classes).

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(source, frames:, fps: 12, loop: true) ⇒ Animation

Returns a new instance of Animation.

Parameters:

  • source (SpriteSheet, TextureAtlas, Texture) —

    backing image

  • frames (Array<SFML::Rect>) —

    texture rects to cycle through

  • fps (Numeric) (defaults to: 12) —

    frames per second

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

    restart at the end if true; pause if false

Raises:

  • (ArgumentError) 


33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
 
# File 'lib/sfml/graphics/animation.rb', line 33

def initialize(source, frames:, fps: 12, loop: true)
  raise ArgumentError, "Animation needs at least one frame" if frames.empty?

  texture =
    case source
    when Texture       then source
    when SpriteSheet,
         TextureAtlas  then source.texture
    else raise ArgumentError, "Animation source must be Texture / SpriteSheet / TextureAtlas"
    end

  @frames        = frames
  @frame_seconds = 1.0 / Float(fps)
  @loop          = loop
  @sprite        = Sprite.new(texture)
  @sprite.texture_rect = @frames.first
  @elapsed       = 0.0
  @frame_index   = 0
  @done          = false
end

Instance Attribute Details

#frame_index ⇒ Object (readonly)

The sprite, frame index components.



55
56
57
 
# File 'lib/sfml/graphics/animation.rb', line 55

def frame_index
  @frame_index
end

#sprite ⇒ Object (readonly)

The sprite, frame index components.



55
56
57
 
# File 'lib/sfml/graphics/animation.rb', line 55

def sprite
  @sprite
end

Instance Method Details

#color ⇒ Object

Returns the color.



127
128
 
# File 'lib/sfml/graphics/animation.rb', line 127

def color       = @sprite.color
# Set the color.

#color=(v) ⇒ Object

Set the color.



129
 
# File 'lib/sfml/graphics/animation.rb', line 129

def color=(v);    @sprite.color = v; end

#done? ⇒ Boolean

Returns whether the animation has reached the end (only meaningful for non-looping animations).

Returns:

  • (Boolean) 


59
 
# File 'lib/sfml/graphics/animation.rb', line 59

def done? = @done

#draw_on(target, states_ptr = nil) ⇒ Object

Drawable interface — forwards to the internal Sprite.



103
104
105
 
# File 'lib/sfml/graphics/animation.rb', line 103

def draw_on(target, states_ptr = nil)
  @sprite.draw_on(target, states_ptr)
end

#duration ⇒ Object

Total animation duration in seconds.



100
 
# File 'lib/sfml/graphics/animation.rb', line 100

def duration = @frames.size * @frame_seconds

#origin ⇒ Object

Returns the origin.



123
124
 
# File 'lib/sfml/graphics/animation.rb', line 123

def origin      = @sprite.origin
# Set the origin.

#origin=(v) ⇒ Object

Set the origin.



125
 
# File 'lib/sfml/graphics/animation.rb', line 125

def origin=(v);   @sprite.origin = v; end

#playing? ⇒ Boolean

true if playing.

Returns:

  • (Boolean) 


62
 
# File 'lib/sfml/graphics/animation.rb', line 62

def playing? = !@done

#position ⇒ Object

Transform passthroughs so callers can write anim.position = instead of anim.sprite.position =. The full surface of Sprite stays accessible via #sprite for advanced cases (color, scale_by, custom blend states, etc.).



111
112
 
# File 'lib/sfml/graphics/animation.rb', line 111

def position    = @sprite.position
# Set the position.

#position=(v) ⇒ Object

Set the position.



113
 
# File 'lib/sfml/graphics/animation.rb', line 113

def position=(v); @sprite.position = v; end

#reset ⇒ Object

Rewind to the first frame and clear the done flag.



91
92
93
94
95
96
97
 
# File 'lib/sfml/graphics/animation.rb', line 91

def reset
  @frame_index = 0
  @elapsed     = 0.0
  @done        = false
  @sprite.texture_rect = @frames.first
  self
end

#rotation ⇒ Object

Returns the rotation.



115
116
 
# File 'lib/sfml/graphics/animation.rb', line 115

def rotation    = @sprite.rotation
# Set the rotation.

#rotation=(v) ⇒ Object

Set the rotation.



117
 
# File 'lib/sfml/graphics/animation.rb', line 117

def rotation=(v); @sprite.rotation = v; end

#scale ⇒ Object

Returns the scale.



119
120
 
# File 'lib/sfml/graphics/animation.rb', line 119

def scale       = @sprite.scale
# Set the scale.

#scale=(v) ⇒ Object

Set the scale.



121
 
# File 'lib/sfml/graphics/animation.rb', line 121

def scale=(v);    @sprite.scale = v; end

#update(dt) ⇒ Object

Advance by dt (a SFML::Time or seconds Float). Updates the internal sprite's texture_rect to the current frame.



66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/sfml/graphics/animation.rb', line 66

def update(dt)
  return if @done

  seconds = dt.is_a?(Time) ? dt.as_seconds : Float(dt)
  @elapsed += seconds

  while @elapsed >= @frame_seconds
    @elapsed -= @frame_seconds
    @frame_index += 1
    if @frame_index >= @frames.size
      if @loop
        @frame_index = 0
      else
        @frame_index = @frames.size - 1
        @done = true
        break
      end
    end
  end

  @sprite.texture_rect = @frames[@frame_index]
  self
end