Tile

class pygamelib.board_items.Tile(**kwargs)

Bases: BoardComplexItem, GenericStructure

New in version 1.2.0.

A Tile is a standard BoardComplexItem configured by default to:

  • be overlappable

  • be restorable

  • be not pickable

  • be immovable.

Aside from the movable attributes (it inherit from GenericStructure so it’s an Immovable object), everything else is configurable.

It is particularly useful to display a Sprite on the background or to create terrain.

Example:

grass_sprite = Sprite.load_from_ansi_file('textures/grass.ans')
for pos in grass_positions:
    outdoor_level.place_item( Tile(sprite=grass_sprite), pos[0], pos[1] )
__init__(**kwargs)
Parameters:
  • overlappable (bool) – Defines if the Tile can be overlapped.

  • restorable (bool) – Defines is the Tile should be restored after being overlapped.

  • pickable (bool) – Defines if the Tile can be picked up by the Player or NPC.

Please see BoardComplexItem for additional parameters.

Methods

__init__(**kwargs)

param overlappable:

Defines if the Tile can be overlapped.

attach(observer)

Attach an observer to this instance.

can_move()

A Tile cannot move.

collides_with(other[, projection_offset])

Tells if this item collides with another item.

debug_info()

Return a string with the list of the attributes and their current value.

detach(observer)

Detach an observer from this instance.

display()

Print the model WITHOUT carriage return.

distance_to(other)

Calculates the distance with an item.

handle_notification(subject[, attribute, value])

A virtual method that needs to be implemented by the observer.

item(row, column)

Return the item component at the row, column position if it is within the complex item's boundaries.

load(data)

Load data and create a new Tile out of it.

notify([modifier, attribute, value])

Notify all the observers that a change occurred.

overlappable()

Returns True if the item is overlappable, False otherwise.

pickable()

Returns True if the item is pickable, False otherwise.

position_as_vector()

Returns the current item position as a Vector2D

render_to_buffer(buffer, row, column, ...)

Render the complex board item from the display buffer to the frame buffer.

restorable()

Returns True if the item is restorable, False otherwise.

serialize()

Return a dictionary with all the attributes of this object.

set_can_move(value)

Set the value of the can_move property to value.

set_overlappable(value)

Set the value of the overlappable property to value.

set_pickable(value)

Set the value of the pickable property to value.

set_restorable(value)

Set the value of the restorable property to value.

store_position(row, column[, layer])

Store the BoardItem position for self access.

store_screen_position(row, column)

Store the screen position of the object.

update_sprite()

Update the complex item with the current sprite.

Attributes

animation

A property to get and set an Animation for this item.

column

Convenience method to get the current stored column of the item.

heading

Return the heading of the item.

height

Convenience method to get the height of the item.

inventory_space

Return the size that the Immovable item takes in the Inventory.

layer

Convenience method to get the current stored layer number of the item.

model

particle_emitter

row

Convenience method to get the current stored row of the item.

screen_column

A property to get/set the screen column.

screen_row

A property to get/set the screen row.

size

A read-only property that gives the size of the item as a 2 dimensions list.

sprite

A property to easily access and update a complex item's sprite.

width

Convenience method to get the width of the item.

property animation

A property to get and set an Animation for this item.

Important

When an animation is set, the item is setting the animation’s parent to itself.

attach(observer)

Attach an observer to this instance. It means that until it is detached, it will be notified every time that a notification is issued (usually on changes).

An object cannot add itself to the list of observers (to avoid infinite recursions).

Parameters:

observer (PglBaseObject) – An observer to attach to this object.

Returns:

True or False depending on the success of the operation.

Return type:

bool

Example:

myboard = Board()
screen = Game.instance().screen
# screen will be notified of all changes in myboard
myboard.attach(screen)
can_move()

A Tile cannot move.

Returns:

False

Return type:

bool

collides_with(other, projection_offset: Vector2D = None)

Tells if this item collides with another item.

Important

collides_with() does not take the layer into account! It is not desirable for the pygamelib to assume that 2 items on different layers wont collide. For example, if a player is over a door, they are on different layers, but logically speaking they are colliding. The player is overlapping the door. Therefor, it is the responsibility of the developer to check for layers in collision, if it is important to the game logic.

Parameters:
  • other (BoardItem) – The item you want to check for collision.

  • projection_offset (Vector2D) – A vector to offset this board item’s position (not the position of the other item). Use this to detect a collision before moving the board item. You can pass the movement vector before moving to check if a collision will occur when moving.

Return type:

bool

Example:

if projectile.collides_with(game.player):
    game.player.hp -= 5
property column

Convenience method to get the current stored column of the item.

This is absolutely equivalent to access to item.pos[1].

Returns:

The column coordinate

Return type:

int

Example:

if item.column != item.pos[1]:
    print('Something extremely unlikely just happened...')
debug_info()

Return a string with the list of the attributes and their current value.

Return type:

str

detach(observer)

Detach an observer from this instance. If observer is not in the list this returns False.

Parameters:

observer (PglBaseObject) – An observer to detach from this object.

Returns:

True or False depending on the success of the operation.

Return type:

bool

Example:

# screen will no longer be notified of the changes in myboard.
myboard.detach(screen)
display()

Print the model WITHOUT carriage return.

distance_to(other)

Calculates the distance with an item.

Parameters:

other (BoardItem) – The item you want to calculate the distance to.

Returns:

The distance between this item and the other.

Return type:

float

Example:

if npc.distance_to(game.player) <= 2.0:
    npc.seek_and_destroy = True
handle_notification(subject, attribute=None, value=None)

A virtual method that needs to be implemented by the observer. By default it does nothing but each observer needs to implement it if something needs to be done when notified.

This method always receive the notifying object as first parameter. The 2 other parameters are optional and can be None.

You can use the attribute and value as you see fit. You are free to consider attribute as an event and value as the event’s value.

Parameters:
  • subject (PglBaseObject) – The object that has changed.

  • attribute (str) – The attribute that has changed, it is usually a “FQDN style” string. This can be None.

  • value (Any) – The new value of the attribute. This can be None.

property heading

Return the heading of the item.

This is a read only property that is updated by store_position().

The property represent the orientation and movement of the item in the board. It gives the difference between the item’s centroid current and previous position. Thus, giving you both the direction and the distance of the movement. You can get the angle from here.

One of the possible usage of that property is to set the sprite/sprixel/model of a moving item.

Returns:

The heading of the item.

Return type:

Vector2D

Example:

if my_item.heading.column > 0:
    my_item.sprixel.model = item_models["heading_right"]

Warning

Just after placing an item on the board, and before moving it, the heading cannot be trusted! The heading represent the direction and orientation of the movement, therefore, it is not reliable before the item moved.

property height

Convenience method to get the height of the item.

This is absolutely equivalent to access to item.size[1].

Returns:

The height

Return type:

int

Example:

if item.height > board.height:
    print('The item is too big for the board.')
property inventory_space

Return the size that the Immovable item takes in the Inventory.

Returns:

The size of the item.

Return type:

int

item(row, column)

Return the item component at the row, column position if it is within the complex item’s boundaries.

Return type:

~pygamelib.board_items.BoardItem

Raises:

PglOutOfBoardBoundException – if row or column are out of bound.

property layer

Convenience method to get the current stored layer number of the item.

This is absolutely equivalent to access to item.pos[2].

Returns:

The layer number

Return type:

int

Example:

if item.layer != item.pos[2]:
    print('Something extremely unlikely just happened...')
classmethod load(data)

Load data and create a new Tile out of it.

Parameters:

data (dict) – Data to create a new tile (usually generated by serialize())

Returns:

A new complex npc.

Return type:

~pygamelib.board_items.Tile

property model
notify(modifier=None, attribute: str = None, value: Any = None) None

Notify all the observers that a change occurred.

Parameters:
  • modifier (PglBaseObject) – An optional parameter that identify the modifier object to exclude it from the notified objects.

  • attribute (str) – An optional parameter that identify the attribute that has changed.

  • value (Any) – An optional parameter that identify the new value of the attribute.

Example:

# This example is silly, you would usually notify other objects from inside
# an object that changes a value that's important for the observers.
color = Color(255,200,125)
color.attach(some_text_object)
color.notify()
overlappable()

Returns True if the item is overlappable, False otherwise.

Example:

if board.item(4,5).overlappable():
    print('The item is overlappable')
property particle_emitter
pickable()

Returns True if the item is pickable, False otherwise.

Example:

if board.item(4,5).pickable():
    print('The item is pickable')
position_as_vector()

Returns the current item position as a Vector2D

Returns:

The position as a 2D vector

Return type:

Vector2D

Example:

gravity = Vector2D(9.81, 0)
next_position = item.position_as_vector() + gravity.unit()
render_to_buffer(buffer, row, column, height, width)

Render the complex board item from the display buffer to the frame buffer.

This method is automatically called by pygamelib.engine.Screen.render().

Parameters:
  • buffer (numpy.array) – A screen buffer to render the item into.

  • row (int) – The row to render in.

  • column (int) – The column to render in.

  • height (int) – The total height of the display buffer.

  • width (int) – The total width of the display buffer.

restorable()

Returns True if the item is restorable, False otherwise.

Example:

if board.item(4,5).restorable():
    print('The item is restorable')
property row

Convenience method to get the current stored row of the item.

This is absolutely equivalent to access to item.pos[0].

Returns:

The row coordinate

Return type:

int

Example:

if item.row != item.pos[0]:
    print('Something extremely unlikely just happened...')
property screen_column: int

A property to get/set the screen column.

Parameters:

value (int) – the screen column

Return type:

int

property screen_row: int

A property to get/set the screen row.

Parameters:

value (int) – the screen row

Return type:

int

serialize() dict

Return a dictionary with all the attributes of this object.

Returns:

A dictionary with all the attributes of this object.

Return type:

dict

set_can_move(value)

Set the value of the can_move property to value.

Parameters:

value (bool) – The value to set.

Example:

item.set_can_move(False)
set_overlappable(value)

Set the value of the overlappable property to value.

Parameters:

value (bool) – The value to set.

Example:

item.set_overlappable(False)
set_pickable(value)

Set the value of the pickable property to value.

Parameters:

value (bool) – The value to set.

Example:

item.set_pickable(False)
set_restorable(value)

Set the value of the restorable property to value.

Parameters:

value (bool) – The value to set.

Example:

item.set_restorable(False)
property size

A read-only property that gives the size of the item as a 2 dimensions list. The first element is the width and the second the height.

Returns:

The size.

Return type:

list

Example:

# This is a silly example because the Board object does not allow
# that use case.
if item.column + item.size[0] >= board.width:
    Game.instance().screen.display_line(
        f"{item.name} cannot be placed at {item.pos}."
    )
property sprite

A property to easily access and update a complex item’s sprite.

Parameters:

new_sprite (Sprite) – The sprite to set

Example:

npc1 = board_items.ComplexNpc(
                                sprite=npc_sprite_collection['npc1_idle']
                            )
# to access the sprite:
if npc1.sprite.width * npc1.sprite.height > CONSTANT_BIG_GUY:
    game.screen.place(
        base.Text(
            'Big boi detected!!!',
            core.Color(255,0,0),
            style=TextStyle.BOLD,
        ),
        notifications.row,
        notifications.column,
    )
# And to set it:
if game.player in game.neighbors(3, npc1):
    npc1.sprite = npc_sprite_collection['npc1_fight']
store_position(row: int, column: int, layer: int = 0)

Store the BoardItem position for self access.

The stored position is used for consistency and quick access to the self position. It is a redundant information and might not be synchronized.

Parameters:
  • row (int) – the row of the item in the Board.

  • column (int) – the column of the item in the Board.

  • layer – the layer of the item in the Board. By default layer is set to 0.

Example:

item.store_position(3,4)
store_screen_position(row: int, column: int) bool

Store the screen position of the object.

This method is automatically called by Screen.place().

Parameters:
  • row (int) – The row (or y) coordinate.

  • column (int) – The column (or x) coordinate.

Example:

an_object.store_screen_coordinate(3,8)
update_sprite()

Update the complex item with the current sprite.

Note

This method use to need to be called every time the sprite was changed. Starting with version 1.3.0, it is no longer a requirement as BoardComplexItem.sprite was turned into a property that takes care of calling update_sprite().

Example:

item = BoardComplexItem(sprite=position_idle)
for s in [walk_1, walk_2, walk_3, walk_4]:
    # This is not only no longer required but also wasteful as
    # update_sprite() is called twice here.
    item.sprite = s
    item.update_sprite()
    board.move(item, Direction.RIGHT, 1)
    time.sleep(0.2)
property width

Convenience method to get the width of the item.

This is absolutely equivalent to access to item.size[0].

Returns:

The width

Return type:

int

Example:

if item.width > board.width:
    print('The item is too big for the board.')