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.blendmode_enum = :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: … }



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

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: … }



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

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: …}



224
225
226
 
# File 'lib/zif/sprite.rb', line 224

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

Instance Method Details

#blendmode_enum=(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 blendmode_enum=(new_blendmode)
  @blendmode_enum = BLENDMODE.fetch(new_blendmode, new_blendmode)
end

#center ⇒ Array<Numeric>

Returns [#center_x, #center_y].

Returns:



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

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)



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

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)



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

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:



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

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



316
317
318
319
320
321
322
323
 
# File 'lib/zif/sprite.rb', line 316

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.



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

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. 



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

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:



184
185
186
 
# File 'lib/zif/sprite.rb', line 184

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:



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

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



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

def rect_hash
  Sprite.rect_array_to_hash(rect)
end

#show ⇒ Object

Sets #a alpha to 255 (fully opaque)



177
178
179
 
# File 'lib/zif/sprite.rb', line 177

def show
  @a = 255
end

#source_as_rect_hash ⇒ Hash<Symbol, Numeric>

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

Returns:



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

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 


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

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:



275
276
277
 
# File 'lib/zif/sprite.rb', line 275

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:



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

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:



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

def source_rect_hash
  Sprite.rect_array_to_source_hash(source_rect)
end

#source_wh ⇒ Array<Numeric>

Returns [#source_w, #source_h].

Returns:



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

def source_wh
  [@source_w, @source_h]
end

#source_xy ⇒ Array<Numeric>

Returns [#source_x, #source_y].

Returns:



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

def source_xy
  [@source_x, @source_y]
end

#to_h ⇒ Hash<Symbol, Numeric>

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

Returns:



335
336
337
 
# File 'lib/zif/sprite.rb', line 335

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.



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

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 


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

def wh
  [@w, @h]
end

#xy ⇒ Array<Numeric>

Returns [#x, #y].

Returns:

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


229
230
231
 
# File 'lib/zif/sprite.rb', line 229

def xy
  [@x, @y]
end

#zoom_factor ⇒ Array<Numeric>

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

Returns:



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

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