pycoode 1.0.0__py3-none-any.whl

pycoode/__init__.py

@@ -0,0 +1,37 @@
+"""pycoode —— 让做游戏像写一行代码一样简单
+
+基于 pygame 封装: 自动处理窗口创建、中文字体、高 DPI、
+分辨率适配、游戏循环、输入、精灵、音效和场景。
+"""
+
+from .core import Game, run, keycode
+from .sprites import Sprite, load_image
+from .scene import Scene
+from .audio import (
+    play, music, stop_music, pause_music, resume_music,
+    set_music_volume, is_music_playing,
+)
+from .utils import (
+    Vector, to_color, clamp, lerp, dist, angle,
+    rand, randint, choice, chance,
+)
+from .demo import demo
+
+__version__ = "1.0.0"
+
+
+def sprite(path, x=0, y=0, **kw):
+    """加载精灵: pc.sprite("hero.png", 400, 300)"""
+    return Sprite.load(path, x, y, **kw)
+
+
+__all__ = [
+    "Game", "run", "demo", "keycode",
+    "Sprite", "sprite", "load_image",
+    "Scene",
+    "play", "music", "stop_music", "pause_music", "resume_music",
+    "set_music_volume", "is_music_playing",
+    "Vector", "to_color", "clamp", "lerp", "dist", "angle",
+    "rand", "randint", "choice", "chance",
+    "__version__",
+]

pycoode/audio.py

@@ -0,0 +1,69 @@
+"""pycoode.audio —— 音效与背景音乐，一行播放
+
+没有音频设备时所有函数静默降级，不会让游戏崩掉。
+"""
+
+import pygame
+
+_sound_cache = {}
+_mixer_ok = True
+
+
+def _ensure_mixer():
+    global _mixer_ok
+    if not _mixer_ok:
+        return False
+    try:
+        if not pygame.mixer.get_init():
+            pygame.mixer.init()
+        return True
+    except Exception:
+        _mixer_ok = False
+        return False
+
+
+def play(path, volume=1.0):
+    """播放音效（可重复调用，自动缓存）"""
+    if not _ensure_mixer():
+        return None
+    key = str(path)
+    if key not in _sound_cache:
+        _sound_cache[key] = pygame.mixer.Sound(key)
+    s = _sound_cache[key]
+    s.set_volume(max(0.0, min(1.0, volume)))
+    s.play()
+    return s
+
+
+def music(path, loop=True, volume=0.6, fade_ms=0):
+    """播放背景音乐（默认循环）"""
+    if not _ensure_mixer():
+        return
+    pygame.mixer.music.load(str(path))
+    pygame.mixer.music.set_volume(max(0.0, min(1.0, volume)))
+    pygame.mixer.music.play(-1 if loop else 0, fade_ms=fade_ms)
+
+
+def stop_music(fade_ms=0):
+    if not _ensure_mixer():
+        return
+    pygame.mixer.music.fadeout(fade_ms) if fade_ms else pygame.mixer.music.stop()
+
+
+def pause_music():
+    if _ensure_mixer():
+        pygame.mixer.music.pause()
+
+
+def resume_music():
+    if _ensure_mixer():
+        pygame.mixer.music.unpause()
+
+
+def set_music_volume(v):
+    if _ensure_mixer():
+        pygame.mixer.music.set_volume(max(0.0, min(1.0, v)))
+
+
+def is_music_playing():
+    return _ensure_mixer() and pygame.mixer.music.get_busy()

pycoode/core.py

@@ -0,0 +1,455 @@
+"""pycoode.core —— Game 类与一行入口 run()
+
+解决"适配问题"的三个设计:
+1. 虚拟画布 + 信箱缩放: 游戏永远按设计分辨率(如 800x600)写坐标,
+   窗口任意拉伸都不变形、不错位;
+2. Windows 高 DPI 适配, 笔记本缩放 150% 也不会模糊偏移;
+3. 中文自动匹配字体, text("你好") 不开字体文件也能显示。
+"""
+
+import os
+import sys
+
+import pygame
+
+from .gfx import DrawingMixin
+from .utils import to_color
+
+# Windows 高 DPI: 必须在 pygame.init() 之前设置
+if sys.platform.startswith("win"):
+    os.environ.setdefault("SDL_WINDOWS_DPI_AWARENESS", "per monitor")
+
+# 常用按键名 -> pygame 键值, 让 g.key_held("space") 这种写法可用
+KEY_NAMES = {
+    "space": pygame.K_SPACE, "enter": pygame.K_RETURN, "return": pygame.K_RETURN,
+    "esc": pygame.K_ESCAPE, "escape": pygame.K_ESCAPE, "tab": pygame.K_TAB,
+    "up": pygame.K_UP, "down": pygame.K_DOWN, "left": pygame.K_LEFT, "right": pygame.K_RIGHT,
+    "shift": pygame.K_LSHIFT, "ctrl": pygame.K_LCTRL, "control": pygame.K_LCTRL,
+    "alt": pygame.K_LALT, "backspace": pygame.K_BACKSPACE, "delete": pygame.K_DELETE,
+    "home": pygame.K_HOME, "end": pygame.K_END, "pageup": pygame.K_PAGEUP, "pagedown": pygame.K_PAGEDOWN,
+    "insert": pygame.K_INSERT, "capslock": pygame.K_CAPSLOCK,
+    **{chr(c): c for c in range(ord("a"), ord("z") + 1)},
+    **{d: getattr(pygame, f"K_{d}") for d in "0123456789"},
+    **{f"f{i}": getattr(pygame, f"K_F{i}") for i in range(1, 13)},
+}
+
+
+def keycode(key):
+    """把 'space'/'a'/pygame.K_SPACE 统一成 pygame 键值; 无法识别返回 None"""
+    if isinstance(key, int):
+        return key
+    return KEY_NAMES.get(str(key).strip().lower())
+
+
+# 常用窗口尺寸预设: pc.run(size="hd")
+SIZE_PRESETS = {
+    "small": (640, 480),
+    "md": (800, 600),
+    "large": (1024, 768),
+    "square": (600, 600),
+    "hd": (1280, 720),
+    "fullhd": (1920, 1080),
+}
+
+
+def _parse_size(size, fallback):
+    """把 'hd' / (1280, 720) 统一成 (宽, 高)"""
+    if size is None:
+        return fallback
+    if isinstance(size, str):
+        key = size.strip().lower()
+        if key in SIZE_PRESETS:
+            return SIZE_PRESETS[key]
+        raise ValueError(
+            f"未知尺寸预设 {size!r}, 可用: {', '.join(sorted(SIZE_PRESETS))}")
+    if isinstance(size, (tuple, list)) and len(size) == 2:
+        return (int(size[0]), int(size[1]))
+    raise TypeError("size 需要是 (宽, 高) 元组或预设名字, 如 size='hd'")
+
+
+def _desktop_size():
+    """当前桌面分辨率; 取不到返回 None（如 dummy 驱动 / 无头环境）"""
+    try:
+        modes = pygame.display.list_modes()
+        if modes and modes != -1 and modes[0][0] > 0:
+            return modes[0]
+    except Exception:
+        pass
+    return None
+
+
+class Game(DrawingMixin):
+    """pycoode 游戏主类。
+
+    最简用法:
+        import pycoode as pc
+        pc.run()                                  # 直接弹出窗口
+        pc.run(draw=lambda g: g.text("Hi", 10, 10))
+
+    完整用法:
+        g = pc.Game(800, 600, title="我的游戏", fps=60)
+        g.on_update = lambda g, dt: ...
+        g.on_draw = lambda g: ...
+        g.run()
+    """
+
+    def __init__(self, width=800, height=600, title="pycoode", fps=60,
+                 background="dark", resizable=True, fullscreen=False,
+                 show_fps=False, icon=None, quit_key="escape",
+                 size=None, fit_screen=False, mouse_visible=True):
+        pygame.init()
+        try:
+            pygame.font.init()
+        except Exception:
+            pass
+        try:
+            pygame.mixer.init()
+        except Exception:
+            pass
+
+        # 窗口大小: size 预设/元组优先, 其次 fit_screen 自动收缩到屏幕内
+        if size is not None:
+            width, height = _parse_size(size, (width, height))
+        if fit_screen:
+            desktop = _desktop_size()
+            if desktop:
+                width = min(width, max(320, int(desktop[0] * 0.9)))
+                height = min(height, max(240, int(desktop[1] * 0.9)))
+
+        self.resizable = bool(resizable)
+        self._fullscreen = bool(fullscreen)
+        flags = 0
+        if self.resizable:
+            flags |= pygame.RESIZABLE
+        if self._fullscreen:
+            flags |= pygame.FULLSCREEN
+        self.screen = pygame.display.set_mode((int(width), int(height)), flags)
+        pygame.display.set_caption(str(title))
+        if icon:
+            try:
+                pygame.display.set_icon(pygame.image.load(str(icon)))
+            except Exception:
+                pass
+
+        # 设计分辨率(虚拟画布) vs 真实窗口, 两者解耦是"零适配"的关键
+        self.width = int(width)
+        self.height = int(height)
+        self.canvas = pygame.Surface((self.width, self.height))
+
+        self.title = str(title)
+        self.fps = int(fps)
+        self.background = background
+        self.quit_key = keycode(quit_key) or pygame.K_ESCAPE
+        self.show_fps = show_fps
+
+        # 鼠标指针可见性（游戏里常隐藏）
+        self.mouse_visible = bool(mouse_visible)
+        try:
+            pygame.mouse.set_visible(self.mouse_visible)
+        except Exception:
+            pass
+
+        self.running = False
+        self.clock = pygame.time.Clock()
+        self.dt = 1.0 / self.fps
+        self.time = 0.0
+        self.frame = 0
+
+        # ---- 输入状态 ----
+        self.keys = set()               # 当前按住
+        self._pressed = set()           # 本帧刚按下
+        self._released = set()          # 本帧刚松开
+        self.mouse_x = 0.0
+        self.mouse_y = 0.0
+        self.mouse_buttons = set()
+        self._mouse_pressed = set()
+        self._mouse_released = set()
+        self.touches = []               # [(x, y, finger_id), ...] 触摸点
+
+        # ---- 回调 / 场景 ----
+        self.on_update = None
+        self.on_draw = None
+        self.on_key = None              # on_key(key)
+        self.on_click = None            # on_click(x, y, button)
+        self.scene = None
+        self._scene_stack = []
+        self._scene_ops = []            # 本帧待执行的场景切换, 帧初统一应用
+
+    # ========================================================================
+    # 主循环
+    # ========================================================================
+
+    def run(self):
+        """启动游戏主循环（阻塞，直到退出）"""
+        self.running = True
+        try:
+            while self.running:
+                dt = self.clock.tick(self.fps) / 1000.0
+                self._frame(min(dt, 0.1))   # 掉帧时 dt 上限 100ms, 防穿墙
+        finally:
+            self._shutdown()
+
+    def step(self, dt=None):
+        """手动推进一步（测试 / 自己写循环时用）"""
+        if dt is None:
+            dt = min(self.clock.tick(self.fps) / 1000.0, 0.1)
+        self._frame(dt)
+
+    def _frame(self, dt):
+        self.dt = dt
+        self.time += dt
+        self.frame += 1
+        self._apply_scene_ops()
+        self._poll_events()
+        self._update(dt)
+        self._draw()
+
+    def _shutdown(self):
+        try:
+            pygame.quit()
+        except Exception:
+            pass
+
+    def stop(self):
+        """退出游戏"""
+        self.running = False
+
+    def _update(self, dt):
+        if self.scene is not None:
+            self.scene.update(self, dt)
+        if self.on_update:
+            self.on_update(self, dt)
+
+    def _draw(self):
+        self.canvas.fill(to_color(self.background))
+        if self.scene is not None:
+            self.scene.draw(self)
+        if self.on_draw:
+            self.on_draw(self)
+        if self.show_fps:
+            self.text(f"FPS {self.clock.get_fps():.0f}", 8, 8, size=16,
+                      color=(120, 255, 120))
+        self._present()
+
+    # ========================================================================
+    # 缩放适配: 虚拟画布 -> 真实窗口 (信箱式, 保持比例)
+    # ========================================================================
+
+    def _view(self):
+        """返回 (scale, offset_x, offset_y)"""
+        sw, sh = self.screen.get_size()
+        if sw == 0 or sh == 0:
+            return 1.0, 0, 0
+        scale = min(sw / self.width, sh / self.height)
+        w, h = self.width * scale, self.height * scale
+        return scale, (sw - w) / 2.0, (sh - h) / 2.0
+
+    def _present(self):
+        scale, ox, oy = self._view()
+        w = max(1, int(self.width * scale))
+        h = max(1, int(self.height * scale))
+        self.screen.fill((0, 0, 0))
+        self.screen.blit(pygame.transform.smoothscale(self.canvas, (w, h)),
+                         (int(ox), int(oy)))
+        pygame.display.flip()
+
+    def _to_canvas(self, sx, sy):
+        """屏幕坐标 -> 游戏内坐标"""
+        scale, ox, oy = self._view()
+        return (sx - ox) / scale, (sy - oy) / scale
+
+    # ========================================================================
+    # 窗口控制: 改窗口大小 / 全屏 / 鼠标指针
+    # ========================================================================
+
+    @property
+    def screen_size(self):
+        """真实窗口的像素大小（区别于游戏设计分辨率 g.width/g.height）"""
+        return self.screen.get_size()
+
+    def _recreate_window(self, w, h, fullscreen):
+        flags = 0
+        if fullscreen:
+            flags |= pygame.FULLSCREEN
+        elif self.resizable:
+            flags |= pygame.RESIZABLE
+        self.screen = pygame.display.set_mode((int(w), int(h)), flags)
+        self._fullscreen = bool(fullscreen)
+
+    def set_window_size(self, w, h):
+        """运行时改变窗口大小；游戏设计分辨率不变，画面自动缩放适配"""
+        self._recreate_window(w, h, False)
+
+    def toggle_fullscreen(self):
+        """全屏 / 窗口模式切换（快捷键 F11）"""
+        self._recreate_window(self.width, self.height, not self._fullscreen)
+
+    def set_mouse_visible(self, visible):
+        """显示 / 隐藏鼠标指针（游戏里常用）"""
+        self.mouse_visible = bool(visible)
+        try:
+            pygame.mouse.set_visible(self.mouse_visible)
+        except Exception:
+            pass
+
+    # ========================================================================
+    # 输入查询
+    # ========================================================================
+
+    @property
+    def mouse_pos(self):
+        return (self.mouse_x, self.mouse_y)
+
+    def key_held(self, key):
+        """按键当前是否按住"""
+        k = keycode(key)
+        return k is not None and k in self.keys
+
+    def key_pressed(self, key):
+        """按键本帧是否刚按下（按下瞬间只触发一帧）"""
+        k = keycode(key)
+        return k is not None and k in self._pressed
+
+    def key_released(self, key):
+        """按键本帧是否刚松开"""
+        k = keycode(key)
+        return k is not None and k in self._released
+
+    def mouse_held(self, button=1):
+        return button in self.mouse_buttons
+
+    def mouse_pressed(self, button=1):
+        return button in self._mouse_pressed
+
+    def mouse_released(self, button=1):
+        return button in self._mouse_released
+
+    # ========================================================================
+    # 场景管理
+    # ========================================================================
+
+    def switch_scene(self, scene):
+        self._scene_ops.append(("switch", scene))
+
+    def push_scene(self, scene):
+        self._scene_ops.append(("push", scene))
+
+    def pop_scene(self):
+        self._scene_ops.append(("pop", None))
+
+    def _apply_scene_ops(self):
+        while self._scene_ops:
+            op, arg = self._scene_ops.pop(0)
+            if op == "switch":
+                self._exit_scene(self.scene)
+                self._enter_scene(arg)
+            elif op == "push":
+                if self.scene is not None:
+                    self._scene_stack.append(self.scene)
+                self._enter_scene(arg)
+            elif op == "pop":
+                self._exit_scene(self.scene)
+                self._enter_scene(self._scene_stack.pop() if self._scene_stack else None)
+
+    def _enter_scene(self, scene):
+        self.scene = scene
+        if scene is not None:
+            scene.game = self
+            scene.on_enter(self)
+
+    def _exit_scene(self, scene):
+        if scene is not None:
+            scene.on_exit(self)
+
+    # ========================================================================
+    # 事件
+    # ========================================================================
+
+    def _poll_events(self):
+        self._pressed.clear()
+        self._released.clear()
+        self._mouse_pressed.clear()
+        self._mouse_released.clear()
+
+        for e in pygame.event.get():
+            if e.type == pygame.QUIT:
+                self.stop()
+            elif e.type == pygame.KEYDOWN:
+                if e.key == self.quit_key:
+                    self.stop()
+                    continue
+                self.keys.add(e.key)
+                self._pressed.add(e.key)
+                if e.key == pygame.K_F11:
+                    self.toggle_fullscreen()
+                if self.scene is not None:
+                    self.scene.handle_key(self, e.key)
+                if self.on_key:
+                    self.on_key(e.key)
+            elif e.type == pygame.KEYUP:
+                self.keys.discard(e.key)
+                self._released.add(e.key)
+            elif e.type == pygame.MOUSEMOTION:
+                self.mouse_x, self.mouse_y = self._to_canvas(*e.pos)
+            elif e.type == pygame.MOUSEBUTTONDOWN:
+                x, y = self._to_canvas(*e.pos)
+                self.mouse_x, self.mouse_y = x, y
+                self.mouse_buttons.add(e.button)
+                self._mouse_pressed.add(e.button)
+                if self.scene is not None:
+                    self.scene.handle_click(self, x, y, e.button)
+                if self.on_click:
+                    self.on_click(x, y, e.button)
+            elif e.type == pygame.MOUSEBUTTONUP:
+                self.mouse_buttons.discard(e.button)
+                self._mouse_released.add(e.button)
+            elif e.type == pygame.FINGERDOWN:
+                self._touch_add(e)
+            elif e.type == pygame.FINGERMOTION:
+                self._touch_add(e)
+            elif e.type == pygame.FINGERUP:
+                self.touches = [t for t in self.touches if t[2] != e.finger_id]
+            elif e.type == pygame.VIDEORESIZE:
+                self._recreate_window(e.w, e.h, self._fullscreen)
+
+    def _touch_add(self, e):
+        sw, sh = self.screen.get_size()
+        x, y = self._to_canvas(e.x * sw, e.y * sh)
+        self.touches = [t for t in self.touches if t[2] != e.finger_id]
+        self.touches.append((x, y, e.finger_id))
+
+
+def run(update=None, draw=None, on_key=None, on_click=None, scene=None,
+        width=800, height=600, title="pycoode", fps=60, background="dark",
+        fullscreen=False, resizable=True, show_fps=False, icon=None,
+        quit_key="escape", size=None, fit_screen=False, mouse_visible=True):
+    """一行启动游戏。
+
+        pc.run()                                                  # 空窗口
+        pc.run(draw=lambda g: g.text("Hi", 10, 10))               # 画点东西
+        pc.run(update=my_update, draw=my_draw, width=960, height=640)
+        pc.run(scene=Menu())                                      # 用场景管理
+        pc.run(size="hd")                                         # 预设窗口大小
+        pc.run(size=(1280, 720))                                  # 或直接给 (宽, 高)
+        pc.run(fit_screen=True)                                   # 自动适应你的屏幕
+        pc.run(mouse_visible=False)                               # 隐藏鼠标指针
+    """
+    g = Game(width=width, height=height, title=title, fps=fps,
+             background=background, fullscreen=fullscreen,
+             resizable=resizable, show_fps=show_fps, icon=icon,
+             quit_key=quit_key, size=size, fit_screen=fit_screen,
+             mouse_visible=mouse_visible)
+    if scene is not None:
+        g.scene = scene() if isinstance(scene, type) else scene
+        g.scene.game = g
+        g.scene.on_enter(g)
+    if update is not None:
+        g.on_update = update
+    if draw is not None:
+        g.on_draw = draw
+    if on_key is not None:
+        g.on_key = on_key
+    if on_click is not None:
+        g.on_click = on_click
+    g.run()
+    return g

pycoode/demo.py

@@ -0,0 +1,59 @@
+"""pycoode.demo —— 内置演示小游戏
+
+    import pycoode
+    pycoode.demo()
+
+方向键 / WASD 移动青色方块，吃掉金色金币，ESC 退出。
+"""
+
+from . import utils
+
+
+def demo(width=800, height=600):
+    import pycoode as pc
+
+    player = pc.Sprite.solid("cyan", 36, 36, width / 2, height / 2)
+    coins = []
+    score = 0
+
+    def spawn_coin():
+        coins.append(pc.Sprite.solid(
+            "gold", 18, 18,
+            utils.rand(40, width - 40), utils.rand(40, height - 40),
+        ))
+
+    for _ in range(5):
+        spawn_coin()
+
+    def update(g, dt):
+        nonlocal score
+        speed = 320
+        dx = int(g.key_held("right")) - int(g.key_held("left"))
+        dy = int(g.key_held("down")) - int(g.key_held("up"))
+        if g.key_held("d"):
+            dx += 1
+        if g.key_held("a"):
+            dx -= 1
+        if g.key_held("s"):
+            dy += 1
+        if g.key_held("w"):
+            dy -= 1
+        player.x = utils.clamp(player.x + dx * speed * dt, 18, width - 18)
+        player.y = utils.clamp(player.y + dy * speed * dt, 18, height - 18)
+        for c in list(coins):
+            if player.collides_with(c):
+                coins.remove(c)
+                score += 1
+                spawn_coin()
+
+    def draw(g):
+        g.clear("dark")
+        for c in coins:
+            c.draw(g)
+        player.draw(g)
+        g.text(f"得分 {score}", 16, 14, size=26, color="white")
+        g.text("方向键 / WASD 移动 · ESC 退出", 16, height - 34,
+               size=16, color=(150, 150, 160))
+
+    pc.run(update=update, draw=draw, width=width, height=height,
+           title="pycoode demo")