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

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

@@ -0,0 +1,76 @@
+import pyscratch as pysc
+from pyscratch import game
+
+enemy = pysc.create_single_costume_sprite("assets/fish_red_skeleton_outline.png")
+
+
+def clicked():
+    """
+    when the enemy is clicked: 
+    change the enemy location with a fade out effect
+    """
+    game['score'] += 10
+
+
+    for i in range(10):
+        yield 1/game.framerate
+        enemy.set_transparency(1-i/10) # print(1-i/10) if you find this confusing.
+        enemy.scale_by(0.9)
+
+    enemy.x = pysc.random_number(0, game.screen_width)
+    enemy.y = pysc.random_number(0, game.screen_height)
+
+    enemy.set_transparency(1)
+    enemy.set_scale(1)
+    
+enemy.when_this_sprite_clicked().add_handler(clicked)
+
+
+def movement():
+    """
+    when_game_start: 
+    the movement of the enemy
+    """
+
+    centre = (game.screen_width/2, game.screen_height/2)
+
+    while True:
+        yield 1/game.framerate
+
+        speed = 5+game['score']*0.1
+        speed = max(1, speed)
+
+
+        # get the distance to the mouse
+        mouse_x, mouse_y = pysc.get_mouse_pos()
+        distance_to_mouse = enemy.distance_to((mouse_x, mouse_y))
+
+        # enemy avoids the mouse when it is close to the mouse
+        if distance_to_mouse < 200:
+            enemy.point_towards_mouse()
+            enemy.direction += 180
+            enemy.move_indir(speed)
+        
+        # otherwise, go to the centre of the screen 
+        else:
+            enemy.point_towards(centre)
+            enemy.move_indir(speed)
+
+
+enemy.when_game_start().add_handler(movement)
+
+
+
+def reduce_score():
+    """
+    reduce the score for every 0.1 second the enemy is in the centre
+    """
+    centre = (game.screen_width/2, game.screen_height/2)
+
+    while True:
+        yield 0.1
+        
+        if enemy.distance_to(centre) < 50:
+            game['score'] -= 1
+
+enemy.when_game_start().add_handler(reduce_score)

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)
@@ -724,6 +732,9 @@ class Game:
         self._space.gravity = xy
 
     def _new_sprite_of_file(self, caller_file):
+        """
+        return a index of the sprite created in the file
+        """
         if not caller_file in self._sprite_count_per_file:
             self._sprite_count_per_file[caller_file] = 0
         else: 
@@ -732,16 +743,17 @@ class Game:
         return self._sprite_count_per_file[caller_file]
 
 
-    def _add_sprite(self, sprite: Sprite, to_show=True, caller_file=None):
+    def _add_sprite(self, sprite: Sprite, caller_file=None):
 
         self._all_sprites.add(sprite)
         if len(self._all_sprites) > self.max_number_sprite:
             raise RuntimeError('Reached the maximum number sprite. ')
         #self._space.add(sprite.body, sprite.shape)
         self._sprite_click_trigger[sprite] = []
-        if to_show:
-            self._all_sprites_to_show.add(sprite)
-        sprite.update()
+        # if to_show:
+        #     sprite.show()
+            #self._all_sprites_to_show.add(sprite)
+        #sprite.update()
 
         if self.__started_interactive:
             sprite.set_draggable(True)
@@ -784,16 +796,12 @@ class Game:
     def _show_sprite(self, sprite: Sprite):
         """
         Show the sprite. 
-        
-        You can use the alias `sprite.show()` to do the same. 
         """
         self._all_sprites_to_show.add(sprite)
 
     def _hide_sprite(self, sprite: Sprite):
         """
         Hide the sprite. 
-        
-        You can use the alias `sprite.hide()` to do the same. 
         """
         self._all_sprites_to_show.remove(sprite)
 
@@ -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
@@ -713,7 +717,17 @@ class Sprite(pygame.sprite.Sprite):
             if not caller_file == this_file:
                 break
 
+
+        self._intend_to_show = True
+        self._shown = False
+        self.hide()
+        
         count = game._add_sprite(self, caller_file=caller_file)
+        
+        self.update()
+        self.show()
+
+
         self.identifier: str
         """
         An identifier of the sprite for loading sprite states (position and direction).
@@ -760,8 +774,10 @@ class Sprite(pygame.sprite.Sprite):
 
         x, y = self._body.position
         self.image, self.rect, self.mask = self._drawing_manager.on_update(x, y, self.__direction.angle_degrees)
-        
+        self._shown = self._intend_to_show
+
         self._physics_manager.on_update(self.image)
+
         
         if self.__is_dragging:
             self._body.velocity=0,0 
@@ -1364,12 +1380,17 @@ class Sprite(pygame.sprite.Sprite):
         ```
         """
         
-        if not self in game._all_sprites_to_show: 
-            return False
+        # if not self in game._all_sprites_to_show: 
+        #     return False
+        
+        # if not other_sprite in game._all_sprites_to_show:
+        #     return False
         
-        if not other_sprite in game._all_sprites_to_show:
+        if not self._shown: 
+            return False
+
+        if not other_sprite._shown:
             return False
-            
         
         if not pygame.sprite.collide_rect(self, other_sprite): 
             return False
@@ -1380,6 +1401,9 @@ class Sprite(pygame.sprite.Sprite):
         """
         Returns whether or not this sprite is touching the mouse
         """
+        if not self._shown:
+            return False
+        
         mos_x, mos_y = pygame.mouse.get_pos()
 
         if not self.rect.collidepoint((mos_x, mos_y)): 
@@ -1411,12 +1435,17 @@ class Sprite(pygame.sprite.Sprite):
         The hidden sprite is still in the space but it cannot touch another sprites
         """
         game._hide_sprite(self)
+        self._shown = False
+        self._intend_to_show = False
 
     def show(self):
         """
         Shows the sprite.
         """        
         game._show_sprite(self)
+        self._intend_to_show = True
+        # self._shown is set to True only during the update 
+        
 
     @override
     def remove(self, *_):
@@ -1430,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
 
 
@@ -1455,8 +1485,10 @@ class Sprite(pygame.sprite.Sprite):
             shape_size_factor = self._physics_manager.shape_size_factor, 
             body_type = self._body.body_type, 
         )
-        if not self in game._all_sprites_to_show:
-            game._hide_sprite(sprite)
+        if not self._intend_to_show:
+            sprite.hide()
+        else: 
+            sprite.show()
 
         if self.__rotation_style == _RotationStyle.LEFTRIGHT:
             sprite.set_rotation_style_left_right()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyscratch-pysc
-Version: 1.0.3
+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
@@ -22,10 +22,15 @@ 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
 
 
-
-## Change History
+### 12 Sep 2025
+**v1.0.4**  
+Fixed the show/hide collision related problem due to the deferral of movement to the frame update.
 
 ### 07 Sep 2025
 **v1.0.3**