gamekit2d 0.3.2__tar.gz → 0.3.3__tar.gz

{gamekit2d-0.3.2/gamekit2d.egg-info → gamekit2d-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gamekit2d
-Version: 0.3.2
+Version: 0.3.3
 Summary: A tiny zero-dependency 2D game library (standard library only, self-made GDI renderer + tkinter + winsound). A simpler pygame.
 Author: gamekit contributors
 License-Expression: MIT
@@ -82,7 +82,7 @@ def wave(dt):
 
 `Group` 是一组精灵的轻量容器：整组移动 / 隐藏 / 删除，不用自己写循环。精灵仍由 Game 统一渲染，Group 只做批量管理。
 
-`Game(..., dirty=True)` 开启**脏矩形局部更新**：不整屏清屏，只把上一帧真正移动过的精灵旧位置刷回背景色。实测：在"少量动态对象 + 静态背景"场景（菜单、UI、几个移动元素）与整屏清屏基本持平；**大量精灵同时移动时建议保持 `dirty=False`**（局部恢复比整屏 `memmove` 清屏更贵）。仅 GDI 后端有效。
+`Game(..., dirty=True)` 开启**脏矩形局部更新**：不整屏清屏，只把上一帧真正移动过的精灵旧位置刷回背景色。配合 `game.sprite(..., static=True)` 标记静态元素（墙壁、砖块、UI 装饰）——它们只在第一帧画进后台缓冲，之后只要没被移动精灵压过就不再重画。实测"400 静态 + 8 动态"场景比每帧全画快 **1.46 倍**。大量精灵同时移动时仍用默认 `dirty=False`。仅 GDI 后端有效。
 
 ---
 

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/README.md

@@ -58,7 +58,7 @@ def wave(dt):
 
 `Group` 是一组精灵的轻量容器：整组移动 / 隐藏 / 删除，不用自己写循环。精灵仍由 Game 统一渲染，Group 只做批量管理。
 
-`Game(..., dirty=True)` 开启**脏矩形局部更新**：不整屏清屏，只把上一帧真正移动过的精灵旧位置刷回背景色。实测：在"少量动态对象 + 静态背景"场景（菜单、UI、几个移动元素）与整屏清屏基本持平；**大量精灵同时移动时建议保持 `dirty=False`**（局部恢复比整屏 `memmove` 清屏更贵）。仅 GDI 后端有效。
+`Game(..., dirty=True)` 开启**脏矩形局部更新**：不整屏清屏，只把上一帧真正移动过的精灵旧位置刷回背景色。配合 `game.sprite(..., static=True)` 标记静态元素（墙壁、砖块、UI 装饰）——它们只在第一帧画进后台缓冲，之后只要没被移动精灵压过就不再重画。实测"400 静态 + 8 动态"场景比每帧全画快 **1.46 倍**。大量精灵同时移动时仍用默认 `dirty=False`。仅 GDI 后端有效。
 
 ---
 

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/gamekit/__init__.py

@@ -46,7 +46,7 @@ from .utils.color import (Color, to_color, mix, random_color,
                           LIGHT_GRAY, DARK_GRAY, NAVY)
 from .utils.vector import Vec2
 
-__version__ = "0.3.2"
+__version__ = "0.3.3"
 __all__ = [
     "Game", "Scene", "Key", "normalize",
     "Sprite", "Group", "Animation",

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/gamekit/core/game.py

@@ -63,6 +63,7 @@ class Game:
         self._dirty = bool(dirty) and (self.backend == "GdiRenderer")
         self._last_bboxes = {}
         self._moved = {}
+        self._dirty_first = True   # 第一帧必须全画（静态精灵首次入缓冲）
 
         # ---- 全局物理 ----
         self.gravity = 0.0        # 像素/秒^2，作用于 gravity_scale>0 的精灵
@@ -188,15 +189,27 @@ class Game:
         r = self._renderer
 
         if self._dirty:
-            # 脏矩形模式：不清整屏，只擦上一帧真正移动过的精灵旧位置
-            r.begin_frame(clear=False)
-            if self._moved:
-                r.recover_background(list(self._moved.values()))
-            self._moved = {}
+            self._render_dirty(r)
         else:
             r.begin_frame(clear=True)
+            self._draw_all(r)
 
-        # 精灵与图形按 layer 混排绘制（layer 越大越靠上层）
+        for t in list(self._texts):
+            if not t._removed:
+                t._draw(r)
+
+        for u in list(self._ui_elements):
+            if not u._removed:
+                u._draw(r)
+
+        for ps in list(self._particles):
+            if not ps._removed:
+                ps._draw(r)
+
+        r.end_frame()
+
+    def _collect_drawables(self):
+        """收集当前帧需要绘制的精灵/图形，按 layer 排序。"""
         drawables = []
         for s in self._sprites:
             if not s._removed and s.visible:
@@ -204,36 +217,84 @@ class Game:
         for sh in self._shapes:
             if not sh._removed and sh.visible:
                 drawables.append((sh.layer, sh))
+        drawables.sort(key=lambda x: x[0])
+        return drawables
+
+    def _draw_all(self, r):
+        """整屏清屏模式：画全部精灵/图形。"""
+        for _, obj in self._collect_drawables():
+            obj._draw(r)
+
+    @staticmethod
+    def _bbox_intersects(l, t, r, b, rect):
+        rl, rt, rr, rb = rect
+        return not (r < rl or l > rr or b < rt or t > rb)
+
+    def _render_dirty(self, r):
+        """脏矩形模式：不清整屏，静态精灵只画一次，动态精灵旧位置用背景恢复。"""
+        r.begin_frame(clear=False)
+        dirty = list(self._moved.values())   # 上一帧动态精灵的旧位置
+        if dirty:
+            r.recover_background(dirty)
+
+        statics = []
+        dynamics = []
         seen = set()
-        for _, obj in sorted(drawables, key=lambda x: x[0]):
+        for s in self._sprites:
+            if s._removed or not s.visible:
+                continue
+            if getattr(s, "static", False):
+                statics.append((s.layer, s))
+            else:
+                dynamics.append((s.layer, s))
+
+        if self._dirty_first:
+            # 第一帧：所有精灵都要画进后台缓冲（包括静态的）
+            to_draw = [(sh.layer, sh) for sh in self._shapes if not sh._removed and sh.visible]
+            to_draw.extend(statics)
+            to_draw.extend(dynamics)
+            to_draw.sort(key=lambda x: x[0])
+            for _, obj in to_draw:
+                obj._draw(r)
+                if hasattr(obj, "left"):
+                    seen.add(id(obj))
+            self._dirty_first = False
+            # 记录所有动态精灵 bbox（静态精灵不进 _last_bboxes，
+            # 它们位置不变，以后靠"与脏区相交才重画"管理）
+            for _, s in dynamics:
+                self._last_bboxes[id(s)] = (int(s.left), int(s.top),
+                                            int(s.right), int(s.bottom))
+            return
+
+        # 后续帧：静态精灵只有 bbox 与脏区相交时才重画（被动态精灵压过）
+        redraw_statics = []
+        for layer, s in statics:
+            sl = int(s.left); st = int(s.top); sr = int(s.right); sb = int(s.bottom)
+            if any(self._bbox_intersects(sl, st, sr, sb, d) for d in dirty):
+                redraw_statics.append((layer, s))
+
+        to_draw = redraw_statics + dynamics
+        # shapes 每帧重画（简单起见，不做静态优化）
+        for sh in self._shapes:
+            if not sh._removed and sh.visible:
+                to_draw.append((sh.layer, sh))
+        to_draw.sort(key=lambda x: x[0])
+
+        self._moved = {}
+        for _, obj in to_draw:
             obj._draw(r)
-            if self._dirty and hasattr(obj, "left"):
+            if hasattr(obj, "left") and not getattr(obj, "static", False):
                 bid = id(obj)
                 seen.add(bid)
                 nb = (int(obj.left), int(obj.top),
                       int(obj.right), int(obj.bottom))
                 old = self._last_bboxes.get(bid)
                 if old is not None and old != nb:
-                    self._moved[bid] = old   # 下一帧开头擦旧位置
+                    self._moved[bid] = old
                 self._last_bboxes[bid] = nb
-        # 清理已删除精灵的 bbox 记录（避免字典无限增长）
-        if self._dirty:
-            for bid in [b for b in self._last_bboxes if b not in seen]:
-                self._last_bboxes.pop(bid, None)
-
-        for t in list(self._texts):
-            if not t._removed:
-                t._draw(r)
-
-        for u in list(self._ui_elements):
-            if not u._removed:
-                u._draw(r)
-
-        for ps in list(self._particles):
-            if not ps._removed:
-                ps._draw(r)
-
-        r.end_frame()
+        # 清理已删除动态精灵的 bbox 记录
+        for bid in [b for b in self._last_bboxes if b not in seen]:
+            self._last_bboxes.pop(bid, None)
 
     # ==================================================================
     # 定时器
@@ -269,15 +330,19 @@ class Game:
     # 对象工厂
     # ==================================================================
     def sprite(self, image=None, x=0, y=0, width=None, height=None,
-               color=None, shape="rect", tag=None, layer=0):
+               color=None, shape="rect", tag=None, layer=0, static=False):
         """创建并返回一个精灵。
 
         ``game.sprite("player.png", x=100, y=100)``
         ``game.sprite(color="red", x=200, y=200, width=40, height=40, shape="circle")``
+
+        ``static=True`` 标记静态精灵：dirty 模式下只在第一帧绘制，
+        之后不再重画（被移动精灵压过时会自动重画那一块）。
         """
         from ..sprites.sprite import Sprite
         s = Sprite(self, image=image, x=x, y=y, width=width, height=height,
-                   color=color, shape=shape, tag=tag, layer=layer)
+                   color=color, shape=shape, tag=tag, layer=layer,
+                   static=static)
         if s not in self._sprites:
             self._sprites.append(s)
         return s

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/gamekit/render/backend.py

@@ -327,6 +327,9 @@ def _vk_to_keysym(vk):
 # 矩形 Surface 缓存上限：超过后回退直接 GDI 绘制，防 GDI 对象耗尽
 _RECT_CACHE_MAX = 256
 
+# 进程级共享的隐藏 tk root：PhotoImage 解码需要 Tk 默认 root
+_shared_decode_root = None
+
 
 class GdiRenderer(Renderer):
     """基于自研 GDI 内核的后端（立即模式）。
@@ -348,15 +351,18 @@ class GdiRenderer(Renderer):
         self._fonts = {}          # (family, size, bold, italic) -> HFONT
         self._image_cache = {}    # id(photo) -> Surface（图像精灵像素缓存）
         self._rect_cache = {}     # (w,h,color[,outline]) -> Surface（矩形精灵缓存）
-        self._decode_root = None  # 隐藏 tk root，仅用于 PhotoImage 解码
-        # 立即创建隐藏 root：Sprite 的 load_image 在 Game.__init__ 之后、
-        # run 之前执行，需要默认 root 才能解码 PhotoImage。
-        try:
-            import tkinter as tk
-            self._decode_root = tk.Tk()
-            self._decode_root.withdraw()
-        except Exception:
-            self._decode_root = None
+        # 隐藏 tk root 是进程级共享单例：PhotoImage 解码需要 Tk 默认 root，
+        # 但 Tcl 一次只能有一个解释器。多个 Game 复用同一个 root，
+        # 不在每个后端关闭时 destroy（进程退出时一起回收）。
+        global _shared_decode_root
+        if _shared_decode_root is None:
+            try:
+                import tkinter as tk
+                _shared_decode_root = tk.Tk()
+                _shared_decode_root.withdraw()
+            except Exception:
+                _shared_decode_root = None
+        self._decode_root = _shared_decode_root
 
         # 输入状态
         self._keys_held = set()
@@ -401,12 +407,8 @@ class GdiRenderer(Renderer):
                 pass
         self._rect_cache.clear()
         self._window.close()
-        if self._decode_root is not None:
-            try:
-                self._decode_root.destroy()
-            except Exception:
-                pass
-            self._decode_root = None
+        # decode_root 是进程级共享单例，不在此处 destroy
+        self._decode_root = None
 
     # ---- 每帧 ----
     def pump(self):

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/gamekit/render/window.py

@@ -19,6 +19,32 @@ _CLASS_NAME = "GameKitRenderWindow"
 
 # 所有活着的 Window：hwnd -> Window，供 wndproc 回调（滚轮等）反查实例
 _WINDOWS = {}
+# 窗口类只注册一次（重复 RegisterClassW 会让类句柄和 WNDPROC 闭包累积）
+_class_registered = False
+
+
+@win32.WNDPROC
+def _wndproc(hwnd, msg, wparam, lparam):
+    """模块级窗口过程：不闭包，所有 GameKit 窗口共享。"""
+    if msg == WM_MOUSEWHEEL:
+        win = _WINDOWS.get(hwnd)
+        if win is not None:
+            delta = (wparam >> 16) & 0xFFFF
+            if delta >= 0x8000:
+                delta -= 0x10000
+            win._wheel_delta += delta
+        return 0
+    if msg == WM_CLOSE:
+        win32.user32.DestroyWindow(hwnd)
+        return 0
+    if msg == WM_DESTROY:
+        # 注意：这里不要 PostQuitMessage(0)。
+        # PostQuitMessage 会往线程消息队列塞 WM_QUIT，
+        # 若同进程随后再用 tkinter（Tcl 事件循环），残留的
+        # WM_QUIT 会让其悄悄退出。关闭检测改由 poll_events 的
+        # IsWindow 完成。
+        return 0
+    return win32.user32.DefWindowProcW(hwnd, msg, wparam, lparam)
 
 
 class Window:
@@ -51,41 +77,21 @@ class Window:
     # ------------------------------------------------------------ 创建
 
     def _register_class(self):
-        @win32.WNDPROC
-        def wndproc(hwnd, msg, wparam, lparam):
-            if msg == WM_MOUSEWHEEL:
-                win = _WINDOWS.get(hwnd)
-                if win is not None:
-                    delta = (wparam >> 16) & 0xFFFF
-                    if delta >= 0x8000:
-                        delta -= 0x10000
-                    win._wheel_delta += delta
-                return 0
-            if msg == WM_CLOSE:
-                win32.user32.DestroyWindow(hwnd)
-                return 0
-            if msg == WM_DESTROY:
-                # 注意：这里不要 PostQuitMessage(0)。
-                # PostQuitMessage 会往线程消息队列塞 WM_QUIT，
-                # 若同进程随后再用 tkinter（Tcl 事件循环），残留的
-                # WM_QUIT 会让其悄悄退出。关闭检测改由 poll_events 的
-                # IsWindow 完成。
-                return 0
-            return win32.user32.DefWindowProcW(hwnd, msg, wparam, lparam)
-
-        self._wndproc = wndproc  # 保持引用
-        wc = WNDCLASSW()
-        wc.style = 0
-        wc.lpfnWndProc = wndproc
-        wc.cbClsExtra = 0
-        wc.cbWndExtra = 0
-        wc.hInstance = win32.hinstance()
-        wc.hIcon = None
-        wc.hCursor = None
-        wc.hbrBackground = win32.gdi32.GetStockObject(win32.COLOR_WINDOW)
-        wc.lpszMenuName = None
-        wc.lpszClassName = _CLASS_NAME
-        win32.user32.RegisterClassW(byref(wc))
+        global _class_registered
+        if not _class_registered:
+            wc = WNDCLASSW()
+            wc.style = 0
+            wc.lpfnWndProc = _wndproc
+            wc.cbClsExtra = 0
+            wc.cbWndExtra = 0
+            wc.hInstance = win32.hinstance()
+            wc.hIcon = None
+            wc.hCursor = None
+            wc.hbrBackground = win32.gdi32.GetStockObject(win32.COLOR_WINDOW)
+            wc.lpszMenuName = None
+            wc.lpszClassName = _CLASS_NAME
+            if win32.user32.RegisterClassW(byref(wc)):
+                _class_registered = True
 
     def _create_window(self, title):
         style = win32.WS_OVERLAPPEDWINDOW | win32.WS_VISIBLE

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/gamekit/sprites/sprite.py

@@ -23,7 +23,7 @@ class Sprite:
     """
 
     def __init__(self, game, image=None, x=0, y=0, width=None, height=None,
-                 color=None, shape="rect", tag=None, layer=0):
+                 color=None, shape="rect", tag=None, layer=0, static=False):
         self.game = game
 
         # ---- 位置与速度 ----
@@ -40,6 +40,9 @@ class Sprite:
         self.shape = shape if shape in ("rect", "circle") else "rect"
         self.layer = layer
         self.tag = tag
+        # static=True：标记为静态精灵。dirty 模式下它只在第一帧绘制，
+        # 之后只要没被动态精灵压过就不再重画（像素留在后台缓冲里）。
+        self.static = bool(static)
         self._image_path = None
         self._photo = None
         self._flip_h = False

{gamekit2d-0.3.2 → gamekit2d-0.3.3/gamekit2d.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gamekit2d
-Version: 0.3.2
+Version: 0.3.3
 Summary: A tiny zero-dependency 2D game library (standard library only, self-made GDI renderer + tkinter + winsound). A simpler pygame.
 Author: gamekit contributors
 License-Expression: MIT
@@ -82,7 +82,7 @@ def wave(dt):
 
 `Group` 是一组精灵的轻量容器：整组移动 / 隐藏 / 删除，不用自己写循环。精灵仍由 Game 统一渲染，Group 只做批量管理。
 
-`Game(..., dirty=True)` 开启**脏矩形局部更新**：不整屏清屏，只把上一帧真正移动过的精灵旧位置刷回背景色。实测：在"少量动态对象 + 静态背景"场景（菜单、UI、几个移动元素）与整屏清屏基本持平；**大量精灵同时移动时建议保持 `dirty=False`**（局部恢复比整屏 `memmove` 清屏更贵）。仅 GDI 后端有效。
+`Game(..., dirty=True)` 开启**脏矩形局部更新**：不整屏清屏，只把上一帧真正移动过的精灵旧位置刷回背景色。配合 `game.sprite(..., static=True)` 标记静态元素（墙壁、砖块、UI 装饰）——它们只在第一帧画进后台缓冲，之后只要没被移动精灵压过就不再重画。实测"400 静态 + 8 动态"场景比每帧全画快 **1.46 倍**。大量精灵同时移动时仍用默认 `dirty=False`。仅 GDI 后端有效。
 
 ---
 

{gamekit2d-0.3.2 → gamekit2d-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gamekit2d"
-version = "0.3.2"
+version = "0.3.3"
 description = "A tiny zero-dependency 2D game library (standard library only, self-made GDI renderer + tkinter + winsound). A simpler pygame."
 readme = "README.md"
 requires-python = ">=3.9"