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, the Agent class that ties them together, a vision-cone Perception system (near/far alert zones, line-of-sight), and minimax search with alpha-beta pruning for turn-based adversarial decisions. (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.cutscene: Contains Cutscene (a gale.sequence.Sequence of beats that also ticks/renders any actors involved every frame) and its beats — ShowImage, PlayAnimation (a dependency-free stand-in for video playback), MoveActor, SetActorAnimation, Dialogue, Wait — each lasting a fixed duration or advancing on a specific input. (example)

• gale.ecs: Contains a Data-Oriented Design (ECS) toolkit — a World storing entities (plain integer ids) and components (plain Python objects), queried by System/SystemScheduler to process them in bulk every frame. (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 — a variable-rate update/render pair driven by real elapsed time, plus a fixed_update that steps at a constant rate regardless of frame rate, for anything that needs to be frame-rate-independent (e.g. driving a gale.physics.World).

• 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, configurable-format room codes (encode/decode) for sharing a host/port pair as a short, human-typeable string, a PredictionBuffer for client-side prediction/server reconciliation, and a SnapshotInterpolator/lag_compensated_position for entity interpolation and lag compensation. (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.quest: Contains a customizable-per-game quest system built on gale.sequence — Objective, Stage (a group of objectives), Quest (a sequence of stages), and QuestLog (tracks/starts every quest and broadcasts progress events to whichever are active). (example)

• gale.sequence: Contains Step, StepGroup, and Sequence — the generic “do this until it’s done, then do the next thing” engine shared by gale.quest and gale.cutscene; a step completes after a fixed duration, on a specific input, or by a subclass’s own condition. (example)

• gale.state: Contains the class BaseState, a basic class StateMachine, a basic class StateStack, and HierarchicalState for nesting a sub-StateMachine inside a state (HFSM). (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), IsometricTileMap (the same kind of map rendered in a diamond/isometric projection, plus the standalone cartesian_to_isometric/isometric_to_cartesian transforms, reusable for isometric coordinate math outside of tile maps too), 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.

• gale.ecs: World, components, queries, and Systems/SystemScheduler.

• gale.sequence: Step, StepGroup, and Sequence, the shared engine behind quests and cutscenes.

• gale.quest: Objective, Stage, Quest, and QuestLog.

• gale.cutscene: Cutscene and its beats — images, “video”, actor movement, dialogue.

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.

Three more full games showcase the isometric tilemap, perception, HFSM, minimax, networked prediction/interpolation, and ECS additions: examples/outpost, a small isometric stealth prototype where patrolling guards spot the player through a vision cone and a hierarchical state machine, and a terminal minigame is defended by a minimax AI; examples/circuit, a small online racing prototype with client-side prediction/server reconciliation, entity interpolation, lag compensation, and an AI racer following the track with A*/steering; and examples/futsal, a small futsal match simulation where each team’s behavior tree/Blackboard-driven roles decide intent that a gale.ecs World/SystemScheduler simulates in bulk (movement, fatigue, ball/player collisions).

examples/wayfarer showcases the gale.sequence/gale.quest/gale.cutscene additions: a small top-down adventure where an intro cutscene (a character walking to a mark, pose changes, input-advanced dialogue) hands off into free-roam play, collecting herbs, defeating a wolf, and reporting back to an NPC progress a two-stage QuestLog-tracked quest, completing it triggers a victory cutscene.

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.