pygame-topdownengine 0.0.1__py3-none-any.whl

examples/LICENSE

@@ -0,0 +1,121 @@
+Creative Commons Legal Code
+
+CC0 1.0 Universal
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

examples/basic_usage.py

@@ -0,0 +1,78 @@
+import topdownengine as tde
+from topdownengine.mobile_obj.controller import KeyboardInputController, MovementAIController
+from topdownengine.asset_paths import ASSETS_DIR
+from topdownengine.math import scale_rect
+import pygame as pg
+
+# Define an instance of the Game class
+game = tde.Game(
+    screen_width=900, 
+    screen_height=650, 
+    window_title="pygame-topdownengine Basic Usage Example"
+)
+
+# Define a MobileObj to be the Player
+player = tde.MobileObj(
+    controller=KeyboardInputController(), 
+    animation_paths={
+        'idle': ASSETS_DIR / 'example-player' / 'idle.png',
+        'walk': ASSETS_DIR / 'example-player' / 'walk.png'
+    },
+    frame_size=(16, 16),
+    directional_anims=True
+)
+
+# Define a MobileObj to follow the Player
+enemy = tde.MobileObj(
+    controller=MovementAIController(target_mobile_obj=player), 
+    animation_paths={
+        'idle': ASSETS_DIR / 'example-player' / 'idle.png',
+        'walk': ASSETS_DIR / 'example-player' / 'walk.png'
+    },
+    frame_size=(16, 16),
+    directional_anims=True
+)
+
+# Define an env_obj
+env_obj = tde.EnvObject(frame_size=(32, 32), colliders=[pg.Rect(0, 0, 32, 32)])
+env_obj.position = pg.Vector2(100, 100)
+env_obj.obj_shadow = '32x16'
+
+# Add them to the game object group
+game.game_object_group.add(player)
+game.game_object_group.add(env_obj)
+game.game_object_group.add(enemy)
+
+# Rescale GameObjects to have a SCALE of 3 (this makes them more visible)
+tde.GameObject.set_scale(3, game)
+
+# GameObj automatically generates a four frame "flashing animation."
+# In order to disable it, this line of code makes it use only the first frame,
+# which is solid red.
+env_obj.animations = {'idle': [env_obj.animations['idle'][0]]} 
+
+# You can add subpixel rendering by uncommenting the below line of code
+# tde.GameObject.SUBPIXEL = True
+
+# Debug Rendering
+# original_draw = game.render
+# def new_render():
+#     original_draw()
+#     pg.draw.rect(
+#         game.screen, 
+#         (0, 0, 255), 
+#         scale_rect(mobile_obj.hitboxes[0], mobile_obj.SCALE),
+#         1
+#     )
+#     pg.draw.rect(
+#         game.screen, 
+#         (0, 0, 255), 
+#         scale_rect(env_obj.hitboxes[0], env_obj.SCALE),
+#         1
+#     )
+#     pg.display.flip()
+
+# game.render = new_render
+
+# Run the game
+game.run()

pygame_topdownengine-0.0.1.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.4
+Name: pygame-topdownengine
+Version: 0.0.1
+Author: Shaurya Sharma
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Games/Entertainment
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Typing :: Typed
+Requires-Python: >=3.12.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pygame-ce>=2.5.7
+Dynamic: license-file
+
+# pygame-topdownengine
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://opensource.org)
+
+pygame-topdownengine is a 2.5D engine for top-down games. It is designed to be highly modular, with most core systems being located in the easily extendible GameObject class. It is built on top of the pygame-ce package, which you can find here: https://github.com/pygame-community/pygame-ce/tree/main.
+
+## Features
+- GameObject class that contains all of the core systems.
+- Built-in MobileObj class for anything that moves.
+- Option to use either pixel-perfect or subpixel rendering.
+- Dynamic scale-setting for all GameObjects.
+- Robust 3D collision detection.
+
+## Installation
+In order to install pygame-topdownengine, make sure Python and pip are both installed and in PATH. Then, run this command into your terminal:<br>
+`pip install pygame-topdownengine`
+
+## License
+This library is distributed under the MIT license, which can be found in the root of this repository under the `LICENSE` file.
+
+The source files located in the `examples` subfolder are licensed under the Creative Commons Zero 1.0 Universal license, which can be found inside of `examples/LICENSE`.

pygame_topdownengine-0.0.1.dist-info/RECORD

@@ -0,0 +1,26 @@
+examples/LICENSE,sha256=bUia9ikmYtnjbTTOSUI3hJhKX25B17WPSbASZN9Z-gM,7047
+examples/basic_usage.py,sha256=MFRtA_Y36g9CnjaLYdoKfzQHraox5iSCqDojJyD3IiM,2268
+pygame_topdownengine-0.0.1.dist-info/licenses/LICENSE,sha256=Bs3gra1ROdEwV2eWo4tO0hGeG1TCGr3Ind2Fuivqmvg,1071
+tests/conftest.py,sha256=8WLh1VMj_-6zXWmaIU8MxPWOH937SFoqKFNEgGSXx_A,1156
+tests/test_math.py,sha256=lsHwr6InIneiv3Ml3ZsdT5GoREoxvKbtVRt79wx8ZsQ,628
+tests/test_physics.py,sha256=Ehmmu1jd8xA6DAr_Ro-I7W9qZT6xShP9AAyoRuyCnhU,1611
+topdownengine/__init__.py,sha256=zthxjZeMd64W4CdR3XaHx9G5-joBYSTqjJG-UOR9b5U,337
+topdownengine/asset_paths.py,sha256=D1T4_e43S5M9KxNEN706OBjH2FDfo307bahr4bwvgOI,177
+topdownengine/controls.py,sha256=U5QPHW0SAacltF6xOGVSWHOqH8XD4qD6OxktE6RtGgk,3909
+topdownengine/env_object.py,sha256=ZkHm0imjjeBLfrHAay1hYbRYavQ5FWS7O5UP1dH4ljA,1009
+topdownengine/game.py,sha256=bllEGNyRYt01djPPJpeRpInj2GembEArzeflt5AY2-o,2446
+topdownengine/game_object.py,sha256=MzNqZREZ9YrbxzfjF1DW94AiKXFVN53ctKaiimWj5v8,10155
+topdownengine/math.py,sha256=6gZYCtUl8vZbAZcX3Ol5rtEZPkKjMJ15-mUn61kIJzc,885
+topdownengine/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+topdownengine/visual_utils.py,sha256=SPAgfJc9iR7eFrI0d1QfntFMQoqYWiRt1aP1aAj0q0A,5368
+topdownengine/assets/example-player/idle.png,sha256=Y4FF953VvwyCa1uBDlSPnzC0jsLY91Cxm2Ftkv7GKmE,1069
+topdownengine/assets/example-player/walk.png,sha256=p6UOP5XVGd9wQT94g9LsN5oU5clbJ8uEIeUU45_NniM,1068
+topdownengine/assets/shadows/16x8.png,sha256=qbdH3yrTJaWb1yFYOc3D9CoIG8Egm2z7y6Th4r3EdFY,580
+topdownengine/assets/shadows/32x16.png,sha256=AeBKg5M1TIzbGIv7S2mzZ637tNN-n1vXrghAc4KkhtI,633
+topdownengine/assets/shadows/8x4.png,sha256=XKENJ7LYoPjA-lO5LutWBWke1D1LZVBWQF2VbQky8Ao,96
+topdownengine/mobile_obj/__init__.py,sha256=pxEhWLFU0AwpzQ_HRAYRUCdAyfNixpPkeX0JJhnIdEQ,1755
+topdownengine/mobile_obj/controller.py,sha256=vqxqrtD2xfmB9FYh7gX2vtrw36rgG0qywjP9J_YQ3lg,2228
+pygame_topdownengine-0.0.1.dist-info/METADATA,sha256=nSZNqSBf7HLEPBQxo1674_bW3znoKSrO7BteEHnD9uk,1812
+pygame_topdownengine-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pygame_topdownengine-0.0.1.dist-info/top_level.txt,sha256=lCXRjglBoTJ6qfKegxiTx_fC1Zuo-zk0ckiS4nR-Rp4,29
+pygame_topdownengine-0.0.1.dist-info/RECORD,,

pygame_topdownengine-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pygame_topdownengine-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shaurya Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pygame_topdownengine-0.0.1.dist-info/top_level.txt

@@ -0,0 +1,3 @@
+examples
+tests
+topdownengine

tests/conftest.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import pygame as pg
+import pytest
+import topdownengine as tde
+from topdownengine.mobile_obj.controller import KeyboardInputController
+from topdownengine.asset_paths import ASSETS_DIR
+from topdownengine.controls import MoreKeysPressed
+
+# Fixtures
+@pytest.fixture
+def game():
+    game = tde.Game(1, 1)
+    print('Initializing game instance.')
+    yield game
+    pg.quit()
+
+@pytest.fixture
+def mobile_obj():
+    return tde.MobileObj(
+        controller=KeyboardInputController(), 
+        animation_paths={
+            'idle': ASSETS_DIR / 'example-player' / 'idle.png',
+            'walk': ASSETS_DIR / 'example-player' / 'walk.png'
+        },
+        frame_size=(16, 16),
+        directional_anims=True
+    )
+
+# This code "monkey patches" pygame-ce to replace get_pressed with a custom
+# function that allows us to add/remove fake keys to the stream by 
+# adding/removing them from the FAKED_KEYS set.
+FAKED_KEYS = set()
+original_get_pressed = pg.key.get_pressed
+
+def fake_get_pressed():
+    return MoreKeysPressed(original_get_pressed(), FAKED_KEYS)
+
+pg.key.get_pressed = fake_get_pressed

tests/test_math.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+from topdownengine import math as tde_math
+import pytest
+
+LERP_TEST_ARGS = [
+    [5, 8], # P->P
+    [1, -7], # P->N
+    [5, 0], # P->0
+    [-8, 5], # N->P
+    [-5, -10], # N->N
+    [-7, 0], # N->0
+    [0, 7], # 0->P
+    [0, -6], # 0->N
+    [0, 0], # 0->0
+]
+
+@pytest.mark.parametrize("start, end", LERP_TEST_ARGS)
+def test_lerp_with_t_0_equals_start(start, end):
+    assert tde_math.lerp(start, end, 0) == start
+
+@pytest.mark.parametrize("start, end", LERP_TEST_ARGS)
+def test_lerp_with_t_1_equals_end(start, end):
+    assert tde_math.lerp(start, end, 1) == end

tests/test_physics.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import os
+
+# Set dummy drivers before importing pygame
+os.environ["SDL_VIDEODRIVER"] = "dummy"
+os.environ["SDL_AUDIODRIVER"] = "dummy"
+
+import topdownengine as tde
+import pytest
+import pygame as pg
+from conftest import FAKED_KEYS
+
+# Jump Tests
+def test_can_jump_while_grounded(game: tde.Game, mobile_obj: tde.MobileObj):
+    mobile_obj.elevation = mobile_obj.z = 0
+    mobile_obj.jump()
+    assert mobile_obj.z_vel == mobile_obj.jump_vel
+
+def test_cannot_jump_while_airborne(game: tde.Game, mobile_obj: tde.MobileObj):
+    mobile_obj.elevation = 0
+    mobile_obj.z = 10
+    mobile_obj.jump()
+    assert mobile_obj.z_vel != mobile_obj.jump_vel
+
+# 2D Movement Tests
+MOVEMENT_TEST_ARGS = [
+    pg.Vector2(1, 0), # Right
+    pg.Vector2(0, 1), # Down
+    pg.Vector2(-1, 0), # Left
+    pg.Vector2(0, -1), # Up
+    pg.Vector2(1, 1), # Down-Right
+    pg.Vector2(1, -1), # Up-Right
+    pg.Vector2(-1, 1), # Down-Left
+    pg.Vector2(-1, -1) # Up-Left
+]
+@pytest.mark.parametrize("dir", MOVEMENT_TEST_ARGS)
+def test_movement(game: tde.Game, mobile_obj: tde.MobileObj, dir: pg.Vector2):
+    def step(key, condition):
+        FAKED_KEYS.clear()
+        FAKED_KEYS.add(key)
+        game.handle_events()
+        mobile_obj.update(60, game)
+        assert eval(condition)
+
+    if dir.x == 1:
+        step(pg.K_d, 'mobile_obj.velocity.x > 0')
+
+    elif dir.x == -1: 
+        step(pg.K_a, 'mobile_obj.velocity.x < 0') 
+
+    if dir.y == 1:
+        step(pg.K_s, 'mobile_obj.velocity.y > 0')
+
+    elif dir.y == -1: 
+        step(pg.K_w, 'mobile_obj.velocity.y < 0')

topdownengine/__init__.py

@@ -0,0 +1,10 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+"""pygame-topdownengine is a game engine built on top of the pygame-ce
+framework. It allows for the quick creation of 2.5D top-down games."""
+
+from .game import Game
+from .game_object import GameObject
+from .mobile_obj import MobileObj
+from .env_object import EnvObject

topdownengine/asset_paths.py

@@ -0,0 +1,7 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+from pathlib import Path
+
+PACKAGE_ROOT = Path(__file__).resolve().parent
+ASSETS_DIR = PACKAGE_ROOT / "assets"

topdownengine/controls.py

@@ -0,0 +1,109 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import pygame as pg
+from pygame._sdl2.controller import Controller
+
+class KeyboardInputManager:
+    """Acts as a keyboard and mouse input reciever.
+    
+    This class stores keybind information, allows for the serialization
+    and deserialization of keybinds, and collects input data to compile
+    into a list of inputs.
+    
+    Attributes:
+    - keybinds (dict[str,int|str]): Stores all keybind data.
+    - non_hold_inputs (list[str]): List of which inputs can't be held.
+    - keys (ScancodeWrapper): Keys currently pressed.
+    - just_pressed_keys (ScancodeWrapper): Keys pressed in the current frame.
+    """
+
+    def __init__(self) -> None:
+        self.keybinds = {
+            'Move Right': pg.K_d,
+            'Move Left': pg.K_a,
+            'Move Up': pg.K_w,
+            'Move Down': pg.K_s,
+            'Jump': pg.K_SPACE
+        }
+        self.non_hold_inputs = []
+        self.keys = self.just_pressed_keys = NoKeysPressed()
+
+    def serialize(self) -> dict:
+        return {
+            k: pg.key.name(v) if type(v) == int else v
+            for k, v in self.keybinds.items()
+        }
+    
+    def deserialize(self, data: dict) -> None:
+        for k, v in data.items():
+            try:
+                self.keybinds[k] = pg.key.key_code(v)
+            except ValueError:
+                self.keybinds[k] = v
+    
+    def get_input(self) -> list[str]:
+        "Returns all inputs to execute logic for. MUST be called after pg.event.get()."
+        self.keys = pg.key.get_pressed()
+        self.just_pressed_keys = pg.key.get_just_pressed()
+        inputs = []
+
+        for keybind in self.keybinds:
+            if self.keybinds[keybind] == 'Button 1':
+                if pg.mouse.get_just_pressed()[0]: 
+                    inputs.append(keybind) 
+            elif self.keybinds[keybind] == 'Button 3':
+                if pg.mouse.get_just_pressed()[2]: 
+                    inputs.append(keybind) 
+            else:
+                if self.keys[self.keybinds[keybind]]: 
+                    if keybind in self.non_hold_inputs:
+                        if self.just_pressed_keys[self.keybinds[keybind]]:
+                            inputs.append(keybind)
+                    else:
+                        inputs.append(keybind) 
+
+        return inputs
+
+# TODO: Add controller support
+# class ControllerInputManager:
+#     def __init__(self):
+#         self.controller = Controller(0)
+
+#         self.keybinds = {
+#             # 'Interact': pg.K_e,
+#             # 'Inventory': pg.K_i,
+#             'Use Item': pg.CONTROLLER_BUTTON_RIGHTSHOULDER,
+#             'Use Item Special': 5,
+#             # 'Use Ability 1': pg.K_v,
+#             # 'Use Ability 2': pg.K_b,
+#         }
+#         self.non_hold_inputs = ['Interact', 'Inventory']
+
+#     def get_input(self) -> list[str]:
+#         inputs = []
+
+#         for keybind in self.keybinds:
+#             print(self.controller.get_button(self.keybinds[keybind]))
+#             if self.controller.get_button(self.keybinds[keybind]): 
+#                 if keybind in self.non_hold_inputs and False:
+#                     if self.just_pressed_keys[self.keybinds[keybind]]:
+#                         inputs.append(keybind)
+#                 else:
+#                     inputs.append(keybind) 
+#                     print('hello')
+#         return inputs
+
+class NoKeysPressed:
+    "Emulates a pygame ScancodeWrapper where no keys are pressed."
+    def __getitem__(self, key: int) -> bool: 
+        return False
+
+class MoreKeysPressed:
+    "Emulates a pygame ScancodeWrapper where given keys are always pressed."
+    def __init__(self, wrapper: pg.key.ScancodeWrapper, pressed_keys: set) -> None: 
+        self.wrapper = wrapper
+        self.pressed_keys = pressed_keys
+
+    def __getitem__(self, key: int) -> bool:
+        return self.wrapper[key] or key in self.pressed_keys

topdownengine/env_object.py

@@ -0,0 +1,33 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+from .game_object import GameObject
+from typing import Any
+from .game import Game
+import pygame as pg
+
+class EnvObject(GameObject):
+    CAUSES_COLLISIONS = True
+    
+    def __init__(
+        self,
+        animation_paths: dict[str,str]|None=None, 
+        frame_size: tuple[int]|None=None, 
+        colliders: list[pg.Rect]=[],
+        *groups: Any
+    ) -> None:
+        # Set animation paths dict and frame size before calling super().__init__()
+        # This make it automatically load in the animations without
+        # having to call it a second time.
+        self.animation_paths = animation_paths
+        if frame_size is not None:
+            self.frame_size = frame_size
+
+        super().__init__(*groups)
+
+        # Colliders are relative to the EnvObject.
+        # Meanwhile, hitboxes are in world space.
+        self.colliders = colliders
+
+    def update(self, dt: float, game: Game) -> None:
+        super().update(dt, game)

topdownengine/game.py

@@ -0,0 +1,75 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import pygame as pg
+
+class Game:
+    """Acts as the central core of the game and manages the core loop and gamestate.
+    
+    This class initializes pygame-ce, updates and renders all GameObjects,
+    manages different states and transitions between them, runs the core
+    gameplay loop, and serves as the root component.
+    
+    Attributes:
+    - screen (pygame.Surface): The primary display Surface.
+    - is_running (bool): Boolean flag to control execution.
+    - clock (pygame.time.Clock): Controls framerate and handles deltatime.
+    - fps (int): Integer that controls how much FPS the Game should have
+    - game_object_group (pygame.sprite.Group): Stores all GameObjects.
+    - game_speed_percentage (float): The speed percentage for execution, ranging from 0 to 1.
+    """
+
+    def __init__(
+        self, 
+        screen_width: int, 
+        screen_height: int,
+        window_title: str='pygame-topdownengine',
+        window_icon_path: str|None=None,
+        fps: int=60
+    ) -> None:
+        # Initialize pygame-ce
+        pg.init()
+
+        # Initialize display
+        if window_icon_path is not None:
+            pg.display.set_icon(pg.image.load(window_icon_path))
+
+        self.screen = pg.display.set_mode((screen_width, screen_height))
+        pg.display.set_caption(window_title)
+
+        # Clock + FPS
+        self.clock = pg.time.Clock()
+        self.fps = fps
+
+        # Is Running Boolean Flag
+        self.is_running = True
+
+        # GameObject Group
+        self.game_object_group = pg.sprite.Group()
+
+        # Game Speed Percentage
+        self.game_speed_percentage = 1
+
+    def handle_events(self) -> None:
+        for event in pg.event.get():
+            if event.type == pg.QUIT:
+                self.is_running = False
+                break
+    
+    def update(self, dt: float) -> None:
+        self.game_object_group.update(dt, self)
+
+    def render(self) -> None:
+        self.screen.fill((255, 255, 255))
+        for game_obj in sorted(self.game_object_group.sprites(), key=lambda g: g.draw_index):
+            self.screen.blit(game_obj.image, game_obj.rect)
+        pg.display.flip()
+
+    def run(self) -> None:
+        while self.is_running:
+            dt = self.clock.tick(self.fps) * self.game_speed_percentage
+            self.handle_events()
+            self.update(dt)
+            self.render()
+        pg.quit()
+        exit()

topdownengine/game_object.py

@@ -0,0 +1,269 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import pygame as pg
+from .game import Game
+from .visual_utils import VisualUtils
+from topdownengine import math as tde_math
+
+class GameObject(pg.sprite.Sprite):
+    SCALE = 1
+    SHADOWS = None
+    SUBPIXEL = False
+    VELOCITY_DEADZONE = 0.2
+    CAUSES_COLLISIONS = False
+
+    def __init__(self, *groups: pg.sprite.Group) -> None:
+        super().__init__(*groups)
+
+        # Position, Z-Axis, Velocity
+        self.position = pg.Vector2()
+        self.velocity = pg.Vector2()
+        self.elevation = 0
+        self.z = 0
+        self.z_vel = 0
+        self.gravity = 0.005
+        self.height = 8
+
+        # Visuals
+        self.frame = 0
+        self.anim_speed = 0.25
+        if getattr(self, 'animation_paths', None) is not None:
+            self.current_animation = list(self.animation_paths.keys())[0]
+        else:
+            self.current_animation = 'idle'
+        self.obj_shadow = '16x8'
+        self.load_animations()
+        self.scale_animations()
+        if self.SHADOWS is None:
+            GameObject.load_and_scale_shadows()
+
+        self.colliders = self.generate_colliders()
+    
+    # Visual Methods + Properties
+    @classmethod
+    def load_and_scale_shadows(cls) -> None:
+        from topdownengine.asset_paths import ASSETS_DIR
+        shadows = list((ASSETS_DIR / "shadows").glob("*.png"))
+        cls.SHADOWS = dict()
+        for shadow in shadows:
+            shadow_img = pg.image.load(
+                shadow
+            ).convert_alpha()
+
+            cls.SHADOWS[shadow.name.replace('.png', '')] = pg.transform.scale(
+                shadow_img,
+                (shadow_img.width * cls.SCALE, shadow_img.height * cls.SCALE)
+            )
+
+    def load_animations(self) -> None:
+        "Load unscaled animations."
+        self.animations = dict()
+
+        if getattr(self, 'animation_paths', None) is None:
+            # When there is no animation path data, add red
+            # square idle animation with changing colors.
+            self.animations['idle'] = []
+            for i in range(4):
+                image = pg.Surface(getattr(self, 'frame_size', (16, 16)))
+                image.fill((255/(i+1), 0, 0))
+                self.animations['idle'].append(image.convert_alpha())
+        else:
+            for k, v in self.animation_paths.items():
+                if getattr(self, 'directional_anims', False):
+                    dirs = ['d', 'r', 'u', 'l']
+                    all_anims = VisualUtils.load_animations(v, *self.frame_size)
+                    all_anims.append(VisualUtils.flip_animation(all_anims[1], True, False))
+                    for i, anim in enumerate(all_anims):
+                        self.animations[f'{k}_{dirs[i]}'] = anim
+
+                else:
+                    self.animations[k] = VisualUtils.load_animation(v, *self.frame_size)
+
+    def scale_animations(self) -> None:
+        "Scale animations."
+        for _, anim in self.animations.items():
+            for i, frame in enumerate(anim):
+                anim[i] = pg.transform.scale(
+                    frame,
+                    (frame.width * self.SCALE, frame.height * self.SCALE)
+                )
+
+    @classmethod
+    def set_scale(cls, new_scale: int, game: Game|None) -> None:
+        cls.SCALE = new_scale
+        cls.load_and_scale_shadows()
+        if game is None: return
+        for go in game.game_object_group:
+            go.load_animations()
+            go.scale_animations()
+
+    @property
+    def current_frame(self) -> pg.Surface:
+        "Current animation frame the GameObj is on."
+        if getattr(self, 'directional_anims', False):
+            current_anim = self.animations[f"{self.current_animation}_{self.current_dir}"]
+        else:
+            current_anim = self.animations[self.current_animation]
+        return current_anim[int(self.frame) % len(current_anim)]
+
+    @property
+    def image(self) -> pg.Surface:
+        "Image for drawing."
+        frame = self.current_frame
+        shadow = None
+        if self.obj_shadow is not None:
+            shadow = self.SHADOWS[self.obj_shadow]
+
+        if self.SUBPIXEL:
+            z_elevation_offset = (self.z - self.elevation) * self.SCALE
+        else:
+            z_elevation_offset = int(self.z - self.elevation) * self.SCALE
+        image = pg.Surface(
+            (
+                frame.width, 
+                (frame.height + z_elevation_offset + 
+                (shadow.height//2 if shadow is not None else 0))
+            ), 
+            pg.SRCALPHA
+        )
+        if shadow is not None: image.blit(shadow, (0, image.height - shadow.height))
+        image.blit(frame, (0, 0))
+        return image
+        
+    @property
+    def rect(self) -> pg.Rect|pg.FRect:
+        "Rect object for drawing."
+        shadow_offset = pg.Vector2(0, self.SHADOWS[self.obj_shadow].height//2 if self.obj_shadow is not None else 0)
+        elev_pos = self.position - pg.Vector2(0, self.elevation)
+        if self.SUBPIXEL:
+            return self.image.get_frect(
+                midbottom=elev_pos * self.SCALE + shadow_offset
+            )
+
+        elev_pos.x = int(elev_pos.x)
+        elev_pos.y = int(elev_pos.y)
+        return self.image.get_rect(
+            midbottom=elev_pos * self.SCALE + shadow_offset
+        )
+    
+    @property
+    def draw_index(self) -> tuple[int|float]:
+        return (self.z, self.rect.bottom)
+    
+    # Collisions
+    def generate_colliders(self) -> list[pg.Rect|pg.FRect]:
+        "Default list of Rect objects for collisions."
+        frame = self.current_frame
+        elev_pos = self.position - pg.Vector2(0, self.elevation)
+        if self.SUBPIXEL:
+            r = self.current_frame.get_frect(
+                topleft=elev_pos * self.SCALE
+            )
+        else:
+            elev_pos.x = int(elev_pos.x)
+            elev_pos.y = int(elev_pos.y)
+            r = self.current_frame.get_rect(
+                topleft=elev_pos * self.SCALE
+            )
+
+        r = tde_math.scale_rect(r, 1/self.SCALE)
+
+        return [r]
+    
+    @property
+    def hitboxes(self) -> list[pg.Rect]:
+        """Return a list of hitbox Rects in world-space, as opposed to
+        GameObj.colliders, which uses relative positioning to the
+        GameObj itself."""
+        return [
+            pg.Rect(c.left + self.position.x - c.width//2, c.top + self.position.y - c.height - self.elevation, c.width, c.height)
+            for c in self.colliders
+        ]
+    
+    @property
+    def unelevated_hitboxes(self) -> list[pg.Rect]:
+        """Return a list of hitbox Rects in world-space unelevated, as opposed to
+        GameObj.colliders, which uses relative positioning to the
+        GameObj itself."""
+        return [
+            pg.Rect(c.left + self.position.x - c.width//2, c.top + self.position.y - c.height, c.width, c.height)
+            for c in self.colliders
+        ]
+
+    def _handle_collision(self, dir: pg.Vector2, game: Game) -> bool:
+        """Checks for collisions and moves the GameObj. Returns whether a collision occured or not."""
+        if dir.x and dir.y:
+            raise ValueError('Both axes cannot be moved in one step. Move them in separate method calls.')
+        
+        moving_right = dir.x > 0
+        moving_down = dir.y > 0
+        moving_x = bool(dir.x)
+
+        self.position += dir
+
+        collision_found = True
+        return_value = False
+        while collision_found:
+            collision_found = False
+            for self_hitbox in self.hitboxes:  # always fresh
+                for game_obj in game.game_object_group:
+                    if game_obj is self or not game_obj.CAUSES_COLLISIONS or (game_obj.z + game_obj.height) <= self.z:
+                        continue
+                    for other_hitbox in game_obj.hitboxes:
+                        if self_hitbox.colliderect(other_hitbox):
+                            if moving_x:
+                                if moving_right:
+                                    self.position.x += other_hitbox.left - self_hitbox.right
+                                else:
+                                    self.position.x += other_hitbox.right - self_hitbox.left
+                            else:
+                                if moving_down:
+                                    self.position.y += other_hitbox.top - self_hitbox.bottom
+                                else:
+                                    self.position.y += other_hitbox.bottom - self_hitbox.top
+                            collision_found = True
+                            return_value = True
+                            break  # restart with fresh hitboxes
+                    if collision_found:
+                        break
+                if collision_found:
+                    break
+
+        return return_value
+
+    def _handle_elevation(self, game: Game) -> None:
+        new_elevation = 0
+
+        for self_hitbox in self.hitboxes:
+            for game_obj in game.game_object_group:
+                if game_obj is self or not game_obj.CAUSES_COLLISIONS:
+                    continue
+
+                for other_hitbox in game_obj.hitboxes:
+                    if self_hitbox.colliderect(other_hitbox) or self.unelevated_hitboxes[self.hitboxes.index(self_hitbox)].colliderect(other_hitbox):
+                        new_elevation = max(new_elevation, game_obj.height + game_obj.elevation)
+
+        self.elevation = new_elevation
+
+    # Update
+    def update(self, dt: float, game: Game) -> None:
+        # Gravity
+        self.z_vel -= self.gravity * dt
+        self.z += self.z_vel * dt
+        self.z = max(self.z, self.elevation)
+
+        # Frame Update
+        self.frame += self.anim_speed * dt
+
+        # Add Velocity To Position
+        if self.velocity.length() <= self.VELOCITY_DEADZONE:
+            # Add a 'deadzone' where if the velocity is low enough, it just becomes (0, 0)
+            self.velocity = pg.Vector2()
+
+        if not self.velocity.length():
+            return
+        
+        self._handle_collision(pg.Vector2(self.velocity.x, 0), game)
+        self._handle_collision(pg.Vector2(0, self.velocity.y), game)
+        self._handle_elevation(game)

topdownengine/math.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import pygame as pg
+
+def lerp(start: float|pg.Vector2, end: float|pg.Vector2, t: float) -> float:
+    """This function linearly interpolates two floats or Vectors. Accepts t values
+    outside of the [0, 1] range. The start and end MUST be the same type.
+    
+    Keyword arguments:
+    start -- Start Vector/float
+    end -- End Vector/float
+    t -- Interpolation weight
+    Return: New Vector/float
+    """
+    if type(start) != type(end):
+        raise TypeError(f'{type(start)} and {type(end)} are not the same; they must be equal.')
+    return start + (end - start) * t
+
+def scale_rect(rect: pg.Rect|pg.FRect, scalar: int|float) -> pg.Rect|pg.FRect:
+    new_rect = rect.copy()
+    new_rect.width *= scalar
+    new_rect.height *= scalar
+    new_rect.top *= scalar
+    new_rect.left *= scalar
+
+    return new_rect

topdownengine/mobile_obj/__init__.py

@@ -0,0 +1,53 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+from topdownengine.game_object import GameObject
+from typing import Any
+from topdownengine.game import Game
+
+class MobileObj(GameObject):
+    def __init__(
+        self, 
+        controller: Any,
+        animation_paths: dict[str,str]|None=None, 
+        frame_size: tuple[int]|None=None, 
+        directional_anims: bool=False, 
+        *groups: Any
+    ) -> None:
+        # Set animation paths dict and frame size before calling super().__init__()
+        # This make it automatically load in the animations without
+        # having to call it a second time.
+        self.animation_paths = animation_paths
+        if frame_size is not None:
+            self.frame_size = frame_size
+        self.directional_anims = directional_anims
+        if self.directional_anims:
+            self.current_dir = 'd'
+
+        super().__init__(*groups)
+        self.controller = controller
+        self.jump_vel = 0.75
+
+    def update(self, dt: float, game: Game) -> None:
+        self.controller.update(self, dt)
+        super().update(dt, game)
+        if self.velocity.length():
+            self.current_animation = 'walk'
+            angle = self.velocity.as_polar()[1]
+            if -45 <= angle <= 45: # Right
+                self.current_dir = 'r'
+
+            elif (-180 <= angle <= -135) or (135 <= angle <= 180): # Left
+                self.current_dir = 'l'
+
+            elif 45 <= angle <= 135: # Down
+                self.current_dir = 'd'
+
+            elif -135 <= angle <= -45: # Up
+                self.current_dir = 'u'
+        else:
+            self.current_animation = 'idle'
+
+    def jump(self) -> None:
+        if self.elevation == self.z:
+            self.z_vel = self.jump_vel

topdownengine/mobile_obj/controller.py

@@ -0,0 +1,61 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+from topdownengine.controls import KeyboardInputManager
+import pygame as pg
+import math
+from topdownengine import math as tde_math
+from . import MobileObj
+
+class BaseMobileObjController:
+    "A base class for all MobileObj controllers."
+    def update(self, mobile_obj: MobileObj, dt: float) -> None:
+        """Update function for MobileObj controllers."""
+        pass
+
+    def move(self, mobile_obj: MobileObj, dt: float, dir: pg.Vector2) -> None:
+        if dir.length() != 0: 
+            dir.normalize_ip()
+            dir *= self.speed
+
+        dt_seconds = dt / 1000.0
+        weight = 1.0 - math.exp(-self.snapping_speed * dt_seconds)
+        mobile_obj.velocity = tde_math.lerp(mobile_obj.velocity, dir, weight)
+
+class StaticController(BaseMobileObjController):
+    "A MobileObj controller that keeps the MobileObj still."
+    def update(self, mobile_obj: MobileObj, dt: float) -> None:
+        "Sets the MobileObj's velocity to (0, 0)."
+        mobile_obj.velocity = pg.Vector2()
+
+class KeyboardInputController(BaseMobileObjController):
+    "A MobileObj controller that uses keyboard inputs."
+    def __init__(self) -> None:
+        "Initializes the input manager."
+        self.input_mgr = KeyboardInputManager()
+        self.speed = 2
+        self.snapping_speed = 10.0
+
+    def update(self, mobile_obj: MobileObj, dt: float) -> None:
+        "Moves the MobileObj based on keyboard input."
+        input = self.input_mgr.get_input()
+
+        if 'Jump' in input:
+            mobile_obj.jump()
+
+        dir = pg.Vector2(
+            int('Move Right' in input) - int('Move Left' in input),
+            int('Move Down' in input) - int('Move Up' in input)
+        )
+        self.move(mobile_obj, dt, dir)
+
+class MovementAIController(BaseMobileObjController):
+    def __init__(self, target_mobile_obj: MobileObj) -> None:
+        self.target_mobile_obj = target_mobile_obj
+        self.speed = 1.5
+        self.snapping_speed = 10.0
+
+    def update(self, mobile_obj: MobileObj, dt: float) -> None:
+        "Move the MobileObj towards the target."
+        dir = self.target_mobile_obj.position - mobile_obj.position
+        self.move(mobile_obj, dt, dir)

topdownengine/visual_utils.py

@@ -0,0 +1,138 @@
+# Copyright (c) 2026 Shaurya Sharma
+# SPDX-License-Identifier: MIT
+
+import pygame as pg
+
+class VisualUtils:
+    @staticmethod
+    def load_animation(
+        filename: str, 
+        frame_width: int, 
+        frame_height: int,
+        new_frame_width: int=None, 
+        new_frame_height: int=None
+    ) -> list[pg.Surface]:
+        "Loads an animation from a given file with a given frame width and height"
+        sheet = pg.image.load(filename).convert_alpha()
+        frames = []
+        frame_count = sheet.get_width() // frame_width
+        for i in range(frame_count):
+            rect = pg.Rect(i * frame_width, 0, frame_width, frame_height)
+            frame = pg.transform.scale(sheet.subsurface(rect), (frame_width, frame_height))
+            if new_frame_width is not None or new_frame_height is not None:
+                frame = pg.transform.scale(frame, (new_frame_width if new_frame_width is not None else frame_width, new_frame_height if new_frame_height is not None else frame_height))
+            frames.append(frame)
+        return frames
+
+    @staticmethod
+    def load_animations(
+        filename: str, 
+        frame_width: int, 
+        frame_height: int, 
+        scale_to: int|tuple=None
+    ) -> list[list[pg.Surface]]:
+        "Loads multiple animations from a given spritesheet with a given frame width and height."
+        sheet = pg.image.load(filename).convert_alpha()
+        all_rows = []
+        
+        cols = sheet.get_width() // frame_width
+        rows = sheet.get_height() // frame_height
+        
+        for row in range(rows):
+            current_row_frames = []  # Start a new list for this specific row
+            for col in range(cols):
+                rect = pg.Rect(col * frame_width, row * frame_height, frame_width, frame_height)
+                if scale_to:
+                    if type(scale_to) == int:
+                        frame = pg.transform.scale(sheet.subsurface(rect), (rect.width * scale_to, rect.height * scale_to))
+                    else:
+                        frame = pg.transform.scale(sheet.subsurface(rect), scale_to)
+                else:
+                    frame = sheet.subsurface(rect)
+                current_row_frames.append(frame)
+            
+            all_rows.append(current_row_frames) # Add the finished row to the master list
+                
+        return all_rows
+    
+    @staticmethod
+    def flip_animation(
+        anim: list[pg.Surface], 
+        flip_x: bool=False, 
+        flip_y: bool=False
+    ) -> list[pg.Surface]:
+        new_anim = []
+        for frame in anim:
+            new_anim.append(
+                pg.transform.flip(
+                    frame,
+                    flip_x,
+                    flip_y
+                )
+            )
+        return new_anim
+
+    @staticmethod
+    def replace_color(
+        surface: pg.Surface, 
+        old_color: pg.typing.ColorLike, 
+        new_color: pg.typing.ColorLike
+    ) -> pg.Surface:
+        "Replace all of one given color in a Surface with another."
+        surface_new = surface.copy()
+        with pg.PixelArray(surface_new) as pixels:
+            pixels.replace(old_color, new_color)
+        return surface_new
+
+    @staticmethod
+    def make_img_white(surface: pg.Surface, amount: int=255) -> pg.Surface:
+        "Make a Surface white to a given degree (defaults to 255)."
+        silhouette = surface.copy()
+        silhouette.fill((amount, amount, amount, 0), special_flags=pg.BLEND_RGBA_ADD)
+        return silhouette
+
+    @staticmethod
+    def draw_low_res_line(
+        surface: pg.Surface, 
+        color: pg.typing.ColorLike, 
+        start_pos: pg.typing.Point, 
+        end_pos: pg.typing.Point, 
+        res: int=256
+    ) -> None:
+        "Draw a line that matches the game's pixel resolution."
+        sw, sh = surface.get_size()
+        if sw > sh:
+            lw, lh = res, int(res * (sh / sw))
+        else:
+            lw, lh = int(res * (sw / sh)), res
+            
+        low_res_surf = pg.Surface((max(1, lw), max(1, lh)), pg.SRCALPHA)
+        scale = sw / lw
+        x0, y0 = int(start_pos[0] / scale), int(start_pos[1] / scale)
+        x1, y1 = int(end_pos[0] / scale), int(end_pos[1] / scale)
+        pg.draw.line(low_res_surf, color, (x0, y0), (x1, y1), 1)
+        final_surf = pg.transform.scale(low_res_surf, (sw, sh))
+        surface.blit(final_surf, (0, 0))
+
+    @staticmethod
+    def create_outline(
+        surface: pg.Surface, 
+        thickness: int, 
+        outline_color: pg.typing.ColorLike
+    ) -> pg.Surface:
+        "Create an outline of a given thickness and color on a Surface."
+        mask = pg.mask.from_surface(surface)
+        mask_surface = mask.to_surface(setcolor=outline_color)
+        mask_surface.set_colorkey((0, 0, 0))
+        new_width = surface.get_width() + (thickness * 2)
+        new_height = surface.get_height() + (thickness * 2)
+        combined_surface = pg.Surface((new_width, new_height), pg.SRCALPHA)
+        for dx in range(-thickness, thickness + 1):
+            for dy in range(-thickness, thickness + 1):
+                if dx == 0 and dy == 0:
+                    continue
+                if dx**2 + dy**2 <= thickness**2:
+                    combined_surface.blit(mask_surface, (dx + thickness, dy + thickness))
+                    
+        combined_surface.blit(surface, (thickness, thickness))
+        return combined_surface