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, animation: Animation = None, particle_emitter=None)
Bases:
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 forImmovable
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.animation (
Animation
) – An animation to animate the item sprixel.particle_emitter (
ParticleEmitter
) – A particle emitter that is attached to this item.
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 developer 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, animation: Animation = None, particle_emitter=None)
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.
attach
(observer)Attach an observer to this instance.
can_move
()Returns True if the item can move, False otherwise.
collides_with
(other[, projection_offset])Tells if this item collides with another item.
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.
load
(data)Load data and create a new BoardItem out of it.
notify
([modifier, attribute, value])Notify all the observers that a change occurred.
Returns True if the item is overlappable, False otherwise.
pickable
()Returns True if the item is pickable, False otherwise.
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).
Returns True if the item is restorable, False otherwise.
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.
Attributes
A property to get and set an
Animation
for this item.Convenience method to get the current stored column of the item.
Return the heading of the item.
Convenience method to get the height of the item.
A property to get and set the size that the BoardItem takes in the
Inventory
.Convenience method to get the current stored layer number of the item.
Convenience method to get the current stored row of the item.
A property to get/set the screen column.
A property to get/set the screen row.
A read-only property that gives the size of the item as a 2 dimensions list.
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()
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, 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:
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
A property to get and set the size that the BoardItem takes in the
Inventory
.- Returns:
The size of the item.
- Return type:
int
- 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 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
- 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:
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.
- 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}." )
- 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:
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)
- 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.')