simplay.core – Core components of Simplay

class simplay.core.VisualEnvironment(initial_time: int | float = 0)

Bases: Environment

Extends the Environment class with visualization.

class simplay.core.VisualComponent(env: VisualEnvironment, id: str, type: ComponentType, visual: str, tint: int = 16777215)

Base class for all visual components.

Parameters:

  • env – The environment instance.

  • id – The id of the component.

  • type – The type of the component, one of ComponentType..

  • visual – The visualization of the component, must be registered in the VisualizationManager.

  • tint – The tint of the component. The tint is multiplied with the pixel value of each pixel. To use HEX values, write them as 0xRRGGBB. For example: 0xFF0000 is red, 0x00FF00 is green, 0x0000FF is blue. If the whole image is white, tinting it will change the color of the image. If the image is black, tinting it will have no effect. If no tint should be applied, set it to 0xFFFFFF, which is the default value.

Raises:
static create_custom_component(env: VisualEnvironment, id: str, visual: str, pos_x: int = 0, pos_y: int = 0, visible: bool = True, tint: int = 16777215) → VisualComponent

Creates a non-simulation component, i.e. a component that is not part of the simulation, but can be used to visualize other components.

The positional parameters are used to directly set the position of the component. If you want to move the component later, use the is_at() method.

Parameters:

  • env – The environment to create the component in.

  • id – The id of the component.

  • visual – The visual to use for the component.

  • pos_x – The x coordinate of the component.

  • pos_y – The y coordinate of the component.

  • visible – Whether the component should be visible.

  • tint – The tint color of the component.

Returns:

The created component.

has_decorating_text(text: str)

Adds an SetDecoratingText event for the given component to the EventQueue.

Parameters:

text – The text to display.

has_frame(frame: int)

Adds an SetSpriteFrame event for the given component to the EventQueue.

Parameters:

frame – The index of the frame to display.

has_original_tint()

Adds an SetTintColor event for the given component to the EventQueue, resetting the tint color to its initial value.

has_tint(color: int)

Adds an SetTintColor event for the given component to the EventQueue.

Parameters:

color – The color to tint the component with, as an integer. To use HEX values, write them as 0xRRGGBB. For example: 0xFF0000 is red, 0x00FF00 is green, 0x0000FF is blue.

is_at(x: int, y: int)

Adds an SetPosition event for the given component to the EventQueue.

Parameters:

  • x – The x coordinate of the component.

  • y – The y coordinate of the component.

is_interacting_with(target: VisualComponent)

Adds an SetInteracting event for the given component to the EventQueue.

Parameters:

target – The component the first component is interacting with.

Raises:

TypeError – If the target is not a VisualComponent.

is_invisible()

Adds an SetVisible event for the given component to the EventQueue, making it invisible.

is_near(target: VisualComponent)

Adds an MoveNear event for the given component to the EventQueue.

Parameters:

target – The target component.

Raises:

TypeError – If the target is not a VisualComponent.

is_near_cell(x: int, y: int)

Adds an MoveNearCell event for the given component to the EventQueue.

Parameters:

  • x – The x coordinate of the target cell.

  • y – The y coordinate of the target cell.

is_no_longer_interacting_with(target: VisualComponent)

Adds an SetNotInteracting event for the given component to the EventQueue.

Parameters:

target – The component the first component is not interacting with anymore.

Raises:

TypeError – If the target is not a VisualComponent.

is_visible()

Adds an SetVisible event for the given component to the EventQueue, making it visible.

class simplay.core.VisualizationManager

This class acts as a central point for all entities, visuals and events.

add_entity(entity: VisualComponent, type: ComponentType)

Add an entity to the visualization.

Parameters:

  • entity – The entity to add.

  • type – The type of the entity, one of ComponentType.

Raises:
add_event(event: VisualEvent)

Add an event to the visualization.

Parameters:

event – The event to add.

entities

The entities of the simulation.

events

The events that happened in the simulation.

grid

The grid that is used for the visualization.

register_sprites(id: str, frames: List[str])

Register sprites with the manager.

Parameters:

  • id – The id of the visual, it must be unique and can be used to reference the visual in components.

  • frames – A list of paths to the frames of the sprite.

Raises:
register_visual(id: str, path: str)

Register a visual with the manager. The visual is a sprite with a list of frames whose length is equal to one.

Parameters:

  • id – The id of the visual, it must be unique and can be used to reference the visual in components.

  • path – The path to the visual.

Raises:
serialize() → str

Serialize the visualization to a JSON string.

serialize_for_jupyter() → dict

Serialize the visualization for use with Jupyter.

set_grid(grid: VisualGrid)

Set the grid for the visualization.

Parameters:

grid – The grid to use.

Raises:
visuals

The visuals that have been registered with the manager.

write_to_file(filename: str)

Write the visualization to a file.

Parameters:

filename – The name of the file to write to.