Class: Zif::Sprite

Inherits:
Object
  • Object
show all
Includes:
Actions::Actionable, Actions::Animatable, Assignable, Clickable, Serializable
Defined in:
lib/zif/sprite.rb

Overview

A basic sprite which combines actions / animations, click handling, mass assignment and more.

The foundation for most of the Zif library.

Includes attr_sprite – supports what DRGTK provides for these classes in addition to what is documented here.

See DRGTK docs on attr_sprite: docs.dragonruby.org/#—-attr_sprite.rb

# This only needs to be done once globally, usually in your Zif::Scene#prepare_scene method
$game.services[:input_service].register_clickable(dragon)

 # Turn the dragon red when the mouse is clicked down.
 # This lambda is called by the input service with this sprite (dragon) plus the mouse location.
 # We don't need the mouse location for this example so we prefix that argument with _ to indicate it is unused
 dragon.on_mouse_down = lambda {|sprite, _point|
   sprite.r = 255
   sprite.g = 0
   sprite.b = 0
 }

 # Turn the dragon green when the mouse is clicked down & moved
 dragon.on_mouse_changed = lambda {|sprite, _point|
   sprite.r = 0
   sprite.g = 255
   sprite.b = 0
 }

 # Turn the dragon blue when the mouse click ends - the dragon stays blue after this until you click again.
 dragon.on_mouse_up = lambda {|sprite, _point|
   sprite.r = 0
   sprite.g = 0
   sprite.b = 255
 }

Examples:

Basic usage

dragon = Zif::Sprite.new.tap do |s|
  s.x = 300
  s.y = 300
  s.w = 82
  s.h = 66
  s.path = "sprites/dragon_1.png"
end
# At this point, you can render your dragon:
$gtk.args.outputs.sprites << dragon

Scaling an image

# dragon is the dragon sprite with path +sprites/dragon_1.png+.  This image is 82 pixels wide, 66 pixels tall.

# Place our sprite at 10,10 on the screen:
dragon.x = 10
dragon.y = 10

# The sprite should be 100 pixels by 100 pixels in size on the screen:
dragon.w = 100
dragon.h = 100

# Only show the center 50x50 pixels of the source image:
dragon.source_w = 50
dragon.source_h = 50

# Take that 50x50 slice from the center of the image
dragon.source_x = 82.fdiv(2) - 25
dragon.source_y = 66.fdiv(2) - 25

# All together, this means we are showing
# - the center 50x50 pixels of the dragon,
# - scaled up to fit 100x100,
# - at 10,10 on the screen

Handling clicks

# Building on dragon from the basic example.  Expects Zif::Services::InputService to be set up.

Constant Summary collapse

BLENDMODE = 
{
  none:     0,
  alpha:    1,
  add:      2,
  mod:      3,
  multiply: 4
}.freeze

Instance Attribute Summary collapse

Attributes included from Clickable

#on_mouse_changed, #on_mouse_down, #on_mouse_up

Attributes included from Actions::Animatable

#animation_sequences, #cur_animation

Attributes included from Actions::Actionable

#actions, #dirty

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Clickable

#absorb_click?

Methods included from Actions::Animatable

#new_basic_animation, #new_tiled_animation, #register_animation_sequence, #run_animation_sequence, #stop_animating

Methods included from Actions::Actionable

#bounce_forever_around, #delayed_action, #fade_in, #fade_out, #fade_out_and_in_forever, #new_action, #perform_actions, #run_action, #running_actions?, #stop_action

Methods included from Serializable

#inspect, #serialize, #to_s

Methods included from Assignable

#assign

Constructor Details

#initialize(name = Zif.unique_name('sprite')) ⇒ Sprite

Returns a new instance of Sprite.

Parameters:

  • name (Symbol, String) (defaults to: Zif.unique_name('sprite')) —

    #name



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/zif/sprite.rb', line 145

def initialize(name=Zif.unique_name('sprite'))
  @name      = name
  @logical_x = 0
  @logical_y = 0
  @x         = 0
  @y         = 0
  @z_index   = 0
  @w         = 0
  @h         = 0
  @a         = 255
  @r         = 255
  @g         = 255
  @b         = 255
  @angle     = 0
  self.blend = :alpha
end

Instance Attribute Details

#a ⇒ Numeric

Returns Alpha channel (Transparency) (0-255).

Returns:

  • (Numeric) —

    Alpha channel (Transparency) (0-255)




# File 'lib/zif/sprite.rb', line 111

#angle ⇒ Numeric

Returns Rotation angle in degrees.

Returns:

  • (Numeric) —

    Rotation angle in degrees




# File 'lib/zif/sprite.rb', line 111

#b ⇒ Numeric

Returns Blue color (0-255).

Returns:

  • (Numeric) —

    Blue color (0-255)




# File 'lib/zif/sprite.rb', line 111

#g ⇒ Numeric

Returns Green color (0-255).

Returns:

  • (Numeric) —

    Green color (0-255)




# File 'lib/zif/sprite.rb', line 111

#h ⇒ Numeric

Returns Height.

Returns:

  • (Numeric) —

    Height




# File 'lib/zif/sprite.rb', line 111

#logical_x ⇒ Integer

Returns Used for unit positioning (tile map addressing, for example - See Layers::LayerGroup).

Returns:

  • (Integer) —

    Used for unit positioning (tile map addressing, for example - See Layers::LayerGroup)



93
94
95
 
# File 'lib/zif/sprite.rb', line 93

def logical_x
  @logical_x
end

#logical_y ⇒ Integer

Returns Used for unit positioning (tile map addressing, for example - See Layers::LayerGroup).

Returns:

  • (Integer) —

    Used for unit positioning (tile map addressing, for example - See Layers::LayerGroup)



96
97
98
 
# File 'lib/zif/sprite.rb', line 96

def logical_y
  @logical_y
end

#name ⇒ Symbol, String

Returns The name of this instance. This helps differentiate multiple copies when debugging.

Returns:

  • (Symbol, String) —

    The name of this instance. This helps differentiate multiple copies when debugging.



90
91
92
 
# File 'lib/zif/sprite.rb', line 90

def name
  @name
end

#path ⇒ Symbol, String

Returns The source of this image. Either the path to the image file relative to app/, or the name of the render target.

Returns:

  • (Symbol, String) —

    The source of this image. Either the path to the image file relative to app/, or the name of the render target.




# File 'lib/zif/sprite.rb', line 111

#r ⇒ Numeric

Returns Red color (0-255).

Returns:

  • (Numeric) —

    Red color (0-255)




# File 'lib/zif/sprite.rb', line 111

#render_target ⇒ Zif::RenderTarget

If this sprite is a parent container for a RenderTarget (sources it via #path), reference it here

Not for sprites which are children (rendered inside) of a Render Target!

Returns:



109
110
111
 
# File 'lib/zif/sprite.rb', line 109

def render_target
  @render_target
end

#source_h ⇒ Numeric

Returns The Y axis extent to which we will source the #path image.

Returns:

  • (Numeric) —

    The Y axis extent to which we will source the #path image




# File 'lib/zif/sprite.rb', line 111

#source_w ⇒ Numeric

Returns The X axis extent to which we will source the #path image.

Returns:

  • (Numeric) —

    The X axis extent to which we will source the #path image




# File 'lib/zif/sprite.rb', line 111

#source_x ⇒ Numeric

Returns X axis position of the #path image we want to start sourcing the image from.

Returns:

  • (Numeric) —

    X axis position of the #path image we want to start sourcing the image from




# File 'lib/zif/sprite.rb', line 111

#source_y ⇒ Numeric

Returns Y axis position of the #path image we want to start sourcing the image from.

Returns:

  • (Numeric) —

    Y axis position of the #path image we want to start sourcing the image from




# File 'lib/zif/sprite.rb', line 111

#w ⇒ Numeric

Returns Width.

Returns:

  • (Numeric) —

    Width




# File 'lib/zif/sprite.rb', line 111

#x ⇒ Numeric

Returns X axis position.

Returns:

  • (Numeric) —

    X axis position




# File 'lib/zif/sprite.rb', line 111

#y ⇒ Numeric

Returns Y axis position.

Returns:

  • (Numeric) —

    Y axis position




# File 'lib/zif/sprite.rb', line 111

#z_index ⇒ Integer

Note:

Layers::LayerGroup has it’s own stacking order, each layer has a z-index. Sprites contained within a layer are ordered amongst themselves using this attribute, but are constrained to the layer they are on.

Returns Stacking order, used to determine which sprite is above another if overlapping.

Returns:

  • (Integer) —

    Stacking order, used to determine which sprite is above another if overlapping.

See Also:



103
104
105
 
# File 'lib/zif/sprite.rb', line 103

def z_index
  @z_index
end

Class Method Details

.rect_array_to_hash(arr = []) ⇒ Hash<Symbol, Numeric>

Returns Converts the array into a hash with those values mapped like {x: … }.

Parameters:

  • arr (Array<Numeric>) (defaults to: []) —

    Takes an array of [x, y, w, h] integers

Returns:

  • (Hash<Symbol, Numeric>) —

    Converts the array into a hash with those values mapped like {x: … }



212
213
214
215
216
217
218
219
 
# File 'lib/zif/sprite.rb', line 212

def self.rect_array_to_hash(arr=[])
  {
    x: arr[0],
    y: arr[1],
    w: arr[2],
    h: arr[3]
  }
end

.rect_array_to_source_hash(arr = []) ⇒ Hash<Symbol, Numeric>

Returns Converts the array into a hash with those values mapped like {source_x: … }.

Parameters:

  • arr (Array<Numeric>) (defaults to: []) —

    Takes an array of [source_x, source_y, source_w, source_h] integers

Returns:

  • (Hash<Symbol, Numeric>) —

    Converts the array into a hash with those values mapped like {source_x: … }



223
224
225
226
227
228
229
230
 
# File 'lib/zif/sprite.rb', line 223

def self.rect_array_to_source_hash(arr=[])
  {
    source_x: arr[0],
    source_y: arr[1],
    source_w: arr[2],
    source_h: arr[3]
  }
end

.rect_hash_to_source_hash(rect = {}) ⇒ Hash<Symbol, Numeric>

Returns Converts keys in rect like {source_x: …, source_y: …}.

Parameters:

  • rect (Hash<Symbol, Numeric>) (defaults to: {}) —

    {x: …, y: …}

Returns:

  • (Hash<Symbol, Numeric>) —

    Converts keys in rect like {source_x: …, source_y: …}



234
235
236
 
# File 'lib/zif/sprite.rb', line 234

def self.rect_hash_to_source_hash(rect={})
  rect.transform_keys { |key| key.include?('source_') ? key : "source_#{key}".to_sym }
end

Instance Method Details

#blend ⇒ Integer Also known as: blendmode_enum

Returns The integer value for the specified blend mode. See BLENDMODE.

Examples:

This always returns an integer, even if you set it using a symbol

mysprite.blend = :alpha  # => 1
mysprite.blend           # => 1

Returns:

  • (Integer) —

    The integer value for the specified blend mode. See BLENDMODE



180
181
182
 
# File 'lib/zif/sprite.rb', line 180

def blend
  @blendmode
end

#blend=(new_blendmode) ⇒ Integer

Set blend mode using either symbol names or the enum integer values.

Parameters:

  • new_blendmode (Symbol, Integer) —

    #blend :none, :alpha, :add, :mod, :multiply or 0, 1, 2, 3, 4. See BLENDMODE

Returns:

  • (Integer) —

    The integer value for the specified blend mode



172
173
174
 
# File 'lib/zif/sprite.rb', line 172

def blend=(new_blendmode)
  @blendmode = BLENDMODE.fetch(new_blendmode, new_blendmode)
end

#center ⇒ Array<Numeric>

Returns [#center_x, #center_y].

Returns:



259
260
261
 
# File 'lib/zif/sprite.rb', line 259

def center
  [center_x, center_y]
end

#center_x ⇒ Integer

Returns The x value of center point of the sprite (calculated from #x and #w).

Returns:

  • (Integer) —

    The x value of center point of the sprite (calculated from #x and #w)



249
250
251
 
# File 'lib/zif/sprite.rb', line 249

def center_x
  (@x + @w.idiv(2)).to_i
end

#center_y ⇒ Integer

Returns The y value of center point of the sprite (calculated from #y and #h).

Returns:

  • (Integer) —

    The y value of center point of the sprite (calculated from #y and #h)



254
255
256
 
# File 'lib/zif/sprite.rb', line 254

def center_y
  (@y + @h.idiv(2)).to_i
end

#clicked?(point, kind = :up) ⇒ Object?

Returns If this sprite has a #render_target, pass the click through to it. Otherwise, call Clickable#clicked? and return this sprite or nil.

Parameters:

  • point (Array<Integer>) —
    x, y

    position Array of the current mouse click.

  • kind (Symbol) (defaults to: :up) —

    The kind of click coming through, one of [:up, :down, :changed]

Returns:

See Also:



204
205
206
207
208
 
# File 'lib/zif/sprite.rb', line 204

def clicked?(point, kind=:up)
  return super(point, kind) unless @render_target && !absorb_click?

  @render_target.clicked?(point, kind)
end

#color ⇒ Hash<Symbol, Numeric>

Returns r: #r, g: #g, b: #b, a: #a.

Returns:

  • (Hash<Symbol, Numeric>) —

    r: #r, g: #g, b: #b, a: #a



326
327
328
329
330
331
332
333
 
# File 'lib/zif/sprite.rb', line 326

def color
  {
    r: @r,
    g: @g,
    b: @b,
    a: @a
  }
end

#color=(rgba_array = []) ⇒ Object

Note:

Use #assign if you want to assign with a hash. This works with positional array.

Parameters:

  • rgba_array (Array<Numeric>) (defaults to: []) —

    [r, g, b, a]. If any entry is nil, assignment is skipped.



337
338
339
340
341
342
 
# File 'lib/zif/sprite.rb', line 337

def color=(rgba_array=[])
  @r = rgba_array[0] if rgba_array[0]
  @g = rgba_array[1] if rgba_array[1]
  @b = rgba_array[2] if rgba_array[2]
  @a = rgba_array[3] if rgba_array[3]
end

#dup_and_assign(sprite) ⇒ Zif::Sprite

Returns A copy of this sprite, with the changes applied.

Parameters:

  • sprite (Hash<Symbol, Object>) —

    A hash of key-values to mass assign to a copy of this sprite.

Returns:

  • (Zif::Sprite) —

    A copy of this sprite, with the changes applied.

See Also:



165
166
167
 
# File 'lib/zif/sprite.rb', line 165

def dup_and_assign(sprite)
  dup.assign(sprite)
end

#exclude_from_serialize ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future. 



350
351
352
 
# File 'lib/zif/sprite.rb', line 350

def exclude_from_serialize
  %w[render_target]
end

#hide ⇒ Object

Note:

Some processing may be skipped if this sprite is hidden, to increase performance.

Sets #a alpha to 0 (fully transparent).

See Also:



194
195
196
 
# File 'lib/zif/sprite.rb', line 194

def hide
  @a = 0
end

#rect ⇒ Array<Numeric>

Note:

Performance Tip: Use the Sprite itself for things like #intersect_rect? rather than creating this array!

Returns [#x, #y, #w, #h].

Returns:



265
266
267
 
# File 'lib/zif/sprite.rb', line 265

def rect
  [@x, @y, @w, @h]
end

#rect_hash ⇒ Hash<Symbol, Numeric>

Returns x: #x, y: #y, w: #w, h: #h.

Returns:

  • (Hash<Symbol, Numeric>) —

    x: #x, y: #y, w: #w, h: #h



270
271
272
 
# File 'lib/zif/sprite.rb', line 270

def rect_hash
  Sprite.rect_array_to_hash(rect)
end

#show ⇒ Object

Sets #a alpha to 255 (fully opaque)



187
188
189
 
# File 'lib/zif/sprite.rb', line 187

def show
  @a = 255
end

#source_as_rect_hash ⇒ Hash<Symbol, Numeric>

If for some reason you want source_ attrs without “source_” keys

Returns:



321
322
323
 
# File 'lib/zif/sprite.rb', line 321

def source_as_rect_hash
  Sprite.rect_array_to_hash(source_rect)
end

#source_center ⇒ Array<Numeric>

Returns [source center x, source center y].

Returns:

  • (Array<Numeric>) —
    source center x, source center y 


305
306
307
 
# File 'lib/zif/sprite.rb', line 305

def source_center
  [(@source_x + @source_w.idiv(2)).to_i, (@source_y + @source_h.idiv(2)).to_i]
end

#source_is_set? ⇒ Boolean

Returns True if #source_x, #source_y, #source_w, #source_h are all set to something.

Returns:



285
286
287
 
# File 'lib/zif/sprite.rb', line 285

def source_is_set?
  !(@source_x.nil? || @source_y.nil? || @source_w.nil? || @source_h.nil?)
end

#source_rect ⇒ Array<Numeric>

Returns [#source_x, #source_y, #source_w, #source_h].

Returns:



300
301
302
 
# File 'lib/zif/sprite.rb', line 300

def source_rect
  [@source_x, @source_y, @source_w, @source_h]
end

#source_rect_hash ⇒ Hash<Symbol, Numeric>

Returns source_x: #source_x, source_y: #source_y, source_w: #source_w, source_h: #source_h.

Returns:



315
316
317
 
# File 'lib/zif/sprite.rb', line 315

def source_rect_hash
  Sprite.rect_array_to_source_hash(source_rect)
end

#source_wh ⇒ Array<Numeric>

Returns [#source_w, #source_h].

Returns:



295
296
297
 
# File 'lib/zif/sprite.rb', line 295

def source_wh
  [@source_w, @source_h]
end

#source_xy ⇒ Array<Numeric>

Returns [#source_x, #source_y].

Returns:



290
291
292
 
# File 'lib/zif/sprite.rb', line 290

def source_xy
  [@source_x, @source_y]
end

#to_h ⇒ Hash<Symbol, Numeric>

Returns Hash of #color + #rect_hash + #source_rect_hash + #path.

Returns:



345
346
347
 
# File 'lib/zif/sprite.rb', line 345

def to_h
  {path: @path}.merge(source_rect_hash).merge(rect_hash).merge(color)
end

#view_actual_size! ⇒ Object

This sets all of #source_x, #source_y, #source_w, #source_h to display the entire width and height You want to use this, unless you’re trying to zoom/pan. These attrs need to be set before we can display component sprites.



277
278
279
280
281
282
 
# File 'lib/zif/sprite.rb', line 277

def view_actual_size!
  @source_x = 0
  @source_y = 0
  @source_w = @w
  @source_h = @h
end

#wh ⇒ Array<Numeric>

Returns [#w, #h].

Returns:

  • (Array<Numeric>) —
    #w, #h 


244
245
246
 
# File 'lib/zif/sprite.rb', line 244

def wh
  [@w, @h]
end

#xy ⇒ Array<Numeric>

Returns [#x, #y].

Returns:

  • (Array<Numeric>) —
    #x, #y 


239
240
241
 
# File 'lib/zif/sprite.rb', line 239

def xy
  [@x, @y]
end

#zoom_factor ⇒ Array<Numeric>

Returns [#w divided by #source_w, #h divided by #source_h].

Returns:



310
311
312
 
# File 'lib/zif/sprite.rb', line 310

def zoom_factor
  [@w.fdiv(@source_w), @h.fdiv(@source_h)]
end