Class: TDD::Ease

Inherits:
Object
  • Object
show all
Defined in:
TDD Easing/tdd_ease_module.rb

Overview

Summary

This static class is used to apply an easing algorithm to an object's parameters over X amount of frames.

Easing methods can be extended through adding static methods to the Easing module. The default easing method is Easing::LINEAR and is identical to the default easing provided in VXAce

Version

1.0.9

Date

03/24/2015

Author

Galenmereth / Tor Damian Design <post@tordamian.com>

License

Free for non-commercial and commercial use. Credit greatly appreciated but not required. Share script freely with everyone, but please retain this description area unless you change the script completely. Thank you.

Changelog

1.0.9

  • Updated Game_CharacterBase extension to 1.0.4, fixing ease_moveto_char problems when using event ids

1.0.8

  • Added Ease.complete_easings_for with options.

  • Fixed overwrite bug, so that it checks for pointer uniqueness when comparing two easing targets.

1.0.7
1.0.6

Added support to use non-Hash objects directly as targets of easing. This is fully backwards compatible. Also added documentation for the delay option.

1.0.5

Added support for a delay in options hash. This makes the easing wait the specified x amount of frames before starting.

1.0.4

TDD Ease Object updated. Ease.from now works as intended. Fixed attribute origin setting to remove method check, since that is done in the easing module already.

1.0.3

Fixed @interpreter bug in Game_CharacterBase extension

1.0.2

Introduced the TDD module namespace and Ease_Object instead of using a hash

Constant Summary

@@easings = 
[]

Class Method Summary (collapse)

Class Method Details

+ (Object) clear_easings_for(args = {})

Clear all active easings for a target object

Parameters:

  • args (Hash) (defaults to: {}) —

    Options Hash

Options Hash (args):

  • :target (Object) —

    • The target Object to clear easings for

  • :perform_complete_call (Boolean) — default: false —

    • Whether to perform the complete call on each Ease_Object or not



230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'TDD Easing/tdd_ease_module.rb', line 230

def clear_easings_for(args={})
  args = {
    :target                => nil,
    :perform_complete_call => false
  }.merge(args)

  @@easings.each do |ease|
    @@easings.delete(ease) if ease.target.equal?(args[:target])
    if args[:perform_complete_call]
      ease.observers.each{|o| o.send(ease.call_on_complete, ease)} if ease.call_on_complete
    end
  end
end

+ (Object) complete_easings_for(target, perform_complete_call = false)

Complete easings for a target (or an array of targets). Skips directly to the last “frame” of transition.

Parameters:

  • target (Object, Array) —

    The target Object to complete easings for, or an Array of target Objects to complete easings for.

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

    Whether to call the :call_on_complete optional method on the target(s)



248
249
250
251
252
253
254
255
256
257
 
# File 'TDD Easing/tdd_ease_module.rb', line 248

def complete_easings_for(target, perform_complete_call=false)
  if target.is_a? Array
    target.each{|t| complete_easings_for(t, perform_complete_call)}
  else
    @@easings.select{|e| e.target == target}.each do |ease|
      ease.frames = 1
      perform_ease_for(ease)
    end
  end
end

+ (Ease_Object) from(target, frames, attributes = {}, options = {})

Note:

Functions like to, except eases from given attributes values to current target attribute values

Ease parameters from given attribute values to target's current attribute values

Parameters:

  • target (Object, Array) —

    An Object (or an Array of objects) which has the attributes listed in attributes and which you want to effect with an easing FROM its current values TO the values given in the attributes hash

  • frames (Integer) —

    The amount of frames to apply the easing over

  • attributes (Hash) (defaults to: {}) —

    Hash of attributes and target values for the attributes you wish to affect on the target object

  • options (Hash) (defaults to: {}) —

    Options Hash

Returns:

  • (Ease_Object) —

    ease_object - The created Ease_Object

See Also:



109
110
111
 
# File 'TDD Easing/tdd_ease_module.rb', line 109

def from(target, frames, attributes={}, options={})
  register_ease(:from, target, frames, attributes, options)
end

+ (Object) overwrite_other_easings(ease)

Note:

Overwrites (deletes) other Ease_Objects with the same target

Overwrite other ease queues for Ease_Objects with the same target

Parameters:

  • ease (Ease_Object) —

    The Ease_Object to search for like targets



213
214
215
216
217
218
219
220
221
222
223
 
# File 'TDD Easing/tdd_ease_module.rb', line 213

def overwrite_other_easings(ease)
  return unless ease.overwrite

  # Turn off overwrite from now for this ease
  ease.overwrite = false

  # Remove other ease with same target
  @@easings.each do |ease_to_delete|
    @@easings.delete(ease_to_delete) if ease_to_delete.target.equal?(ease.target) && ease_to_delete != ease
  end
end

+ (Object) perform_ease_for(ease)

Perform ease for Ease_Object

Parameters:

  • ease (Ease_Object) —

    The Ease_Object to advance the animation 1 frame tick



136
137
138
139
140
141
142
143
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
171
172
173
174
175
176
177
178
179
180
181
182
 
# File 'TDD Easing/tdd_ease_module.rb', line 136

def perform_ease_for(ease)
  # Initial setup of origin attributes
  ease.setup

  # Set local target var
  target = ease.target

  begin
    # Perform easing
    ease.attributes.each_pair do |attribute, value|
      attribute_origin = ease.attributes_origin[attribute]
      case ease.method
      when :to
        from = attribute_origin
        to = value
      when :from
        from = value
        to = attribute_origin
      end

      # Move instantly if frames is 1
      if ease.frames == 1
        value = to
      else
        value = Easing.send(ease.easing, ease.frame, from, to - from, ease.frames)
      end

      # Set the attribute on the target
      if target.is_a? Hash
        target[attribute] = value
      else
        target.send("#{attribute}=", value)
      end
    end

    ease.observers.each{|o| o.send(ease.call_on_update, ease)} if ease.call_on_update

    ease.frame += 1
    if ease.frame > ease.frames
      @@easings.delete(ease)
      ease.observers.each{|o| o.send(ease.call_on_complete, ease)} if ease.call_on_complete
    end
  rescue
    # Do not attempt to animate disposed items
    clear_easings_for(target: target) if target.class.method_defined?("disposed?") && target.disposed?
  end
end

+ (Ease_Object) register_ease(method, target, frames, attributes, options)

Register an Ease_Object in queue

Parameters:

  • method (Symbol) —

    (:to, :from) - The method to use

  • target (Object, Array) —

    An Object (or an Array of objects) which has the attributes listed in attributes and which you want to effect with an easing FROM its current values TO the values given in the attributes hash

  • frames (Integer) —

    The amount of frames to apply the easing over

  • attributes (Hash) —

    Hash of attributes and target values for the attributes you wish to affect on the target object

  • options (Hash) —

    Options Hash

Returns:

  • (Ease_Object) —

    ease_object - The created Ease_Object



189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'TDD Easing/tdd_ease_module.rb', line 189

def register_ease(method, target, frames, attributes, options)
  if target.is_a? Array
    target.each{|target| self.register_ease(method, target, frames, attributes, options)}
    return
  end
  
  ease = TDD::Ease_Object.new(method, target, frames, attributes, options)
  
  # Perform initial ease this frame if no delay
  perform_ease_for(ease) if ease.delay == 0 && method == :from

  # Delete other easings for same target if applicable
  self.overwrite_other_easings(ease) if ease.overwrite && ease.delay == 0

  # Add to easings array
  @@easings.push(ease)

end

+ (Ease_Object) to(target, frames, attributes = {}, options = {})

Note:

Depending on how your objects or classes are set up, you may need to use an “intermediary” object (like the target_obj hash in the example) to hold the attributes, then apply the values form this “intermediary” object to the attributes of the class when the :call_on_update method is called. The reason for this is that you may not necessarily want the easing function to write directly to a caller class. Look at the Game_Picture extension for an example of this necessity, where I didn't want to make any of the read-only attributes writable to implement easing.

Ease parameters to given attribute values from target's current attribute values

Examples:

Setting up an ease

target_obj = {:x => 0, :y => 0}
target_attributes = {:x => 250, :y => 100}
options = {
  :easing         => Easing::BOUNCE_IN,
  :observers      => [self],
  :call_on_update => :update (can also be writtens as "update")
}
TDD::Ease.to(target_obj, 60, target_attributes, options)

This would ease the movement of target_object from 0x and 0y to 250x and
100y over 60 frames (1 second) using the Easing::BOUNCE_IN easing method.
Every easing update (each frame) would call the method update on the
observer objects (self, in this case).

Parameters:

  • target (Object, Array) —

    An Object (or an Array of objects) which has the attributes listed in attributes and which you want to effect with an easing FROM its current values TO the values given in the attributes hash

  • frames (Integer) —

    The amount of frames to apply the easing over

  • attributes (Hash) (defaults to: {}) —

    Hash of attributes and target values for the attributes you wish to affect on the target object

  • options (Hash) (defaults to: {}) —

    Options Hash

Options Hash (options):

  • :easing (Easing) — default: Easing::LINEAR —

    Easing method to use

  • :delay (Integer) — default: 0 —

    Delay (in frames) before starting the ease.

  • :observers (Array) — default: nil —

    Array of observer objects (default = nil)

  • :call_on_update (Symbol, String, Boolean) — default: false —

    Method to call on :observers every update tick

  • :call_on_complete (Symbol, String, Boolean) — default: false —

    Method to call on :observers when easing is complete

Returns:

  • (Ease_Object) —

    ease_object - The created Ease_Object

See Also:



97
98
99
 
# File 'TDD Easing/tdd_ease_module.rb', line 97

def to(target, frames, attributes={}, options={})
  register_ease(:to, target, frames, attributes, options)
end

+ (Object) update

Note:

Called by Scene_Base when the extension is in place for it.

Updates easings every engine / Scene frame tick



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'TDD Easing/tdd_ease_module.rb', line 117

def update
  @@easings.each do |ease|
    # Skip to wait for delay option if present
    if ease.delay > 0
      ease.delay -= 1
      next
    end
    
    # Delete other easings if overwrite set
    self.overwrite_other_easings(ease) if ease.overwrite

    # Perform ease calculations
    perform_ease_for(ease)
  end
end