BoardItem

class pygamelib.board_items.BoardItem(sprixel=None, model=None, name=None, item_type=None, parent=None, pickable=False, overlappable=False, restorable=False, can_move=False, pos=None, value=None, inventory_space=1)

Bases: pygamelib.base.PglBaseObject

Base class for any item that will be placed on a Board.

Parameters:
  • type (str) – A type you want to give your item. It can be any string. You can then use the type for sorting or grouping for example.
  • name (str) – A name for this item. For identification purpose.
  • pos (list) – the position of this item. When the item is managed by the Board and Game engine this member hold the last updated position of the item. It is not updated if you manually move the item. It must be an array of 2 integers [row,column]
  • model (str) – The model to use to display this item on the Board. Be mindful of the space it will require. Default value is ‘*’. This parameter is now deprecated in favor of “sprixel”. If both “sprixel” and “model” are specified, “model” is ignored.
  • parent – The parent object of the board item. Usually a Board or Game object.
  • sprixel (Sprixel) – The sprixel that will represent the item on the Board.
  • pickable (bool) – Represent the capacity for a BoardItem to be pick-up by player or NPC. This parameter is True or False. If sets to None, it’ll be set to False.
  • overlappable (bool) – Represent to be overlapped by another BoardItem. This parameter is True or False. If sets to None, it’ll be set to False.
  • restorable (bool) – Represent the capacity for an Immovable BoardItem to be restored by the board if the item is overlappable and has been overlapped by another BoardItem. This parameter is True or False. If sets to None, it’ll be set to False.
  • can_move (bool) – Represent the ability of the BoardItem to move on the Board. If this parameter is False, the Board.move() method will not allow the item to move. This parameter is True or False. If sets to None, it’ll be set to False.
  • pos – The position of the BoardItem on a Board. Please make sure that you understand what you do before changing that parameter. The position of an item is managed by the Board object and will be updated. In most cases you don’t need to use that parameter. The position is a list of 2 or 3 int: [row, column, layer].
  • value (int | float) – The value of an item. It can be used for any game purpose: a score indicator, a trade value, the amount of XP to grant to a player on a kill, etc.
  • inventory_space (int) – The space that the item takes in the pygamelib.engine.Inventory. This parameter used to be available only for Immovable items but since 1.3.0, every BoardItem can be configured to be pickable, so every BoardItem can now take space in the inventory. Default value is 1.

Note

Starting with version 1.2.0 and introduction of complex items, BoardItems have a size. That size CANNOT be set. It is always 1x1. This is because a BoardItem always takes 1 cell, regardless of its actual number of characters. The size is a read-only property.

Important

In version 1.3.0 the BoardItem object has been reworked to make sure that the pickable, restorable, overlappable and can_move properties are configurable for all items independently of their type. This fixes an issue with restorable: only Immovable objects could be restorable. Now all items can be any combination of these properties. As a developper you are now encouraged to use the corresponding functions to determine the abilities of an item.

Warning

An item cannot be restorable and pickable at the same time. If it’s pickable, it’s put into the inventory of the item overlapping it. Therefor, it cannot be restored. If both restorable and pickable are set to True, one of the 2 is set to False depending on the value of overlappable: if True restorable is set to True and pickable to False and the contrary if overlappable is False.

__init__(sprixel=None, model=None, name=None, item_type=None, parent=None, pickable=False, overlappable=False, restorable=False, can_move=False, pos=None, value=None, inventory_space=1)

Like the object class, this class constructor takes no parameter.

Methods

__init__([sprixel, model, name, item_type, …]) Like the object class, this class constructor takes no parameter.
can_move() Returns True if the item can move, False otherwise.
collides_with(other) Tells if this item collides with another item.
debug_info() Return a string with the list of the attributes and their current value.
display() Print the model WITHOUT carriage return.
distance_to(other) Calculates the distance with an item.
inventory_space A property to get and set the size that the BoardItem takes in the Inventory.
load(data) Load data and create a new BoardItem out of it.
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 board item into a display buffer (not a screen buffer).
serialize() Return a dictionary with all the attributes of this object.
store_position(row, column[, layer]) Store the BoardItem position for self access.

Attributes

column Convenience method to get the current stored column of the item.
height Convenience method to get the height of the item.
model
row Convenience method to get the current stored row of the item.
width Convenience method to get the width of the item.
attach(observer)

Attach an observer to this instance. It means that until it is detached, it will be notified everytime 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)
be_notified(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 paramters 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. This can be None.
  • value (Any) – The new value of the attribute. This can be None.
can_move()

Returns True if the item can move, False otherwise.

Example:

if board.item(4,5).can_move():
    print('The item can move')
collides_with(other)

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 developper 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.
Return type:bool

Example:

if projectile.collides_with(game.player):
    game.player.hp -= 5
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
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.')
inventory_space

A property to get and set the size that the BoardItem takes in the Inventory.

Returns:The size of the item.
Return type:int
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 BoardItem out of it.

Parameters:data (dict) – Data to create a new item (usually generated by serialize())
Returns:A new item.
Return type:~pygamelib.board_items.BoardItem
model
notify(modifier=None, attribute: str = None, value: Any = None) → None

Notify all the observers that a change occurred. Two important points:

  1. The “change” that occurred is not specified (but the notifying object is passed as parameter)
  2. No parameters are passed to the be_notified() method except the notifying object.
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')
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 board item into a display buffer (not a screen 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.

Example:

method()
restorable()

Returns True if the item is restorable, False otherwise.

Example:

if board.item(4,5).restorable():
    print('The item is restorable')
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...')
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)
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}."
    )
store_position(row, column, layer=0)

Store the BoardItem position for self access.

The stored position is used for consistency and quick access to the self postion. 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)
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.')