### Home Classes Methods

### In Files

- lib/rubygame/sprite.rb

### Methods

- ::new
- #add
- #alive?
- #col_rect
- #collide
- #collide_group
- #collide_sprite?
- #draw
- #kill
- #remove
- #undraw
- #update

### Files

- CREDITS
- LICENSE
- NEWS
- README
- ROADMAP
- custom_sdl_load_paths.rdoc
- getting_started.rdoc
- keyboard_symbols.rdoc
- macosx_install.rdoc
- managing_framerate.rdoc
- surface_palettes.rdoc
- windows_install.rdoc

### Class/Module Index

Quicksearch

- Rubygame
- Rubygame::ActiveEvent
- Rubygame::Clock
- Rubygame::Color
- Rubygame::Color::ColorBase
- Rubygame::Color::ColorHSL
- Rubygame::Color::ColorHSV
- Rubygame::Color::ColorRGB
- Rubygame::Color::Palette
- Rubygame::Event
- Rubygame::EventActions
- Rubygame::EventActions::BlockAction
- Rubygame::EventActions::MethodAction
- Rubygame::EventActions::MultiAction
- Rubygame::EventHandler
- Rubygame::EventHandler::HasEventHandler
- Rubygame::EventHook
- Rubygame::EventQueue
- Rubygame::EventTriggers
- Rubygame::EventTriggers::AndTrigger
- Rubygame::EventTriggers::AttrTrigger
- Rubygame::EventTriggers::BlockTrigger
- Rubygame::EventTriggers::InstanceOfTrigger
- Rubygame::EventTriggers::KeyPressTrigger
- Rubygame::EventTriggers::KeyReleaseTrigger
- Rubygame::EventTriggers::KindOfTrigger
- Rubygame::EventTriggers::MouseMoveTrigger
- Rubygame::EventTriggers::MousePressTrigger
- Rubygame::EventTriggers::MouseReleaseTrigger
- Rubygame::EventTriggers::OrTrigger
- Rubygame::EventTriggers::TickTrigger
- Rubygame::EventTriggers::YesTrigger
- Rubygame::Events
- Rubygame::Events::ClockTicked
- Rubygame::Events::InputFocusGained
- Rubygame::Events::InputFocusLost
- Rubygame::Events::JoystickAxisMoved
- Rubygame::Events::JoystickBallMoved
- Rubygame::Events::JoystickButtonEvent
- Rubygame::Events::JoystickButtonPressed
- Rubygame::Events::JoystickButtonReleased
- Rubygame::Events::JoystickHatMoved
- Rubygame::Events::KeyPressed
- Rubygame::Events::KeyReleased
- Rubygame::Events::KeyboardEvent
- Rubygame::Events::MouseButtonEvent
- Rubygame::Events::MouseFocusGained
- Rubygame::Events::MouseFocusLost
- Rubygame::Events::MouseMoved
- Rubygame::Events::MousePressed
- Rubygame::Events::MouseReleased
- Rubygame::Events::QuitRequested
- Rubygame::Events::WindowExposed
- Rubygame::Events::WindowMinimized
- Rubygame::Events::WindowResized
- Rubygame::Events::WindowUnminimized
- Rubygame::ExposeEvent
- Rubygame::Ftor
- Rubygame::GL
- Rubygame::Hotspot
- Rubygame::JoyAxisEvent
- Rubygame::JoyBallEvent
- Rubygame::JoyDownEvent
- Rubygame::JoyHatEvent
- Rubygame::JoyUpEvent
- Rubygame::Joystick
- Rubygame::Key
- Rubygame::KeyDownEvent
- Rubygame::KeyUpEvent
- Rubygame::MailQueue
- Rubygame::MediaBag
- Rubygame::Mixer
- Rubygame::Mixer::Music
- Rubygame::Mixer::Sample
- Rubygame::Mouse
- Rubygame::MouseDownEvent
- Rubygame::MouseMotionEvent
- Rubygame::MouseUpEvent
- Rubygame::Music
- Rubygame::NamedResource
- Rubygame::NamedResource::NamedResourceClassMethods
- Rubygame::QuitEvent
- Rubygame::Rect
- Rubygame::ResizeEvent
- Rubygame::SDLError
- Rubygame::SFont
- Rubygame::Screen
- Rubygame::Sound
- Rubygame::Sprites
- Rubygame::Sprites::DepthSortGroup
- Rubygame::Sprites::Group
- Rubygame::Sprites::LimitGroup
- Rubygame::Sprites::Sprite
- Rubygame::Sprites::UpdateGroup
- Rubygame::Surface
- Rubygame::TTF

No matching classes.

# Rubygame::Sprites::Sprite

The Sprite mix-in module (not to be confused with its parent module, Sprites) can be used to extend a class or object to behave as a sprite. Specifically, a sprite can:

- draw (blit) itself onto a Surface in its proper position

- detect bounding-box collision with Groups (collide_group) and/or other sprites (collide_sprite).

- update its own state based on arbitrary rules.

A Sprite is, fundamentally, a Surface with an associated Rect which defines the position of that Surface on the Screen. Additionally, sprites can have some behavior associated with them via the update method, including movement and collision detection; because of this, sprites can be the foundation of most on-screen objects, such as characters, items, missiles, and even user-interface elements.

In order to work properly as a Sprite, the extended object or class must have two methods defined (by default, these are defined as accessors to attributes of the same names):

image | return a Surface with the sprite's image.
rect | returns a Rect with the position and dimensions of the sprite.

Normally, the value returned by rect is used to draw the sprite onto a Surface as well as to detect collision between sprites. However, if @col_rect will be used for collision detection instead, if it is defined. See also col_rect.

Additionally, if you are extending an already-existing instance (rather than a class), that instance must have an attribute @groups, which is an Array containing all Groups to which the sprite belongs.

### Attributes

col_rect[W]

Set an alternative Rect to use for collision detection. If undefined or set to nil, the Sprite's rect is used instead.

depth[RW]
groups[R]
image[RW]
rect[RW]

### Public Class Methods

new() click to toggle source

Initialize the Sprite, defining @groups and @depth.

    # File lib/rubygame/sprite.rb, line 82
    def initialize
            @groups = []
            @depth = 0
    end

### Public Instance Methods

add(*groups) click to toggle source

Add the Sprite to each given Group.

    # File lib/rubygame/sprite.rb, line 88
    def add(*groups)
            groups.each { |group|
                    unless @groups.include? group
                            @groups.push(group)
                            group.push(self)
                    end
            }
    end

alive? → true or false click to toggle source

True if the Sprite belongs to at least one Group.

    # File lib/rubygame/sprite.rb, line 100
    def alive?
            return @groups.length > 0
    end

col_rect → Rect click to toggle source

Returns @col_rect if it is defined, otherwise calls rect. This method is used by collide, collide_group, and collide_sprite to get the bounding box for collision detection.

    # File lib/rubygame/sprite.rb, line 113
    def col_rect
            if defined? @col_rect
                    return (@col_rect or rect)
            else
                    return rect
            end
    end

collide(other) → Array click to toggle source

Check collision between the caller and a Group or another Sprite. See also collide_group and collide_sprite. This method uses the value of col_rect as the bounding box when detecting collision.

If `other` is a Group, returns an Array of every Sprite in that Group that collides with the caller. If `other` is a Sprite, returns an Array containing `other` if it collides with the caller. Otherwise, returns an empty Array.

    # File lib/rubygame/sprite.rb, line 131
    def collide(other)
            if other.class.is_a? Group
                    return collide_group(other)
            elsif collide_sprite?(other)
                    return [other]
            else
                    return []
            end
    end

collide_group(group) → Array click to toggle source

Check collision between the caller and all members of a Group. This method uses the value of col_rect as the bounding box when detecting collision.

Returns an Array of every Sprite in `group` that collides with the caller. If none collide, returns an empty Array.

    # File lib/rubygame/sprite.rb, line 149
    def collide_group(group)
            sprites = []
            group.each { |sprite|
                    if self.collide_sprite?(sprite) and (not sprites.include?(sprite))
                            sprites.push(sprite)
                    end
            }
            return sprites
    end

collide_sprite?(sprite) → true or false or nil click to toggle source

Check collision between the caller and another Sprite. This method uses the value of col_rect as the bounding box when detecting collision. Returns true if `sprite` collides with the caller, false if they do not, or nil if `sprite` does not respond to either :col_rect or :rect (meaning it was not possible to detect collision).

    # File lib/rubygame/sprite.rb, line 166
    def collide_sprite?(sprite)
            if sprite.respond_to?(:col_rect)
                    return self.col_rect.collide_rect?(sprite.col_rect)
            elsif sprite.respond_to?(:rect)
                    return self.col_rect.collide_rect?(sprite.rect)
            else
                    return nil
            end
    end

draw(surface) → Rect click to toggle source

Blit the Surface returned by image onto `surface` at the position given by the Rect returned by rect. Returns a Rect representing the area of `surface` which was affected by the draw.

    # File lib/rubygame/sprite.rb, line 181
    def draw(destination)
            self.image.blit(destination, self.rect)
    end

kill() click to toggle source

Remove the caller from every Group that it belongs to.

    # File lib/rubygame/sprite.rb, line 186
    def kill
            @groups.each { |group| group.delete(self) }
            @groups = []
    end

remove(*groups) click to toggle source

Remove the caller from each given Group.

    # File lib/rubygame/sprite.rb, line 192
    def remove(*groups)
            groups.each { |group|
                    if @groups.include? group
                            @groups.delete(group)
                            group.delete(self)
                    end
            }
    end

undraw(surface, background) → Rect click to toggle source

'Erase' the sprite from `surface` by drawing over it with part of `background`. For best results, `background` should be the same size as `surface`.

Returns a Rect representing the area of `surface` which was affected.

    # File lib/rubygame/sprite.rb, line 210
    def undraw(dest, background)
            background.blit(dest, @rect, @rect)
    end

update( *args ) click to toggle source

This method is meant to be overwritten by Sprite-based classes to define meaningful behavior. It can take any number of arguments you want, be called however often you want, and do whatever you want. It may return something, but Group#update will not (by default) use, or even collect, return values from this method.

An example definition might take the amount of time that has passed since the last update; the Sprite could then update its position accordingly. Game logic, collision detection, and animation would also fit in here, if appropriate to your class.

    # File lib/rubygame/sprite.rb, line 224
    def update( *args )
            super
    end

[Validate]

Generated with the Darkfish Rdoc Generator 2.