Reworked collision handlers wip #280

Author: viblo

CHANGELOG.rst

@@ -4,6 +4,8 @@ Changelog
 Pymunk 7.0.0 (2025-04-10)
 -------------------------
 
+TODO: Add note of new collision handler logic!
+
 **Many improvements, with some breaking changes!**
 
 This is a big cleanup release with several breaking changes. If you upgrade from an older version, make sure to pay attention, especially the Space.bodies, Space.shapes and shape.constraints updates can break silently! 
@@ -47,6 +49,9 @@ Other improvements
 Extra thanks for aetle for a number of suggestions for improvements in this pymunk release
 
 
+
+
+
 Pymunk 6.11.1 (2025-02-09)
 --------------------------
 

Munk2D

@@ -8,7 +8,7 @@
 b = pymunk.Body(1,10)
 c = pymunk.Circle(b, 5)
 s.add(b, c)
-h = s.add_default_collision_handler()
+h = s.add_global_collision_handler()
 def f(arb, s, data):
     return False
 h.pre_solve = f

benchmarks/pymunk-collision-callback.py

@@ -1,6 +1,5 @@
 import logging
 import math
-import warnings
 
 from ._chipmunk_cffi import ffi, lib
 from .arbiter import Arbiter
@@ -202,51 +201,17 @@ def ext_cpMarchSampleFunc(point: ffi.CData, data: ffi.CData) -> float:
 @ffi.def_extern()
 def ext_cpCollisionBeginFunc(
     _arb: ffi.CData, _space: ffi.CData, data: ffi.CData
-) -> bool:
+) -> None:
     handler = ffi.from_handle(data)
-    x = handler._begin(Arbiter(_arb, handler._space), handler._space, handler.data)
-    if isinstance(x, bool):
-        return x
-
-    func_name = handler._begin.__code__.co_name
-    filename = handler._begin.__code__.co_filename
-    lineno = handler._begin.__code__.co_firstlineno
-
-    warnings.warn_explicit(
-        "Function '" + func_name + "' should return a bool to"
-        " indicate if the collision should be processed or not when"
-        " used as 'begin' or 'pre_solve' collision callback.",
-        UserWarning,
-        filename,
-        lineno,
-        handler._begin.__module__,
-    )
-    return True
+    handler._begin(Arbiter(_arb, handler._space), handler._space, handler.data)
 
 
 @ffi.def_extern()
 def ext_cpCollisionPreSolveFunc(
     _arb: ffi.CData, _space: ffi.CData, data: ffi.CData
-) -> bool:
+) -> None:
     handler = ffi.from_handle(data)
-    x = handler._pre_solve(Arbiter(_arb, handler._space), handler._space, handler.data)
-    if isinstance(x, bool):
-        return x
-
-    func_name = handler._pre_solve.__code__.co_name
-    filename = handler._pre_solve.__code__.co_filename
-    lineno = handler._pre_solve.__code__.co_firstlineno
-
-    warnings.warn_explicit(
-        "Function '" + func_name + "' should return a bool to"
-        " indicate if the collision should be processed or not when"
-        " used as 'begin' or 'pre_solve' collision callback.",
-        UserWarning,
-        filename,
-        lineno,
-        handler._pre_solve.__module__,
-    )
-    return True
+    handler._pre_solve(Arbiter(_arb, handler._space), handler._space, handler.data)
 
 
 @ffi.def_extern()

pymunk/_callbacks.py

@@ -39,6 +39,26 @@ def __init__(self, _arbiter: ffi.CData, space: "Space") -> None:
         self._arbiter = _arbiter
         self._space = space
 
+    @property
+    def process_collision(self) -> bool:
+        """Decides if the collision should be processed or rejected.
+
+        Set this during a begin() or pre_solve() callback to override
+        the default (True) value.
+
+        Set this to true to process the collision normally or
+        false to cause pymunk to ignore the collision entirely. If you set it to
+        false from a `begin` callback, the `pre_solve` and `post_solve` callbacks will never be run,
+        but you will still recieve a separate event when the shapes stop
+        overlapping.
+
+        """
+        return lib.cpArbiterGetProcessCollision(self._arbiter)
+
+    @process_collision.setter
+    def process_collision(self, v: bool) -> None:
+        lib.cpArbiterSetProcessCollision(self._arbiter, v)
+
     @property
     def contact_point_set(self) -> ContactPointSet:
         """Contact point sets make getting contact information from the

pymunk/arbiter.py

@@ -8,8 +8,7 @@
 from ._chipmunk_cffi import ffi, lib
 from .arbiter import Arbiter
 
-_CollisionCallbackBool = Callable[[Arbiter, "Space", Dict[Any, Any]], bool]
-_CollisionCallbackNoReturn = Callable[[Arbiter, "Space", Dict[Any, Any]], None]
+_CollisionCallback = Callable[[Arbiter, "Space", Dict[Any, Any]], None]
 
 
 class CollisionHandler(object):
@@ -42,10 +41,10 @@ def __init__(self, _handler: Any, space: "Space") -> None:
         self._handler.userData = self._userData
 
         self._space = space
-        self._begin: _CollisionCallbackBool = CollisionHandler.always_collide
-        self._pre_solve: _CollisionCallbackBool = CollisionHandler.always_collide
-        self._post_solve: _CollisionCallbackNoReturn = CollisionHandler.do_nothing
-        self._separate: _CollisionCallbackNoReturn = CollisionHandler.do_nothing
+        self._begin: _CollisionCallback = CollisionHandler.do_nothing
+        self._pre_solve: _CollisionCallback = CollisionHandler.do_nothing
+        self._post_solve: _CollisionCallback = CollisionHandler.do_nothing
+        self._separate: _CollisionCallback = CollisionHandler.do_nothing
 
         self._data: Dict[Any, Any] = {}
 
@@ -61,10 +60,10 @@ def data(self) -> Dict[Any, Any]:
         return self._data
 
     @property
-    def begin(self) -> _CollisionCallbackBool:
+    def begin(self) -> _CollisionCallback:
         """Two shapes just started touching for the first time this step.
 
-        ``func(arbiter, space, data) -> bool``
+        ``func(arbiter, space, data)``
 
         Return true from the callback to process the collision normally or
         false to cause pymunk to ignore the collision entirely. If you return
@@ -75,39 +74,38 @@ def begin(self) -> _CollisionCallbackBool:
         return self._begin
 
     @begin.setter
-    def begin(self, func: _CollisionCallbackBool) -> None:
+    def begin(self, func: _CollisionCallback) -> None:
         self._begin = func
 
-        if self._begin == CollisionHandler.always_collide:
-            self._handler.beginFunc = ffi.addressof(lib, "AlwaysCollide")
+        if self._begin == CollisionHandler.do_nothing:
+            self._handler.beginFunc = ffi.addressof(lib, "DoNothing")
         else:
             self._handler.beginFunc = lib.ext_cpCollisionBeginFunc
 
     @property
-    def pre_solve(self) -> _CollisionCallbackBool:
+    def pre_solve(self) -> _CollisionCallback:
         """Two shapes are touching during this step.
 
-        ``func(arbiter, space, data) -> bool``
+        ``func(arbiter, space, data)``
 
-        Return false from the callback to make pymunk ignore the collision
-        this step or true to process it normally. Additionally, you may
+        Additionally, you may
         override collision values using Arbiter.friction, Arbiter.elasticity
         or Arbiter.surfaceVelocity to provide custom friction, elasticity,
         or surface velocity values. See Arbiter for more info.
         """
         return self._pre_solve
 
     @pre_solve.setter
-    def pre_solve(self, func: _CollisionCallbackBool) -> None:
+    def pre_solve(self, func: _CollisionCallback) -> None:
         self._pre_solve = func
 
-        if self._pre_solve == CollisionHandler.always_collide:
-            self._handler.preSolveFunc = ffi.addressof(lib, "AlwaysCollide")
+        if self._pre_solve == CollisionHandler.do_nothing:
+            self._handler.preSolveFunc = ffi.addressof(lib, "DoNothing")
         else:
             self._handler.preSolveFunc = lib.ext_cpCollisionPreSolveFunc
 
     @property
-    def post_solve(self) -> _CollisionCallbackNoReturn:
+    def post_solve(self) -> _CollisionCallback:
         """Two shapes are touching and their collision response has been
         processed.
 
@@ -120,18 +118,16 @@ def post_solve(self) -> _CollisionCallbackNoReturn:
         return self._post_solve
 
     @post_solve.setter
-    def post_solve(self, func: _CollisionCallbackNoReturn) -> None:
+    def post_solve(self, func: _CollisionCallback) -> None:
         self._post_solve = func
 
         if self._post_solve == CollisionHandler.do_nothing:
             self._handler.postSolveFunc = ffi.addressof(lib, "DoNothing")
         else:
             self._handler.postSolveFunc = lib.ext_cpCollisionPostSolveFunc
 
-        self._handler.postSolveFunc = lib.ext_cpCollisionPostSolveFunc
-
     @property
-    def separate(self) -> _CollisionCallbackNoReturn:
+    def separate(self) -> _CollisionCallback:
         """Two shapes have just stopped touching for the first time this
         step.
 
@@ -144,7 +140,7 @@ def separate(self) -> _CollisionCallbackNoReturn:
         return self._separate
 
     @separate.setter
-    def separate(self, func: _CollisionCallbackNoReturn) -> None:
+    def separate(self, func: _CollisionCallback) -> None:
         self._separate = func
 
         if self._separate == CollisionHandler.do_nothing:
@@ -161,14 +157,3 @@ def do_nothing(arbiter: Arbiter, space: "Space", data: Dict[Any, Any]) -> None:
         do nothing method.
         """
         return
-
-    @staticmethod
-    def always_collide(arbiter: Arbiter, space: "Space", data: Dict[Any, Any]) -> bool:
-        """The default method used for the begin and pre_solve callbacks.
-
-        It will always return True, meaning the collision should not be ignored.
-
-        Note that its more efficient to set this method than to define your own
-        return True method.
-        """
-        return True