pigframe 0.2.0

A minimum Python-based game-engine backend library, designed to simplify and streamline the development process of game application.

Pigframe

日本語版 README

Pigframe is a minimum Python-based game-engine backend library, designed to simplify and streamline the development process of game applications. Engineered with flexibility and ease of use in mind, Pigframe provides a robust set of tools and functions that enable developers to create immersive and dynamic gaming experiences.

Key Features:

• Component-Based Architecture: Pigframe adopts a component-based approach, allowing for modular and scalable game development. This architecture facilitates easy addition, modification, and management of game elements.

• Intuitive Scene Management: Manage game scenes seamlessly with Pigframe's intuitive scene transition and control system. This feature allows for smooth transitions and efficient scene organization.

• Efficient Entity-Component System: At the heart of Pigframe is an efficient entity-component system (ECS), which promotes a clean separation of concerns and enhances performance.

• Pythonic Simplicity: Designed with Python's philosophy of simplicity and readability, Pigframe is ideal for those learning game development or individual developers seeking an accessible yet powerful tool.

• Versatile Integration: Pigframe is optimized to work seamlessly with popular Python game libraries like Pyxel and Pygame, making it a perfect choice for diverse and creative game development projects.

Getting Started:

To get started with Pigframe, simply install the package using pip:

pip install pigframe

Contributing:

Contributions to Pigframe are welcome! Whether it's bug reports, feature requests, or code contributions, your input is valuable in making Pigframe better for everyone.

User guide:

• import module

  from pigframe.world import World, System, Event, Screen, Component
  

• create your own world class which has entities, components, systems, events and screens. It is the core of the game.

  # Implement World class for your own project.
  class App(World):
      def __init__(self):
          super().__init__()
          self.init() # write initial process which is unique to the game engine and the game you develop.
      
      ... # other game engine unique methods.
  
  app = App()
  

• create and remove entity

  # Create entity to world.
  entity = app.create_entity() # -> int: entity ID
  # Remove entity from world.
  app.remove_entity(entity) # deletes from entites list
  

• add/remove components to entity

  • add components to entity

    # Add component to entity ID.
    # Components are recorded as values where entity ID is the key inside dict.
    # Component instance are created automatically.
    app.add_component_to_entity(entity, ComponentA, component_argsA) # ComponentA is not an instance of Component but type.
    app.add_component_to_entity(entity, ComponentB, component_argsB) # ComponentB is not an instance of Component but type.
    # getter
    app.get_component(ComponentA) # Returns the list of tuple: entity id which has ComponentA, component implementation. 
    app.get_components(ComponentA, ComponentB) # Returns the list of tuple: entity id which has ComponentA and ComponentB, component implementations. 
    

  • remove components from entity

    app.add_component_to_entity(ent, ComponentA, component_argsA)
    app.add_component_to_entity(ent, ComponentB, component_argsB)
    app.remove_component_from_entity(ent, ComponentA) # remove single component instance from entity
    
    app.add_component_to_entity(ent, ComponentC, component_argsC)
    app.remove_components_from_entity(ent, ComponentB, ComponentC) # remove components instances from entity
    

• use component values inside system, event and screen

  # Example of using get_components() method.
  class SystemA(System):
      def process(self):
          for ent, (component_a, component_b) in self.world.get_components(ComponentA, ComponentB):
              """
              Returns
              -------
              list: list of tuple: entity id, list of components
              """
              component_a.x += component_b.x
              component_a.y += component_b.x
  

• use entity

  # Example of using entity object
  class EventA(Event):
      def __process(self):
          player = self.world.get_entity_object(entity = 0)
          """
          Returns
          -----------
          dict: entity object
              key: component type
              value: component
          """
  

• add scenes to world

  # Add scenes to world.
  app.add_scenes(["launch", "game", "result", "settings"])
  # scenes getter
  app.sceneces # -> [["launch", "game", "result", "settings"]
  

• add/remove system to/from world

  # Add screen to a scene of world. Be sure you have added scenes before adding screens.
  # System instance are created automatically.
  app.add_system_to_scenes(SystemA, "launch", priority = 0, system_args)
  # system with its lower priority than the other systems is executed in advance., by default 0.
  # For here, SystemA().process() runs first in "launch" scene.
  app.add_system_to_scenes(SystemA, "game", priority = 0, system_args)
  app.add_system_to_scenes(SystemB, "launch", priority = 1)
  # Remove system from scene.
  app.remove_system_from_scene(SystemA, ["launch", "game"], system_args = system_args)
  

• add/remove screen to/from world

  # Add screen to a scene of world. Be sure you have added scenes before adding screens.
  # Screen instance are created automatically.
  app.add_screen_to_scenes(ScreenA, "launch", priority = 0)
  app.add_screen_to_scenes(ScreenB, "launch", priority = 0)
  app.add_screen_to_scenes(ScreenC, "game", priority = 0, screen_args)
  # Remove screen from scene.
  app.remove_screen_from_scene(ScreenB, "launch")
  

• add/remove event to/from world

  # Add an event, event triger to a scene of world. Be sure you have added scenes before adding events.
  # Event instance are created automatically.
  app.add_event_to_scene(EventA, "game", callable_triger, priority = 0)
  # Remove event from scene.
  app.remove_event_from_scene(EventA, "game")
  

• add scene transitions settings

  app.add_scene_transition(scene_from = "launch", scene_to = "game", triger = callable_triger)
  # triger has to be callable.
  

• execute systems, events and draw screens

  # Pyxel Example
  class App(World):
      ...
  
      def run(self):
          pyxel.run(self.update, self.draw)
  
      def update(self):
          self.process() # World class has process method.
          # process method calls these internal methods below.
          # 1. process_systems()
          # 1. process_events()
          # 1. scene_manager.process()
  
      def draw(self):
          self.process_screens()
  

  # Pygame Example
  class App(World):
      ...
      
      def run(self):
          while self.running:
              self.update()
              self.draw()
              
      def update(self):
          self.process()
      
      def draw(self):
          self.process_screens()
  

when some components' parameters are entity_id and you want to load saved data which had been created by the previous game, you can put entity_id to create_entity method and use set_next_entity_id method of World class to ensure the same entity_id represents the same game object between the previous game and the current game sessions.

## session1
a = world.create_entity() # -> 0
b = world.create_entity() # -> 1
c = world.create_entity() # -> 2
world.add_components_to_entity(c, Relation, friedns=[b])
## remove a
world.remove_entity(a)

## session2
max_entity_id = 0
for entity_id, data in loaded_data:
    world.create_entity(entity_id=entity_id) # ensure the same entity_id represents the same game object between sessions.
    for component_name, component_data in data["components"].items():
        component_class = globals()[component_name]
        world.add_component_to_entity(entity_id, component_class, **component_data)
    max_entity_id = max(max_entity_id, entity_id)
... # after loading
world.set_next_entity_id(max_entity_id + 1) # prevent entity_id conflict

Examples

game engine	example	contents
Pyxel	2D shooting game	examples of system, event, component, entity and world implementations.
Pygame	control a ball	examples of system, event, component, entity and world implementations.
Pyxel	control a ball	examples of system, event, component, entity and world implementations.