gale-engine 1.7.0

Collection of reusable codes to make games by using pygame.

Gale is a collection of reusable codes to ease your life when building games with Python and Pygame.

Modules

• gale.ai: Contains a modular toolkit to build autonomous characters: the Kinematic body and steering behaviors, a behavior tree, a decision tree, a shared Blackboard, generic graphs with search algorithms, and the Agent class that ties them together. (example)

• gale.animation: Contains the class Animation. (example)

• gale.camera: Contains the class Camera, a 2D scrolling/zooming camera — following a target, screen shake, bounds clamping, and screen/world coordinate conversion. (example)

• gale.factory: Contains the classes Factory and Abstract Factory. (example)

• gale.frames: Contains a util function to generate rectangle frames from a sprite sheet. (example)

• gale.game: Contains a base class Game to be inherited to ease your game building.

• gale.input_handler: Contains key definitions, mouse button definitions, mouse wheel input definitions, mouse move input definitions, gamepad button/axis definitions (local multiplayer included), classes to store the information about an input, an interface to listen the input handler and the class InputHandler. (example)

• gale.log: Contains logging configuration for gale games — printed to the terminal and written to a plain-text file by default, extensible to Graylog, Sentry, a Discord channel, or anywhere else by attaching another logging.Handler. (example)

• gale.net: Contains a pure-Python, pygame-free toolkit for LAN/internet multiplayer: Server, Client, a hand-rolled reliability layer over UDP, per-peer round-trip-time tracking, LAN discovery, and configurable-format room codes (encode/decode) for sharing a host/port pair as a short, human-typeable string. (example)

• gale.particle_system: Contains classes to handle particle systems in your game. (example)

• gale.physics: Contains a Box2D-backed 2D physics toolkit — World, Body, body types, shapes, joints — that never exposes Box2D itself, plus a lightweight scene graph (Node) for organizing physics entities. (example)

• gale.state: Contains the class BaseState, a basic class StateMachine and a basic class StateStack. (example)

• gale.stencil: Contains the class Stencil, a CPU-side equivalent of love.graphics.stencil to mask an arbitrary shape (a circle, a polygon, a sprite) out of a surface’s alpha channel — handy for a top-down game’s fog-of-war/vision reveal, a circular minimap crop, and similar effects. (example)

• gale.text: Contains a util function to ease text rendering and a class Text. (example)

• gale.tilemap: Contains TileMap/Tileset (grid-of-tiles rendering with gale.camera culling built in), load_tiled_map (loads a map exported as JSON from Tiled, tilesets/object layers included), and an optional move_and_collide platformer collision helper (solid walls, one-way platforms) that never depends on gale.physics. (example)

• gale.timer: Contains classes to handle timers that execute action every x seconds, after x seconds, and tweening. (example)

• gale.ui: Contains a widget toolkit for menus, HUDs, and forms — panels, labels, buttons, progress bars, checkboxes, list views, containers, text boxes (click/Enter-paginated, or button-paginated through PaginatedTextBox), text inputs, cursors, and closable Window\ s, styled through a shared theme. (example)

Installation

pip install gale-engine

The package is published on PyPI as gale-engine (gale and several close variants were already taken), but import gale stays exactly the same either way.

To track main directly instead of the latest release:

pip install https://github.com/R3mmurd/Gale/archive/main.zip

Examples

• Project template (gale-admin): scaffolds a new project’s directory structure.

• gale.animation

• gale.camera: following, zoom, bounds, screen shake.

• gale.factory

• gale.frames

• gale.input_handler: includes keyboard key combos and gamepads.

• gale.log: console/file defaults, adding Graylog, Sentry, Discord, or any other destination.

• gale.net: Server/Client, channel choice, RTT, LAN discovery, room codes.

• gale.particle_system

• gale.physics: bodies, shapes, joints, collision callbacks, and the scene graph, with Box2D never exposed directly.

• gale.state

• gale.stencil: mask an arbitrary shape out of a surface, love2d-stencil style.

• gale.text

• gale.tilemap: layers, tilesets, loading a Tiled JSON map, one-way platform collision.

• gale.timer

• gale.ui: menus, HUDs, and forms built from panels, buttons, list views, text inputs, closable windows, and more.

• gale.ai: steering behaviors, behavior tree, decision tree, Blackboard, graphs/search, and the Agent class.

These are short, focused snippets per module. For full running games built with gale, see examples/space_trip and, in particular for gale.ai, examples/nightwatch, a small stealth demo whose guards patrol, chase, and coordinate through a shared behavior tree, blackboard, and pathfinding; for gale.net/gale.ui, examples/rally, a small online Pong playable over a LAN or the internet; for gale.physics, examples/leap, a platformer using all three body types, and examples/hillclimb, a small vehicle-physics demo built on motorized wheel joints; for gale.camera, examples/scavenger, a coin-collecting game with a scrolling/zooming camera; and, for gale.stencil, examples/lantern, a top-down exploration game where the room is only revealed in a circle around the player; and, for gale.tilemap, examples/planks, a platformer loading a level made in Tiled, with one-way platforms and a scrolling camera.

Each example under examples/ is a standalone project (its own settings.py and src/), so it doesn’t see the copy of gale inside this repository unless it’s actually installed. From the repository root, run pip install -e . once, then cd into the example’s directory and run python main.py from there.

Development

To work on this library, install the development dependencies, which include the runtime dependencies plus pytest and pre-commit:

pip install -r requirements/dev.txt

Then install the git hook so that black and the test suite run automatically before every commit:

pre-commit install

You can also run both checks manually at any time:

black .
pytest

Git workflow

main and develop are protected: nobody (including admins) can push to them directly, so every change has to go through a pull request.

• New work branches off develop and is merged back into develop through a pull request.

• Releases are cut by opening a pull request from develop into main. See PACKAGING.md for the full release/publishing process — publishing a GitHub Release automatically pushes the new version to PyPI.

Every pull request (and every push to a branch with an open pull request) triggers the CI workflow defined in .github/workflows/ci.yml, which installs the dependencies (including pytest, since GitHub-hosted runners don’t ship it) and runs:

• black --check --diff . to enforce the code style.

• pytest to run the whole test suite.

Both checks are required status checks on main and develop: a pull request cannot be merged until they pass.

Contributors

Dependencies

Gale is obviously strongly dependent on Python and Pygame. It also depends on the library Click for our command line implementation.

License

This library is distributed under the MIT License, which can be found in the file LICENSE. We reserve the right to place future versions of this library under a different license.

See docs/licenses for licenses of dependencies.