Add per-region collision channel/mask filtering to HitBox

Each hitbox region can now have a channel (what it is) and mask (what
it collides with) bitmask. Collision only occurs when both sides agree:
(A.channel & B.mask) != 0 AND (B.channel & A.mask) != 0.

Adds channels() utility for converting 1-based channel numbers to
bitmasks, RawHitBox v2 serialization format, and updates the
multi-hitbox example to demonstrate channel-based filtering.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Cleptomania

arcade/examples/sprite_multi_hitbox.py

@@ -1,9 +1,13 @@
 """
-Sprite Multi-Region Hit Boxes
+Sprite Multi-Region Hit Boxes with Collision Channels
 
-Demonstrates sprites with multiple hit box regions. The player sprite
-has a "body" region and a "shield" region extending to one side.
-Coins that touch any region of the player are collected.
+Demonstrates sprites with multiple hit box regions and per-region
+collision channels. The player sprite has a "body" region on channel 1
+and a "shield" region on channel 2.
+
+Gold coins are on channel 1 and can only be collected by the body.
+Blue gems are on channel 2 and can only be collected by the shield.
+Coins pass through the shield, and gems pass through the body.
 
 Hit box outlines are drawn for visual debugging. Use A/D to rotate
 the player and see both regions rotate together.
@@ -16,15 +20,16 @@
 import random
 import math
 import arcade
-from arcade.hitbox import HitBox
+from arcade.hitbox import HitBox, channels
 
 WINDOW_WIDTH = 1280
 WINDOW_HEIGHT = 720
 WINDOW_TITLE = "Multi-Region Hit Box Example"
 
 PLAYER_SPEED = 5.0
-COIN_SPEED = 2.0
-COIN_COUNT = 20
+ITEM_SPEED = 2.0
+COIN_COUNT = 15
+GEM_COUNT = 10
 
 
 class GameView(arcade.View):
@@ -34,7 +39,9 @@ def __init__(self):
         self.player_sprite = None
         self.player_list = None
         self.coin_list = None
-        self.score = 0
+        self.gem_list = None
+        self.coin_score = 0
+        self.gem_score = 0
         self.score_display = None
         self.background_color = arcade.csscolor.DARK_SLATE_GRAY
 
@@ -46,9 +53,11 @@ def __init__(self):
     def setup(self):
         self.player_list = arcade.SpriteList()
         self.coin_list = arcade.SpriteList()
-        self.score = 0
+        self.gem_list = arcade.SpriteList()
+        self.coin_score = 0
+        self.gem_score = 0
         self.score_display = arcade.Text(
-            text="Score: 0",
+            text="Coins: 0  |  Gems: 0",
             x=10, y=WINDOW_HEIGHT - 30,
             color=arcade.color.WHITE, font_size=16,
         )
@@ -58,57 +67,79 @@ def setup(self):
         self.player_sprite = arcade.Sprite(img, scale=0.5)
         self.player_sprite.position = WINDOW_WIDTH / 2, WINDOW_HEIGHT / 2
 
-        # Replace the default hitbox with a multi-region hitbox.
-        # "body" is a box around the torso, "shield" extends to the right.
-        # Collision detection automatically checks all regions.
+        # Multi-region hitbox with collision channels:
+        #   "body"   on channel 1 — collides with coins (also on channel 1)
+        #   "shield" on channel 2 — collides with gems  (also on channel 2)
         self.player_sprite.hit_box = HitBox(
             {
                 "body": [(-15, -48), (-15, 40), (15, 40), (15, -48)],
-                "shield": [(15, -30), (15, 30), (45, 30), (45, -30)],
+                "shield": {
+                    "points": [(35, -30), (35, 30), (65, 30), (65, -30)],
+                    "channel": channels(2),
+                    "mask": channels(2),
+                },
             },
             position=self.player_sprite.position,
             scale=self.player_sprite.scale,
             angle=self.player_sprite.angle,
         )
 
         self.player_list.append(self.player_sprite)
-        self._spawn_coins(COIN_COUNT)
+        self._spawn_items(self.coin_list, COIN_COUNT, is_gem=False)
+        self._spawn_items(self.gem_list, GEM_COUNT, is_gem=True)
 
-    def _spawn_coins(self, count):
+    def _spawn_items(self, sprite_list, count, is_gem):
         for _ in range(count):
-            coin = arcade.Sprite(":resources:images/items/coinGold.png", scale=0.4)
+            if is_gem:
+                item = arcade.Sprite(
+                    ":resources:images/items/gemBlue.png", scale=0.4,
+                )
+                # Gems are on channel 2 — only the shield can catch them
+                item.hit_box = HitBox(
+                    item.hit_box.points,
+                    position=item.position,
+                    scale=item.scale,
+                    channel=channels(2),
+                    mask=channels(2),
+                )
+            else:
+                item = arcade.Sprite(
+                    ":resources:images/items/coinGold.png", scale=0.4,
+                )
+                # Coins keep the default channel 1 — only the body can catch them
 
             # Spawn along a random edge
             side = random.randint(0, 3)
             if side == 0:
-                coin.center_x = random.randrange(WINDOW_WIDTH)
-                coin.center_y = WINDOW_HEIGHT + 20
+                item.center_x = random.randrange(WINDOW_WIDTH)
+                item.center_y = WINDOW_HEIGHT + 20
             elif side == 1:
-                coin.center_x = random.randrange(WINDOW_WIDTH)
-                coin.center_y = -20
+                item.center_x = random.randrange(WINDOW_WIDTH)
+                item.center_y = -20
             elif side == 2:
-                coin.center_x = -20
-                coin.center_y = random.randrange(WINDOW_HEIGHT)
+                item.center_x = -20
+                item.center_y = random.randrange(WINDOW_HEIGHT)
             else:
-                coin.center_x = WINDOW_WIDTH + 20
-                coin.center_y = random.randrange(WINDOW_HEIGHT)
+                item.center_x = WINDOW_WIDTH + 20
+                item.center_y = random.randrange(WINDOW_HEIGHT)
 
             # Aim toward the center with some randomness
             target_x = WINDOW_WIDTH / 2 + random.randint(-200, 200)
             target_y = WINDOW_HEIGHT / 2 + random.randint(-200, 200)
-            dx = target_x - coin.center_x
-            dy = target_y - coin.center_y
+            dx = target_x - item.center_x
+            dy = target_y - item.center_y
             dist = math.hypot(dx, dy)
             if dist > 0:
-                coin.change_x = (dx / dist) * COIN_SPEED
-                coin.change_y = (dy / dist) * COIN_SPEED
+                item.change_x = (dx / dist) * ITEM_SPEED
+                item.change_y = (dy / dist) * ITEM_SPEED
 
-            self.coin_list.append(coin)
+            sprite_list.append(item)
 
     def on_draw(self):
         self.clear()
 
         self.coin_list.draw()
+        self.gem_list.draw()
         self.player_list.draw()
 
         # Debug: draw each hitbox region in a different color
@@ -119,10 +150,12 @@ def on_draw(self):
             arcade.draw_line_strip(tuple(pts) + (pts[0],), color=color, line_width=2)
 
         self.coin_list.draw_hit_boxes(color=arcade.color.YELLOW, line_thickness=1)
+        self.gem_list.draw_hit_boxes(color=arcade.color.BLUE, line_thickness=1)
         self.score_display.draw()
 
         arcade.draw_text(
-            "Red = Body  |  Cyan = Shield  |  Arrow keys to move  |  A/D to rotate",
+            "Red body (ch1) = coins  |  Cyan shield (ch2) = gems  |  "
+            "Arrows to move  |  A/D to rotate",
             WINDOW_WIDTH / 2, 20,
             arcade.color.WHITE, font_size=12, anchor_x="center",
         )
@@ -165,27 +198,46 @@ def on_update(self, delta_time):
         if keys[arcade.key.D]:
             self.player_sprite.angle += 3.0
 
-        # Move coins
+        # Move items
         self.coin_list.update()
+        self.gem_list.update()
 
-        # Standard collision check — automatically tests all hitbox regions
-        hit_list = arcade.check_for_collision_with_list(
+        # Coins only collide with the body (channel 1)
+        coin_hits = arcade.check_for_collision_with_list(
             self.player_sprite, self.coin_list
         )
-        if hit_list:
-            for coin in hit_list:
-                coin.remove_from_sprite_lists()
-                self.score += 1
-            self.score_display.text = f"Score: {self.score}"
+        for coin in coin_hits:
+            coin.remove_from_sprite_lists()
+            self.coin_score += 1
+
+        # Gems only collide with the shield (channel 2)
+        gem_hits = arcade.check_for_collision_with_list(
+            self.player_sprite, self.gem_list
+        )
+        for gem in gem_hits:
+            gem.remove_from_sprite_lists()
+            self.gem_score += 1
+
+        if coin_hits or gem_hits:
+            self.score_display.text = (
+                f"Coins: {self.coin_score}  |  Gems: {self.gem_score}"
+            )
 
-        # Replace coins that left the screen
+        # Replace items that left the screen
         margin = 100
-        for coin in list(self.coin_list):
-            if (coin.center_x < -margin or coin.center_x > WINDOW_WIDTH + margin
-                    or coin.center_y < -margin or coin.center_y > WINDOW_HEIGHT + margin):
-                coin.remove_from_sprite_lists()
+        for item in list(self.coin_list):
+            if (item.center_x < -margin or item.center_x > WINDOW_WIDTH + margin
+                    or item.center_y < -margin or item.center_y > WINDOW_HEIGHT + margin):
+                item.remove_from_sprite_lists()
+        for item in list(self.gem_list):
+            if (item.center_x < -margin or item.center_x > WINDOW_WIDTH + margin
+                    or item.center_y < -margin or item.center_y > WINDOW_HEIGHT + margin):
+                item.remove_from_sprite_lists()
+
         if len(self.coin_list) < COIN_COUNT:
-            self._spawn_coins(COIN_COUNT - len(self.coin_list))
+            self._spawn_items(self.coin_list, COIN_COUNT - len(self.coin_list), is_gem=False)
+        if len(self.gem_list) < GEM_COUNT:
+            self._spawn_items(self.gem_list, GEM_COUNT - len(self.gem_list), is_gem=True)
 
 
 def main():

arcade/hitbox/__init__.py

@@ -2,7 +2,15 @@
 
 from arcade.types import Point2List
 
-from .base import HitBox, HitBoxAlgorithm, RawHitBox
+from .base import (
+    DEFAULT_CHANNEL,
+    DEFAULT_MASK,
+    HitBox,
+    HitBoxAlgorithm,
+    RawHitBox,
+    RawHitBoxRegion,
+    channels,
+)
 from .bounding_box import BoundingHitBoxAlgorithm
 
 from .simple import SimpleHitBoxAlgorithm
@@ -60,6 +68,10 @@ def calculate_hit_box_points_detailed(
     "HitBoxAlgorithm",
     "HitBox",
     "RawHitBox",
+    "RawHitBoxRegion",
+    "DEFAULT_CHANNEL",
+    "DEFAULT_MASK",
+    "channels",
     "SimpleHitBoxAlgorithm",
     "PymunkHitBoxAlgorithm",
     "BoundingHitBoxAlgorithm",