pyscratch-pysc 1.0.4__py3-none-any.whl → 2.0.0__py3-none-any.whl

examples/tutorial-day1/in-steps/5-backdrops/friend.py

@@ -0,0 +1,49 @@
+import pyscratch as pysc
+import pygame
+game = pysc.game
+
+friend = pysc.create_single_costume_sprite("assets/fish_orange_outline.png")
+
+def movement():
+    """
+    when_game_start: 
+    the movement of the friend: always moving away from the curosr
+    """
+    centre = game.screen_width/2, game.screen_height/2
+    while True:
+        yield 1/game.framerate
+        mouse_x, mouse_y = pysc.get_mouse_pos()
+        if friend.distance_to((mouse_x, mouse_y)) < 200:
+            friend.point_towards_mouse()
+            friend.direction += 180
+            friend.move_indir(2)
+        
+        else:
+            friend.point_towards(centre)
+            friend.move_indir(2)
+
+friend.when_game_start().add_handler(movement)
+        
+
+
+def check_if_centred():
+    """
+    when_game_start: 
+    move away when near the centre
+    """
+    centre = game.screen_width/2, game.screen_height/2
+    while True:
+        yield 1/game.framerate
+        if friend.distance_to(centre) < 50:
+            game['score'] += 10
+
+            new_x = pysc.random_number(0, game.screen_width)
+            new_y = pysc.random_number(0, game.screen_height)
+
+            friend.x = new_x
+            friend.y = new_y
+    
+friend.when_game_start().add_handler(check_if_centred)
+        
+
+

examples/tutorial-day1/in-steps/5-backdrops/main.py

@@ -0,0 +1,26 @@
+import pyscratch as pysc
+from pyscratch import game
+import chest, enemy, friend
+       
+# background
+bg0 = pysc.load_image("assets/undersea_bg.png")
+bg0 = pysc.scale_to_fit_aspect(bg0, (1024, 576))
+game.add_backdrop('bg0', bg0)
+
+bg1 = pysc.load_image("assets/Cat In Space Wallpaper Hq.jpg")
+bg1 = pysc.scale_to_fit_aspect(bg1, (1024, 576))
+game.add_backdrop('bg1', bg1)
+
+
+
+def on_game_start():
+    game.switch_backdrop('bg0')
+
+game.when_game_start().add_handler(on_game_start)
+
+
+# starting the game
+game.update_screen_mode((1024, 576))
+game.start(show_mouse_position=True)
+
+

examples/tutorial-day1/main.py

@@ -0,0 +1,48 @@
+import pyscratch as pysc
+import pygame
+import target, enemy, chest, friend#, text
+
+game = pysc.game
+
+# mouse 
+pygame.mouse.set_visible(False)
+
+
+# background
+bg0 = pysc.load_image("assets/undersea_bg.png")
+bg0 = pysc.scale_to_fit_aspect(bg0, (1024, 576))
+game.add_backdrop('bg0', bg0)
+
+bg1 = pysc.load_image("assets/Cat In Space Wallpaper Hq.jpg")
+bg1 = pysc.scale_to_fit_aspect(bg1, (1024, 576))
+game.add_backdrop('bg1', bg1)
+
+game.switch_backdrop('bg0')
+
+# sound
+game.load_sound("hit", "assets/impactMetal_light_004.ogg")
+game.load_sound("background", "assets/Circus-Theme-Entry-of-the-Gladiators-Ragtime-Version(chosic.com).mp3")
+
+def play_loop():
+    while True:
+        game.play_sound("background", volume=0)
+        yield 2*60+33
+game.when_game_start().add_handler(play_loop)
+
+
+
+
+def background():
+    while True:
+        yield 1/game.framerate
+        if game['score'] < 0: 
+            game.switch_backdrop('bg1')
+
+        
+game.when_game_start().add_handler(background)
+
+
+game.update_screen_mode((1024, 576))
+game.start(show_mouse_position=True)
+
+

examples/tutorial-day1/target.py

@@ -0,0 +1,14 @@
+import pyscratch as pysc
+game = pysc.game
+target = pysc.create_single_costume_sprite("assets/target_b.png")
+
+# 3. Flow control
+def follow_mouse():
+    game.bring_to_front(target)
+    while True:
+        yield 1/game.framerate
+        mouse_x, mouse_y = pysc.get_mouse_pos()
+        target.x = mouse_x
+        target.y = mouse_y
+    
+target.when_game_start().add_handler(follow_mouse)

examples/tutorial-day1/text.py

@@ -0,0 +1,23 @@
+import pyscratch as pysc
+import pygame
+game = pysc.game
+
+text_box = pysc.create_rect_sprite((200, 200, 200, 20), 700, 90)
+font = pygame.font.Font('assets/Kenney Future.ttf', size=96)
+
+text_box.write_text("YOU LOSE", font, offset=(350, 45))
+
+
+text_box.hide()
+
+text_box.set_draggable(True)
+text_box.set_xy((260, 195))
+text_box.direction = -35
+
+
+
+def game_end(): 
+    text_box.show()
+
+text_box.when_backdrop_switched(1).add_handler(game_end)
+

pyscratch/game_module.py

@@ -12,6 +12,7 @@ from pathlib import Path
 import threading
 import time
 import json, inspect
+from typing_extensions import deprecated
 
 import numpy as np
 import pygame
@@ -309,16 +310,23 @@ class Game:
         self._mouse_drag_trigger = self.create_pygame_event([pygame.MOUSEBUTTONDOWN, pygame.MOUSEBUTTONUP, pygame.MOUSEMOTION])
         self._mouse_drag_trigger.add_handler(self.__mouse_drag_handler)
 
-        ## Backdrops
-        self.backdrops: List[pygame.Surface] = []
-        """A list of all the loaded backdrop images. You will not need to interact with this property directly."""
+        # Backdrops
+        self.backdrops_by_key: Dict[str, pygame.Surface] = {}
+        self.backdrop_indices_by_key: Dict[str, int] = {}
+        self.backdrop_keys: List[str] = []
+
+# TODO: testing needed
 
         self.__screen_width: int = 0
         self.__screen_height: int = 0
         self.__framerate: float = 0
 
-
+        # TODO index and key need to be changed together 
+        # the index is remained for the next_backdrop function
         self.__backdrop_index = None
+        self.__backdrop_key = None
+
+        # TODO: the event is now triggered by the name not the index
         self._backdrop_change_triggers: List[Event] = []
 
         self._top_edge: Sprite
@@ -627,8 +635,8 @@ class Game:
             # Drawing
 
             #self._screen.fill((30, 30, 30))
-            if not (self.__backdrop_index is None): 
-                self._screen.blit(self.backdrops[self.__backdrop_index], (0, 0))
+            if not (self.__backdrop_key is None): 
+                self._screen.blit(self.backdrops_by_key[self.__backdrop_key], (0, 0))
             else:
                 self._screen.fill((255,255,255))
                 helper._draw_guide_lines(self._screen, guide_lines_font, 100, 500)
@@ -745,7 +753,7 @@ class Game:
         # if to_show:
         #     sprite.show()
             #self._all_sprites_to_show.add(sprite)
-        sprite.update()
+        #sprite.update()
 
         if self.__started_interactive:
             sprite.set_draggable(True)
@@ -831,6 +839,7 @@ class Game:
         """
         self._all_sprites_to_show.get_layer_of_sprite(sprite)
 
+    @deprecated("use add_backdrop")
     def set_backdrops(self, images: List[pygame.Surface]):
         """
         Set the list of all available backdrops. This function is meant to be run before the game start. 
@@ -849,32 +858,63 @@ class Game:
         pysc.game.switch_backdrop(1) 
         ```
         """
-        self.backdrops = images
-    
+        for idx, img in enumerate(images):
+            self.add_backdrop(str(idx), img)
+
+    def add_backdrop(self, key, image: pygame.Surface):
+        """
+        Add the image as a backdrop, and index it with the key so it can be switched to using switch_backdrop 
+
+        Example:
+        ```python
+        bg0 = pysc.load_image("assets/undersea_bg.png")'
+
+        game.add_backdrop('background0', bg0)
+        game.switch_backdrop('background0')
+        ```
+
+        """
+        assert not key in self.backdrops_by_key, f"the name '{key}' is already in used"
+        self.backdrop_keys.append(key)
+        self.backdrops_by_key[key] = image
+        self.backdrop_indices_by_key[key] = len(self.backdrop_keys) - 1 # minus one since the new one is added in the previous line
+        
+
     @property
     def backdrop_index(self):
         """
-        The index of the current backdrops. For example, if you do `game.switch_backdrop(0)`, `game.backdrop_index` would be `0`.
+        The index of the current backdrops. 
         """
         return self.__backdrop_index
+    
 
-    def switch_backdrop(self, index:Optional[int]=None):
+    @property
+    def backdrop_key(self):
+        """
+        The key (i.e. name) of the current backdrops.
+        """
+        return self.__backdrop_key
+    
+    def switch_backdrop(self, key:Optional[str]=None):
         """
         Change the backdrop by specifying the index of the backdrop.  
         """
 
-        if index != self.__backdrop_index:
-            self.__backdrop_index = index
+        if key != self.__backdrop_key:
+            self.__backdrop_key = key
+            self.__backdrop_index = None if key is None else self.backdrop_indices_by_key[key] 
             for t in self._backdrop_change_triggers:
-                t.trigger(index)
-            self._specific_backdrop_event_emitter.on_event(self.__backdrop_index)
+                t.trigger(key)
+            self._specific_backdrop_event_emitter.on_event(key)
 
+    # TODO: testing needed
     def next_backdrop(self):
         """
         Switch to the next backdrop. 
         """
         if not self.__backdrop_index is None: 
-            self.switch_backdrop((self.__backdrop_index+1) % len(self.backdrops))
+            idx = (self.__backdrop_index+1) % len(self.backdrops_by_key)
+            self.switch_backdrop(self.backdrop_keys[idx])
         
     # all events 
 
@@ -1026,19 +1066,19 @@ class Game:
             t = _declare_callback_type(t, sample_callback)
         return t
 
-
-    def when_backdrop_switched(self, backdrop_index, associated_sprites : Iterable[Sprite]=[]) -> Event[[]]:
+    # TODO: testing needed
+    def when_backdrop_switched(self, backdrop_key: str, associated_sprites : Iterable[Sprite]=[]) -> Event[[]]:
         """
         It is recommended to use the `Sprite.when_backdrop_switched` alias instead of this method, 
         so you don't need to specify the `associated_sprites` in every event.  
 
-        Returns an `Event` that is triggered when the game is switched to a backdrop at `backdrop_index`.
+        Returns an `Event` that is triggered when the game is switched to a backdrop with the key `backdrop_key`.
 
         The event handler does not take in any parameter.
 
         Parameters
         ---
-        backdrop_index: int
+        backdrop_key: str
             The index of the backdrop  
 
         associated_sprites: List[Sprite]
@@ -1053,10 +1093,11 @@ class Game:
                 return
             t = _declare_callback_type(t, sample_callback)
 
-        self._specific_backdrop_event_emitter.add_event(backdrop_index, t)
+        self._specific_backdrop_event_emitter.add_event(backdrop_key, t)
         return t
- 
-    def when_any_backdrop_switched(self, associated_sprites : Iterable[Sprite]=[]) -> Event[[int]]:
+    
+    # TODO: testing needed
+    def when_any_backdrop_switched(self, associated_sprites : Iterable[Sprite]=[]) -> Event[[Union[str,None]]]:
         """
         It is recommended to use the `Sprite.when_any_backdrop_switched` alias instead of this method, 
         so you don't need to specify the `associated_sprites` in every event.  
@@ -1064,7 +1105,7 @@ class Game:
         Returns an `Event` that is triggered when the backdrop is switched. 
 
         The event handler have to take one parameter:
-        - **idx** (int): The index of the new backdrop  
+        - **str** (str): The key of the new backdrop  
         
         Parameters
         ---
@@ -1075,7 +1116,7 @@ class Game:
         t = self._create_event(associated_sprites)
         self._backdrop_change_triggers.append(t)
         if TYPE_CHECKING:
-            def sample_callback(idx: int)-> Any:
+            def sample_callback(key: Union[str, None])-> Any:
                 return
             t = _declare_callback_type(t, sample_callback)
 

pyscratch/sprite.py

@@ -165,7 +165,7 @@ def create_single_costume_sprite(image_path, *args, **kwargs):
     return Sprite(frame_dict, "always", *args, **kwargs)
 
 
-def create_shared_data_display_sprite(key, font, size = (150, 50), bg_colour=(127, 127, 127), text_colour=(255,255,255), position: Optional[Tuple[float, float]]=None, update_period=0.1, **kwargs):
+def create_shared_data_display_sprite(key, font:Optional[pygame.font.Font]=None, size = (150, 50), bg_colour=(127, 127, 127), text_colour=(255,255,255), position: Optional[Tuple[float, float]]=None, update_period=0.1, **kwargs):
     """
     Create a display for a variable inside shared_data given the dictionary key (i.e. the name of the variable). 
     The variable display will update every `update_period` seconds.
@@ -191,8 +191,9 @@ def create_shared_data_display_sprite(key, font, size = (150, 50), bg_colour=(12
     ---
     key: str
         The dictionary key of the variable in `game.shared_data` that you want to display.
-    font: pygame.font.Font
+    font: None or pygame.font.Font
         The pygame font object. Refer to the website of pygame for more details.
+        If None, a default font will be used. 
     size: Tuple[float, float]
         The size of the display panel
     bg_colour: Tuple[int, int, int] or Tuple[int, int, int, int] 
@@ -207,6 +208,9 @@ def create_shared_data_display_sprite(key, font, size = (150, 50), bg_colour=(12
         Whatever the `Sprite` constructor takes, except `frame_dict`,`starting_animation` & `position`
     """
 
+    if font is None:
+        font = pygame.font.Font(None, 36)
+
     w, h = size
     if position is None:
         position = w/2+25, h/2+25
@@ -716,10 +720,13 @@ class Sprite(pygame.sprite.Sprite):
 
         self._intend_to_show = True
         self._shown = False
-        self.show()
+        self.hide()
         
         count = game._add_sprite(self, caller_file=caller_file)
         
+        self.update()
+        self.show()
+
 
         self.identifier: str
         """
@@ -1452,7 +1459,8 @@ class Sprite(pygame.sprite.Sprite):
         my_sprite.remove()
         ```
         """
-        game._remove_sprite(self)
+        self.hide() # prevent collision
+        game._remove_sprite(self) 
         self.__removed = True
 
 

{pyscratch_pysc-1.0.4.dist-info → pyscratch_pysc-2.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyscratch-pysc
-Version: 1.0.4
+Version: 2.0.0
 Summary: A Python game development framework designed to provide an easy transitioning from Scratch to Python
 Author-email: Daniel Ka-Wa Chan <kwdaniel525@protonmail.com>
 License: MIT
@@ -23,6 +23,10 @@ For more information, see: https://kwdchan.github.io/pyscratch/
 
 
 ## Change History
+### 12 Oct 2025
+**v2.0.0**
+The backdrops are now indexed by keys instead of integers
+
 
 ### 12 Sep 2025
 **v1.0.4**