Sprixel

class pygamelib.gfx.core.Sprixel(model='', bg_color=None, fg_color=None, is_bg_transparent=None)

Bases: PglBaseObject

A sprixel is the representation of 1 cell of the sprite or one cell on the Board. It is not really a pixel but it is the closest notion we’ll have. A Sprixel has a background color, a foreground color and a model. All regular BoardItems can now use a sprixel instead of a model (but simple model is still supported of course).

In the terminal, a sprixel is represented by a single character.

If the background color and the is_bg_transparent are None, the sprixel will be automatically configured with transparent background. In that case, as we cannot really achieve transparency in the console, the sprixel will take the background color of whatever it is overlapping.

Important

BREAKING CHANGE: in version 1.3.0 background and foreground colors use the new Color object. Therefor, Sprixel does not accept ANSI sequences anymore for the bg_color and fg_color parameters.

Example:

player = Player(sprixel=Sprixel(
                                '#',
                                Color(128,56,32),
                                Color(255,255,0),
                                ))
__init__(model='', bg_color=None, fg_color=None, is_bg_transparent=None)
Parameters:
  • model (str) – The model, it can be any string. Preferrably a single character.

  • bg_color (Color) – A Color object to configure the background color.

  • fg_color (Color) – A Color object to configure the foreground color.

  • is_bg_transparent (bool) – Set the background of the Sprixel to be transparent. It tells the engine to replace the background of the Sprixel by the background color of the overlapped sprixel.

Methods

__init__([model, bg_color, fg_color, ...])

param model:

The model, it can be any string. Preferrably a single character.

attach(observer)

Attach an observer to this instance.

black_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLACK_RECT.

black_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLACK_SQUARE.

blue_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLUE_RECT.

blue_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLUE_SQUARE.

copy()

Returns a (deep) copy of the sprixel.

cyan_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.CYAN_RECT.

cyan_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.CYAN_SQUARE.

detach(observer)

Detach an observer from this instance.

from_ansi(string[, model])

Takes an ANSI string, parse it and return a Sprixel.

green_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.GREEN_RECT.

green_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.GREEN_SQUARE.

handle_notification(subject[, attribute, value])

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

load(data)

Create a new Sprixel object based on serialized data.

magenta_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.MAGENTA_RECT.

magenta_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.MAGENTA_SQUARE.

notify([modifier, attribute, value])

Notify all the observers that a change occurred.

red_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.RED_RECT.

red_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.RED_SQUARE.

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

Render the sprixel from the display buffer to the frame buffer.

serialize()

Serialize a Sprixel into a dictionary.

store_screen_position(row, column)

Store the screen position of the object.

white_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.WHITE_RECT.

white_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.WHITE_SQUARE.

yellow_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.YELLOW_RECT.

yellow_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.YELLOW_SQUARE.

Attributes

bg_color

A property to get/set the background color of the Sprixel.

fg_color

A property to get/set the foreground color of the Sprixel.

length

Return the true length of the model.

model

A property to get/set the model of the Sprixel.

screen_column

A property to get/set the screen column.

screen_row

A property to get/set the screen row.

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)
property bg_color

A property to get/set the background color of the Sprixel.

Parameters:

value (Color) – The new color

When the bg_color is changed, the observers are notified of the change with the pygamelib.gfx.core.Sprixel.bg_color:changed event. The new bg_color is passed as the value parameter.

Example:

# Access the sprixel's color
sprix.bg_color
# Set the sprixel's background color to some blue
sprix.bg_color = Color(0,128,255)
classmethod black_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLACK_RECT. The difference is that BLACK_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.black_rect()
classmethod black_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLACK_SQUARE. The difference is that BLACK_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.black_square()
classmethod blue_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLUE_RECT. The difference is that BLUE_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.blue_rect()
classmethod blue_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.BLUE_SQUARE. The difference is that BLUE_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.blue_square()
copy()

Returns a (deep) copy of the sprixel.

New in version 1.3.0.

classmethod cyan_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.CYAN_RECT. The difference is that CYAN_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.cyan_rect()
classmethod cyan_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.CYAN_SQUARE. The difference is that CYAN_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.cyan_square()
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)
property fg_color

A property to get/set the foreground color of the Sprixel.

Parameters:

value (Color) – The new color

When the fg_color is changed, the observers are notified of the change with the pygamelib.gfx.core.Sprixel.fg_color:changed event. The new fg_color is passed as the value parameter.

Example:

# Access the sprixel's color
sprix.fg_color
# Set the sprixel's foreground color to some green
sprix.fg_color = Color(0,255,128)
static from_ansi(string, model='▄')

Takes an ANSI string, parse it and return a Sprixel.

Parameters:
  • string (str) – The ANSI string to parse.

  • model (str) – The character used to represent the sprixel in the ANSI sequence. Default is “▄”

Example:

new_sprixel = Sprixel.from_ansi(
    "\x1b[48;2;139;22;19m\x1b[38;2;160;26;23m▄\x1b[0m"
)

Warning

This has mainly be tested with ANSI string generated by climage. If you find any issue, please report it

classmethod green_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.GREEN_RECT. The difference is that GREEN_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.green_rect()
classmethod green_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.GREEN_SQUARE. The difference is that GREEN_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.green_square()
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 length

Return the true length of the model.

New in version 1.3.0.

With UTF8 and emojis the length of a string as returned by python’s len() function is often very wrong. For example, the len(”x1b[48;2;139;22;19mx1b[38;2;160;26;23m▄x1b[0m”) returns 39 when it should return 1.

This method returns the actual printing/display size of the sprixel’s model.

Note

This is a read only value. It is automatically updated when the model is changed.

Example:

if sprix.length > 2:
    print(
        f"Warning: that sprixel {sprix} will break the rest of the "
        "board's alignement"
        )
classmethod load(data)

Create a new Sprixel object based on serialized data.

New in version 1.3.0.

Parameters:

data (dict) – Data loaded from JSON data (deserialized).

Return type:

Sprixel

Example:

new_sprite = Sprixel.load(json_parsed_data['default_sprixel'])
classmethod magenta_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.MAGENTA_RECT. The difference is that MAGENTA_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.magenta_rect()
classmethod magenta_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.MAGENTA_SQUARE. The difference is that MAGENTA_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.magenta_square()
property model

A property to get/set the model of the Sprixel.

Parameters:

value (str) – The new model

When the model is changed, the observers are notified of the change with the pygamelib.gfx.core.Sprixel.model:changed event. The new model is passed as the value parameter.

Example:

# Get the sprixel's model
sprix.model
# Set the sprixel's model to "@"
sprix.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()
classmethod red_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.RED_RECT. The difference is that RED_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.red_rect()
classmethod red_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.RED_SQUARE. The difference is that RED_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.red_square()
render_to_buffer(buffer, row, column, buffer_height, buffer_width)

Render the sprixel from the display buffer to the frame buffer.

New in version 1.3.0.

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.

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()

Serialize a Sprixel into a dictionary.

New in version 1.3.0.

Returns:

The class as a dictionary

Return type:

dict

Example:

json.dump( sprixel.serialize() )
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)
classmethod white_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.WHITE_RECT. The difference is that WHITE_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.white_rect()
classmethod white_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.WHITE_SQUARE. The difference is that WHITE_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Example:

sprixel = Sprixel.white_square()
classmethod yellow_rect()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.YELLOW_RECT. The difference is that YELLOW_RECT is a string and this one is a Sprixel that can be manipulated more easily.

Note

Yellow is often rendered as brown.

Example:

sprixel = Sprixel.yellow_rect()
classmethod yellow_square()

This class method returns a sprixel that is the equivalent of pygamelib.assets.graphics.YELLOW_SQUARE. The difference is that YELLOW_SQUARE is a string and this one is a Sprixel that can be manipulated more easily.

Note

Yellow is often rendered as brown.

Example:

sprixel = Sprixel.yellow_square()