pygamestudio 1.0.0.dev5__tar.gz → 1.0.0.dev7__tar.gz

{pygamestudio-1.0.0.dev5 → pygamestudio-1.0.0.dev7}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: pygamestudio
-Version: 1.0.0.dev5
-Summary: Let's create pygame visually!
+Version: 1.0.0.dev7
+Summary: Let's create python games visually!
 Project-URL: Documentation, https://pygamestudio.com/tutorial/installation
 Project-URL: Homepage, https://pygamestudio.com
 Project-URL: Github, https://github.com/pygamestudio/pygamestudio
@@ -42,7 +42,7 @@ Description-Content-Type: text/markdown
 English  |  [简体中文](https://github.com/pygamestudio/pygamestudio/blob/main/README_zh-CN.md)
 </div>
 
-**Pygame Studio** is a visual editor built specifically for **pygame-ce**, designed to help users create pygame-ce projects visually, making it easier for beginners, students, and hobby developers to get started with pygame development.
+**Pygame Studio** is a visual editor built with **PyGame-ce** and **PySide6**, designed to help users create Python games visually, making it easier for beginners, students, and hobby developers to get started with game development.
 
 <br>
 
@@ -114,7 +114,7 @@ Once created, the game project will be displayed in the Dashboard.
 
 **3.** Double-click the created project to open the editing window and start your creation.
 
-<img src="https://i-blog.csdnimg.cn/direct/28198f7ded9143f58f866c9a7e8d6dd2.png" width="800"/>
+<img src="https://i-blog.csdnimg.cn/direct/f1dfa703ce8843b6bd5b62bb3c8b6cc3.png" width="800"/>
 
 <br>
 

{pygamestudio-1.0.0.dev5 → pygamestudio-1.0.0.dev7}/README.md

@@ -13,7 +13,7 @@
 English  |  [简体中文](https://github.com/pygamestudio/pygamestudio/blob/main/README_zh-CN.md)
 </div>
 
-**Pygame Studio** is a visual editor built specifically for **pygame-ce**, designed to help users create pygame-ce projects visually, making it easier for beginners, students, and hobby developers to get started with pygame development.
+**Pygame Studio** is a visual editor built with **PyGame-ce** and **PySide6**, designed to help users create Python games visually, making it easier for beginners, students, and hobby developers to get started with game development.
 
 <br>
 
@@ -85,7 +85,7 @@ Once created, the game project will be displayed in the Dashboard.
 
 **3.** Double-click the created project to open the editing window and start your creation.
 
-<img src="https://i-blog.csdnimg.cn/direct/28198f7ded9143f58f866c9a7e8d6dd2.png" width="800"/>
+<img src="https://i-blog.csdnimg.cn/direct/f1dfa703ce8843b6bd5b62bb3c8b6cc3.png" width="800"/>
 
 <br>
 

{pygamestudio-1.0.0.dev5 → pygamestudio-1.0.0.dev7}/README_zh-CN.md

@@ -13,7 +13,7 @@
 [English](https://github.com/pygamestudio/pygamestudio)  |  简体中文
 </div>
 
-**Pygame Studio** 是专为 **pygame-ce** 打造的可视化编辑器，支持以可视化方式制作 pygame-ce 项目，让编程新手、在校学生以及业余开发者都能更轻松地入门 Pygame 游戏开发。
+**Pygame Studio** 是基于 **PyGame-ce** 和 **PySide6** 打造的可视化编辑器，支持以可视化方式制作 Python 游戏，让编程新手、在校学生以及业余开发者都能更轻松地入门游戏开发。
 
 <br>
 
@@ -85,7 +85,7 @@ pygs
 
 **3.** 双击已创建的项目，即可打开编辑窗口，开始你的游戏创作。
 
-<img src="https://i-blog.csdnimg.cn/direct/28198f7ded9143f58f866c9a7e8d6dd2.png" width="800"/>
+<img src="https://i-blog.csdnimg.cn/direct/f1dfa703ce8843b6bd5b62bb3c8b6cc3.png" width="800"/>
 
 <br>
 

{pygamestudio-1.0.0.dev5 → pygamestudio-1.0.0.dev7}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pygamestudio"
-version = "1.0.0.dev5"
+version = "1.0.0.dev7"
 authors = [{ name="Louis Ren", email="louis@pygamestudio.com" }]
-description = "Let's create pygame visually!"
+description = "Let's create python games visually!"
 readme = "README.md"
 license-files = ["LICEN[CS]E*"]
 requires-python = ">=3.9"

pygamestudio-1.0.0.dev7/src/pygamestudio/api/__init__.py

@@ -0,0 +1,7 @@
+from .config.project import *
+from .core.game import *
+from .core.scene import *
+from .core.audio import *
+from .event.constant import *
+
+from pygamestudio.game.object import *

pygamestudio-1.0.0.dev7/src/pygamestudio/api/core/audio.py

@@ -0,0 +1,217 @@
+"""
+Audio manager API for generated games.
+
+Provides a simple interface to play sound effects and background music:
+
+    import pygamestudio as studio
+
+    studio.play_sound('./audio/jump.wav')
+    studio.play_music('./audio/bgm.ogg', loops=-1)
+    studio.set_music_volume(0.5)
+    studio.stop_sound('./audio/jump.wav')
+
+Sound files are resolved relative to the project path (the project's `audio/`
+folder). The audio mixer is initialized lazily on first use; if no audio device
+is available, all calls become no-ops with a warning instead of crashing.
+"""
+
+import os
+import pygame
+from pathlib import Path
+from pygamestudio.common.i18n.translator import Translator as T
+
+
+class AudioManager:
+    def __init__(self):
+        self._is_available = False
+        self._sounds = {}               # absolute path -> pygame.mixer.Sound
+        self._looping_channels = {}     # absolute path -> Channel (looping sfx)
+        self._music_volume = 1.0
+
+    # ---------- internals ----------
+
+    def _init_mixer(self) -> bool:
+        """Initialize pygame.mixer lazily. Returns False when audio is unavailable."""
+        if self._is_available:
+            return True
+        try:
+            if not pygame.mixer.get_init():
+                pygame.mixer.init()
+            self._is_available = True
+        except Exception as e:
+            print(T.tr('api.fail_to_init_mixer', 'Failed to initialize audio mixer: {}').format(e))
+            self._is_available = False
+        return self._is_available
+
+    def _resolve_path(self, sound_path) -> Path:
+        path = Path(sound_path)
+        if path.is_absolute():
+            return path
+        return Path(os.environ.get('PROJECT_PATH', '')) / path
+
+    def _load_sound(self, sound_path):
+        if not self._init_mixer():
+            return None
+
+        absolute_path = self._resolve_path(sound_path)
+        if not absolute_path.exists():
+            print(T.tr('api.no_sound_path', 'The sound path {} does not exist.').format(absolute_path))
+            return None
+
+        key = absolute_path.as_posix()
+        if key not in self._sounds:
+            try:
+                self._sounds[key] = pygame.mixer.Sound(str(absolute_path))
+            except Exception as e:
+                print(T.tr('api.fail_to_load_sound', 'Failed to load sound {}: {}').format(absolute_path, e))
+                return None
+        return self._sounds[key]
+
+    # ---------- sound effects ----------
+
+    def load_sound(self, sound_path):
+        """Load (and cache) a sound effect. Returns a pygame Sound or None."""
+        return self._load_sound(sound_path)
+
+    def play_sound(self, sound_path, volume=1.0, loops=0, fade_ms=0):
+        """
+        Play a sound effect. Returns the pygame Channel, or None on failure.
+
+        :param sound_path: path relative to the project (e.g. './audio/jump.wav')
+        :param volume: playback volume in [0.0, 1.0]
+        :param loops: 0 = play once, -1 = loop forever, N = play N+1 times
+        :param fade_ms: fade-in duration in milliseconds
+        """
+        sound = self._load_sound(sound_path)
+        if sound is None:
+            return None
+
+        try:
+            channel = sound.play(loops=loops, fade_ms=fade_ms)
+            if channel:
+                channel.set_volume(max(0.0, min(1.0, float(volume))))
+                if loops != 0:
+                    self._looping_channels[self._resolve_path(sound_path).as_posix()] = channel
+            return channel
+        except Exception as e:
+            print(T.tr('api.fail_to_play_sound', 'Failed to play sound {}: {}').format(self._resolve_path(sound_path), e))
+            return None
+
+    def stop_sound(self, sound_path):
+        """Stop a looping sound effect started with play_sound(loops=...)."""
+        key = self._resolve_path(sound_path).as_posix()
+        channel = self._looping_channels.pop(key, None)
+        if channel:
+            channel.stop()
+
+    def stop_all_sounds(self):
+        """Stop every currently playing sound effect."""
+        if self._is_available:
+            pygame.mixer.stop()
+        self._looping_channels.clear()
+
+    # ---------- background music ----------
+
+    def play_music(self, music_path, loops=-1, fade_ms=0):
+        """
+        Play a background music track (one stream at a time).
+
+        :param music_path: path relative to the project (e.g. './audio/bgm.ogg')
+        :param loops: -1 = loop forever (default), 0 = play once
+        :param fade_ms: fade-in duration in milliseconds
+        """
+        if not self._init_mixer():
+            return False
+
+        absolute_path = self._resolve_path(music_path)
+        if not absolute_path.exists():
+            print(T.tr('api.no_sound_path', 'The sound path {} does not exist.').format(absolute_path))
+            return False
+
+        try:
+            pygame.mixer.music.load(str(absolute_path))
+            pygame.mixer.music.set_volume(self._music_volume)
+            pygame.mixer.music.play(loops=loops, fade_ms=fade_ms)
+            return True
+        except Exception as e:
+            print(T.tr('api.fail_to_play_music', 'Failed to play music {}: {}').format(absolute_path, e))
+            return False
+
+    def stop_music(self, fade_ms=0):
+        """Stop the background music (with an optional fade-out in ms)."""
+        if not self._is_available:
+            return
+        if fade_ms > 0:
+            pygame.mixer.music.fadeout(fade_ms)
+        else:
+            pygame.mixer.music.stop()
+
+    def pause_music(self):
+        if self._is_available:
+            pygame.mixer.music.pause()
+
+    def resume_music(self):
+        if self._is_available:
+            pygame.mixer.music.unpause()
+
+    def is_music_playing(self) -> bool:
+        if not self._is_available:
+            return False
+        return pygame.mixer.music.get_busy()
+
+    def set_music_volume(self, volume):
+        """Set background music volume in [0.0, 1.0]."""
+        self._music_volume = max(0.0, min(1.0, float(volume)))
+        if self._is_available:
+            pygame.mixer.music.set_volume(self._music_volume)
+
+    def get_music_volume(self) -> float:
+        return self._music_volume
+
+
+# Module-level singleton, mirroring scene_loader.
+audio_manager = AudioManager()
+
+
+def load_sound(sound_path):
+    return audio_manager.load_sound(sound_path)
+
+
+def play_sound(sound_path, volume=1.0, loops=0, fade_ms=0):
+    return audio_manager.play_sound(sound_path, volume, loops, fade_ms)
+
+
+def stop_sound(sound_path):
+    return audio_manager.stop_sound(sound_path)
+
+
+def stop_all_sounds():
+    return audio_manager.stop_all_sounds()
+
+
+def play_music(music_path, loops=-1, fade_ms=0):
+    return audio_manager.play_music(music_path, loops, fade_ms)
+
+
+def stop_music(fade_ms=0):
+    return audio_manager.stop_music(fade_ms)
+
+
+def pause_music():
+    return audio_manager.pause_music()
+
+
+def resume_music():
+    return audio_manager.resume_music()
+
+
+def is_music_playing() -> bool:
+    return audio_manager.is_music_playing()
+
+
+def set_music_volume(volume):
+    return audio_manager.set_music_volume(volume)
+
+
+def get_music_volume() -> float:
+    return audio_manager.get_music_volume()

{pygamestudio-1.0.0.dev5 → pygamestudio-1.0.0.dev7}/src/pygamestudio/api/core/game.py

@@ -3,10 +3,18 @@ import sys
 import pygame
 import inspect
 from pathlib import Path
+from pygamestudio.api.core.scene import scene_loader
 from pygamestudio.api.config.project import get_project_config
 
 
 class Game:
+    """Runtime game class used by every built/exported project.
+
+    Subclass it in the project's main.py and override the on_* hooks. run()
+    starts the main loop: it auto-detects the project root from the caller's
+    file, initializes pygame, dispatches every pygame event to the matching
+    on_* hook, then calls on_update(delta_time) and flips the display.
+    """
     _instance = None
 
     def __init__(self):
@@ -17,6 +25,11 @@ class Game:
         self._running = False
 
     def _init_game(self):
+        """Set up pygame and resolve the project root from the calling file.
+
+        The project path is derived from the stack frame of whoever created
+        the Game (the project's main.py), so no path config is required.
+        """
         caller_frame = inspect.stack()[-1]
         caller_file_path = caller_frame.filename
         self._project_path = Path(caller_file_path).parent.resolve().as_posix()
@@ -29,6 +42,7 @@ class Game:
         self._clock = pygame.time.Clock()
 
     def run(self):
+        """Start the game loop. Blocks until the window is closed."""
         Game._instance = self
         self._init_game()
         self._running = True
@@ -36,6 +50,7 @@ class Game:
         self.on_start()
 
         while self._running:
+            # --- 1. Dispatch all pending pygame events to the on_* hooks. ---
             for event in pygame.event.get():
                 # ---------- Quit Event ----------
                 if event.type == pygame.QUIT:
@@ -55,7 +70,7 @@ class Game:
                 elif event.type == pygame.MOUSEBUTTONUP:
                     self.on_mouse_button_up(event.pos, event.button, getattr(event, 'touch', 0), getattr(event, "clicks", 1), getattr(event, 'window', None))
                 elif event.type == pygame.MOUSEWHEEL:
-                    self.on_mouse_wheel(event.which, event.flipped, event.x, event.y, getattr(event, 'touch', 0), event.precise_x, event.precise_y, getattr(event, 'window', None))
+                    self.on_mouse_wheel(event.flipped, event.x, event.y, getattr(event, 'touch', 0), event.precise_x, event.precise_y, getattr(event, 'window', None))
 
                 # ---------- Joystick Event ----------
                 elif event.type == pygame.JOYAXISMOTION:
@@ -181,9 +196,16 @@ class Game:
 
 
             delta_time = self._clock.tick(self._fps) / 1000
+            # Make the current frame's delta time available to the scene's
+            # scripts (their on_update(delta_time) hooks).
+            scene_loader._set_delta_time(delta_time)
+            # --- 2. Fixed/step logic: user update + draw, then present. ---
             self.on_update(delta_time)
             pygame.display.flip()
 
+        # Let every attached behavior script run its on_destroy() cleanup hook
+        # before the game exits (mirrors on_start fired on scene load).
+        scene_loader._destroy_scripts()
         self.on_quit()
         pygame.quit()
         sys.exit()
@@ -215,7 +237,7 @@ class Game:
     def on_mouse_button_up(self, pos, btn, touch=0, clicks=1, window=None):
         pass
 
-    def on_mouse_wheel(self, which, flipped, x, y, touch=0, precise_x=0.0, precise_y=0.0, window=None):
+    def on_mouse_wheel(self, flipped, x, y, touch=0, precise_x=0.0, precise_y=0.0, window=None):
         pass
 
     # ---------- Joystick Event Hooks ----------

{pygamestudio-1.0.0.dev5 → pygamestudio-1.0.0.dev7}/src/pygamestudio/api/core/scene.py

@@ -1,6 +1,9 @@
 import os
+import sys
 import re
 import json
+import inspect
+import importlib.util
 import pygame
 from pathlib import Path
 from pygamestudio.game.object.type import *
@@ -9,16 +12,29 @@ from pygamestudio.game.object.canvas import *
 from pygamestudio.game.object.text import *
 from pygamestudio.game.object.ellipse import *
 from pygamestudio.game.object.line import *
+from pygamestudio.game.object.polygon import *
 from pygamestudio.game.object.image import *
 from pygamestudio.game.object.button import *
+from pygamestudio.game.object.particle import *
+from pygamestudio.game.object.frame_sequence import *
 from pygamestudio.api.config.project import get_project_config
 from pygamestudio.common.i18n.translator import Translator as T
 
 
 class SceneLoader:
+    """Runtime mirror of the editor's scene tree.
+
+    Reads the .scene JSON produced by the editor and rebuilds the same object
+    tree with is_for_api=True objects, rendering them each frame and driving
+    the attached behavior scripts (on_start / on_update / on_destroy).
+    """
+
     def __init__(self):
         self._current_scene_path = ''
         self._all_object_tree_struct = {}
+        # Seconds elapsed since the last frame, updated by Game.run() each
+        # frame and passed to the scripts' on_update(delta_time) hooks.
+        self._delta_time = 0
 
     def load_scene(self, screen_surface:pygame.Surface, scene_path:str=''):
         if not scene_path and self._current_scene_path or scene_path and scene_path==self._current_scene_path:
@@ -35,6 +51,9 @@ class SceneLoader:
         if not Path(scene_path).exists():
             raise RuntimeError(T.tr('api.no_scene_path', 'The scene path {} does not exist.').format(scene_path))
 
+        if self._all_object_tree_struct:
+            # The current scene is about to be replaced; let its scripts clean up.
+            self._destroy_scripts()
         self._all_object_tree_struct = {}
         self._current_scene_path = scene_path
         with open(scene_path, 'r', encoding='utf-8') as f:
@@ -55,6 +74,8 @@ class SceneLoader:
                 _l(key, child_object_tree_struct)
 
         _l('', scene_data)
+        # The whole object tree now exists; fire the scripts' on_start hooks.
+        self._start_scripts()
         self._update_scene(screen_surface)
 
     def _add(self, parent_uuid, object_type, object_data={}):
@@ -78,13 +99,73 @@ class SceneLoader:
             obj = ObjectText(self, object_data, is_for_api=True)
         elif object_type == OBJECT_ELLIPSE:
             obj = ObjectEllipse(self, object_data, is_for_api=True)
+        elif object_type == OBJECT_POLYGON:
+            obj = ObjectPolygon(self, object_data, is_for_api=True)
         elif object_type == OBJECT_LINE:
             obj = ObjectLine(self, object_data, is_for_api=True)
         elif object_type == OBJECT_IMAGE:
             obj = ObjectImage(self, object_data, is_for_api=True)
         elif object_type == OBJECT_BUTTON:
             obj = ObjectButton(self, object_data, is_for_api=True)
+        elif object_type == OBJECT_PARTICLE:
+            obj = ObjectParticle(self, object_data, is_for_api=True)
+        elif object_type == OBJECT_FRAME_SEQUENCE:
+            obj = ObjectFrameSequence(self, object_data, is_for_api=True)
+        else:
+            raise RuntimeError(T.tr('api.unknown_object_type', 'Unknown object type: {}').format(object_type))
+
+        # Attach the behavior script (if any) so the script's lifecycle hooks
+        # can be driven later (see ObjectBase._start/_update_surface/_destroy).
+        obj.script_instance = self._load_script(obj)
         return obj
+
+    def _load_script(self, obj):
+        """
+        Dynamically load and instantiate the object's behavior script.
+
+        The script module (obj.script_path, relative to the project) is loaded
+        with importlib, the first user-defined class is instantiated with
+        owner=obj, and the instance is stored on obj.script_instance. Returns
+        None when no script is attached or it fails to load (the failure is
+        reported to stderr but does not stop the game).
+        """
+        if not obj.script_path:
+            return None
+
+        script_absolute_path = Path(os.environ.get('PROJECT_PATH', '')) / obj.script_path
+        if not script_absolute_path.exists():
+            print(T.tr('api.no_script_path', 'The script path {} does not exist.').format(script_absolute_path), file=sys.stderr)
+            return None
+
+        try:
+            # A unique module name per object keeps every scene (re)load fresh,
+            # so the latest script content is always picked up.
+            module_name = f'pygamestudio_runtime_script_{obj.uuid}'
+            spec = importlib.util.spec_from_file_location(module_name, script_absolute_path)
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+        except Exception:
+            print(T.tr('api.fail_to_load_script', 'Failed to load script {}: {}').format(script_absolute_path, e), file=sys.stderr)
+            return None
+
+        script_class = self._get_script_class(module)
+        if script_class is None:
+            print(T.tr('api.no_script_class', 'No script class found in {}.').format(script_absolute_path), file=sys.stderr)
+            return None
+
+        try:
+            return script_class(obj)
+        except Exception as e:
+            print(T.tr('api.fail_to_init_script', 'Failed to initialize script {}: {}').format(script_absolute_path, e), file=sys.stderr)
+            return None
+
+    @staticmethod
+    def _get_script_class(module):
+        """Return the first class defined in the given script module (ignores imports)."""
+        for name, value in module.__dict__.items():
+            if inspect.isclass(value) and value.__module__ == module.__name__:
+                return value
+        return None
     
     def _add_object_tree_struct(self, parent_uuid, object_tree_struct_to_add): 
         if not self._all_object_tree_struct:
@@ -114,16 +195,61 @@ class SceneLoader:
         def _update(object_tree_struct, parent_surface):
             value = list(object_tree_struct.values())[0]
             obj = value['object']
-            obj.update_surface()
+            obj._update_surface()
+            self._update_script(obj)
             
-            if obj.is_visible:
+            if obj.visible:
                 for child_object_tree_struct in value['children']:
-                    _update(child_object_tree_struct, obj.get_surface())
+                    _update(child_object_tree_struct, obj._get_surface())
 
-                obj.draw(parent_surface)
+                obj._draw(parent_surface)
 
         _update(self._all_object_tree_struct, screen_surface)
 
+    def _set_delta_time(self, delta_time):
+        """Set the per-frame delta time (seconds) passed to scripts' on_update."""
+        self._delta_time = delta_time
+
+    def _start_scripts(self):
+        """Fire on_start() on every attached script (after the scene is loaded)."""
+        for obj in self._iter_objects():
+            if not obj.script_instance:
+                continue
+            try:
+                obj.script_instance.on_start()
+            except Exception as e:
+                print(T.tr('api.script_start_error', 'Script on_start error for {}: {}').format(obj.name, e), file=sys.stderr)
+
+    def _update_script(self, obj):
+        """Fire on_update(delta_time) on an object's attached script (per frame)."""
+        if not obj.script_instance:
+            return
+        try:
+            obj.script_instance.on_update(self._delta_time)
+        except Exception as e:
+            print(T.tr('api.script_update_error', 'Script on_update error for {}: {}').format(obj.name, e), file=sys.stderr)
+
+    def _destroy_scripts(self):
+        """Fire on_destroy() on every attached script (before the scene is replaced)."""
+        for obj in self._iter_objects():
+            if not obj.script_instance:
+                continue
+            try:
+                obj.script_instance.on_destroy()
+            except Exception as e:
+                print(T.tr('api.script_destroy_error', 'Script on_destroy error for {}: {}').format(obj.name, e), file=sys.stderr)
+
+    def _iter_objects(self):
+        """Yield every object in the current scene tree (depth-first)."""
+        def _gen(object_tree_struct):
+            value = list(object_tree_struct.values())[0]
+            yield value['object']
+            for child_object_tree_struct in value['children']:
+                yield from _gen(child_object_tree_struct)
+
+        if self._all_object_tree_struct:
+            yield from _gen(self._all_object_tree_struct)
+
     def _get_object_tree_struct_by_path(self, object_path):
         def _get(name, target_item_index, current_item_index, recursion_time, part_number, object_tree_struct):
             key = list(object_tree_struct.keys())[0]