Class: Zif::Sprite

Inherits:
Object
  • Object
show all
Includes:
Actions::Actionable, Actions::Animatable, Assignable, Clickable, Serializable
Defined in:
app/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.

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, #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'))

137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
# File 'app/lib/zif/sprite.rb', line 137

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
end

Instance Attribute Details

#aNumeric

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

Returns:

  • (Numeric)

    Alpha channel (Transparency) (0-255)


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

#angleNumeric

Returns Rotation angle in degrees.

Returns:

  • (Numeric)

    Rotation angle in degrees


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

#bNumeric

Returns Blue color (0-255).

Returns:

  • (Numeric)

    Blue color (0-255)


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

#gNumeric

Returns Green color (0-255).

Returns:

  • (Numeric)

    Green color (0-255)


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

#hNumeric

Returns Height.

Returns:

  • (Numeric)

    Height


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

#logical_xInteger

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)


85
86
87
# File 'app/lib/zif/sprite.rb', line 85

def logical_x
  @logical_x
end

#logical_yInteger

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)


88
89
90
# File 'app/lib/zif/sprite.rb', line 88

def logical_y
  @logical_y
end

#nameSymbol, 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.


82
83
84
# File 'app/lib/zif/sprite.rb', line 82

def name
  @name
end

#pathSymbol, 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 'app/lib/zif/sprite.rb', line 103

#rNumeric

Returns Red color (0-255).

Returns:

  • (Numeric)

    Red color (0-255)


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

#render_targetZif::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:


101
102
103
# File 'app/lib/zif/sprite.rb', line 101

def render_target
  @render_target
end

#source_hNumeric

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 'app/lib/zif/sprite.rb', line 103

#source_wNumeric

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 'app/lib/zif/sprite.rb', line 103

#source_xNumeric

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 'app/lib/zif/sprite.rb', line 103

#source_yNumeric

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 'app/lib/zif/sprite.rb', line 103

#wNumeric

Returns Width.

Returns:

  • (Numeric)

    Width


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

#xNumeric

Returns X axis position.

Returns:

  • (Numeric)

    X axis position


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

#yNumeric

Returns Y axis position.

Returns:

  • (Numeric)

    Y axis position


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

#z_indexInteger

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:


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

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


186
187
188
189
190
191
192
193
# File 'app/lib/zif/sprite.rb', line 186

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


197
198
199
200
201
202
203
204
# File 'app/lib/zif/sprite.rb', line 197

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


208
209
210
# File 'app/lib/zif/sprite.rb', line 208

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

Instance Method Details

#centerArray<Numeric>

Returns [#center_x, #center_y].

Returns:


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

def center
  [center_x, center_y]
end

#center_xInteger

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)


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

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

#center_yInteger

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)


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

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:


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

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

  @render_target.clicked?(point, kind)
end

#colorHash<Symbol, Numeric>

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

Returns:

  • (Hash<Symbol, Numeric>)

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


300
301
302
303
304
305
306
307
# File 'app/lib/zif/sprite.rb', line 300

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.


311
312
313
314
315
316
# File 'app/lib/zif/sprite.rb', line 311

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:


156
157
158
# File 'app/lib/zif/sprite.rb', line 156

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

#exclude_from_serializeObject

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.


324
325
326
# File 'app/lib/zif/sprite.rb', line 324

def exclude_from_serialize
  %w[render_target]
end

#hideObject

Note:

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

Sets #a alpha to 0 (fully transparent).


168
169
170
# File 'app/lib/zif/sprite.rb', line 168

def hide
  @a = 0
end

#rectArray<Numeric>

Note:

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

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

Returns:


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

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

#rect_hashHash<Symbol, Numeric>

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

Returns:

  • (Hash<Symbol, Numeric>)

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


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

def rect_hash
  Sprite.rect_array_to_hash(rect)
end

#showObject

Sets #a alpha to 255 (fully opaque)


161
162
163
# File 'app/lib/zif/sprite.rb', line 161

def show
  @a = 255
end

#source_as_rect_hashHash<Symbol, Numeric>

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

Returns:


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

def source_as_rect_hash
  Sprite.rect_array_to_hash(source_rect)
end

#source_centerArray<Numeric>

Returns [source center x, source center y].

Returns:

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

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

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:


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

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

#source_rectArray<Numeric>

Returns:


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

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

#source_rect_hashHash<Symbol, Numeric>

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

Returns:


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

def source_rect_hash
  Sprite.rect_array_to_source_hash(source_rect)
end

#source_whArray<Numeric>

Returns [#source_w, #source_h].

Returns:


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

def source_wh
  [@source_w, @source_h]
end

#source_xyArray<Numeric>

Returns [#source_x, #source_y].

Returns:


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

def source_xy
  [@source_x, @source_y]
end

#to_hHash<Symbol, Numeric>

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

Returns:


319
320
321
# File 'app/lib/zif/sprite.rb', line 319

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.


251
252
253
254
255
256
# File 'app/lib/zif/sprite.rb', line 251

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

#whArray<Numeric>

Returns [#w, #h].

Returns:

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

218
219
220
# File 'app/lib/zif/sprite.rb', line 218

def wh
  [@w, @h]
end

#xyArray<Numeric>

Returns [#x, #y].

Returns:

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

213
214
215
# File 'app/lib/zif/sprite.rb', line 213

def xy
  [@x, @y]
end

#zoom_factorArray<Numeric>

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

Returns:


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

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