Metadata-Version: 2.4
Name: gale-engine
Version: 1.8.0
Summary: Collection of reusable codes to make games by using pygame.
Author-email: Alejandro Mujica <aledrums@gmail.com>
License: MIT License
        
        Copyright (c) 2020 Alejandro J. Mujica (aledrums@gmail.com)
        
        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.
Project-URL: Homepage, https://github.com/R3mmurd/Gale
Project-URL: Repository, https://github.com/R3mmurd/Gale
Project-URL: Issues, https://github.com/R3mmurd/Gale/issues
Keywords: pygame,game,game-development,game-engine
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: Box2D==2.3.10
Requires-Dist: click
Requires-Dist: numpy
Requires-Dist: pygame
Requires-Dist: wheel
Dynamic: license-file

.. image:: https://raw.githubusercontent.com/R3mmurd/Gale/main/logo.png
   :align: center
   :alt: Gale
   :target: https://github.com/R3mmurd/Gale/


|Python3| |Pygame2| |License| |PyPI| |GithubCommits| |BlackFormatBadge| |CIBadge|


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, 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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/gale_ai.rst>`__)
- ``gale.animation``: Contains the class ``Animation``. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/animation.rst>`__)
- ``gale.camera``: Contains the class ``Camera``, a 2D scrolling/zooming camera — following a target, screen shake, bounds clamping, and screen/world coordinate conversion. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/camera.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/ecs.rst>`__)
- ``gale.factory``: Contains the classes ``Factory`` and ``Abstract Factory``. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/factory.rst>`__)
- ``gale.frames``: Contains a util function to generate rectangle frames from a sprite sheet. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/frames.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/input_handler.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/log.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/net.rst>`__)
- ``gale.particle_system``: Contains classes to handle particle systems in your game. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/particle_system.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/physics.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/state.rst>`__)
- ``gale.stencil``: Contains the class ``Stencil``, a CPU-side equivalent of `love.graphics.stencil <https://love2d.org/wiki/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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/stencil.rst>`__)
- ``gale.text``: Contains a util function to ease text rendering and a class ``Text``. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/text.rst>`__)
- ``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 <https://www.mapeditor.org/>`__, 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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/tilemap.rst>`__)
- ``gale.timer``: Contains classes to handle timers that execute action every x seconds, after x seconds, and tweening. (`example <https://github.com/R3mmurd/Gale/blob/main/docs/examples/timer.rst>`__)
- ``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 <https://github.com/R3mmurd/Gale/blob/main/docs/examples/ui.rst>`__)


Installation
------------

.. code-block:: bash

   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:

.. code-block:: bash

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


Examples
--------
- `Project template (gale-admin) <https://github.com/R3mmurd/Gale/blob/main/docs/examples/project_template.rst>`_: scaffolds a new project's directory structure.
- `gale.animation <https://github.com/R3mmurd/Gale/blob/main/docs/examples/animation.rst>`_
- `gale.camera <https://github.com/R3mmurd/Gale/blob/main/docs/examples/camera.rst>`_: following, zoom, bounds, screen shake.
- `gale.factory <https://github.com/R3mmurd/Gale/blob/main/docs/examples/factory.rst>`_
- `gale.frames <https://github.com/R3mmurd/Gale/blob/main/docs/examples/frames.rst>`_
- `gale.input_handler <https://github.com/R3mmurd/Gale/blob/main/docs/examples/input_handler.rst>`_: includes keyboard key combos and gamepads.
- `gale.log <https://github.com/R3mmurd/Gale/blob/main/docs/examples/log.rst>`_: console/file defaults, adding Graylog, Sentry, Discord, or any other destination.
- `gale.net <https://github.com/R3mmurd/Gale/blob/main/docs/examples/net.rst>`_: ``Server``/``Client``, channel choice, RTT, LAN discovery, room codes.
- `gale.particle_system <https://github.com/R3mmurd/Gale/blob/main/docs/examples/particle_system.rst>`_
- `gale.physics <https://github.com/R3mmurd/Gale/blob/main/docs/examples/physics.rst>`_: bodies, shapes, joints, collision callbacks, and the scene graph, with Box2D never exposed directly.
- `gale.state <https://github.com/R3mmurd/Gale/blob/main/docs/examples/state.rst>`_
- `gale.stencil <https://github.com/R3mmurd/Gale/blob/main/docs/examples/stencil.rst>`_: mask an arbitrary shape out of a surface, love2d-stencil style.
- `gale.text <https://github.com/R3mmurd/Gale/blob/main/docs/examples/text.rst>`_
- `gale.tilemap <https://github.com/R3mmurd/Gale/blob/main/docs/examples/tilemap.rst>`_: layers, tilesets, loading a Tiled JSON map, one-way platform collision.
- `gale.timer <https://github.com/R3mmurd/Gale/blob/main/docs/examples/timer.rst>`_
- `gale.ui <https://github.com/R3mmurd/Gale/blob/main/docs/examples/ui.rst>`_: menus, HUDs, and forms built from panels, buttons, list views, text inputs, closable windows, and more.
- `gale.ai <https://github.com/R3mmurd/Gale/blob/main/docs/examples/gale_ai.rst>`_: steering behaviors, behavior tree, decision tree, Blackboard, graphs/search, and the ``Agent`` class.
- `gale.ecs <https://github.com/R3mmurd/Gale/blob/main/docs/examples/ecs.rst>`_: World, components, queries, and Systems/SystemScheduler.

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 <https://github.com/R3mmurd/Gale/blob/main/examples/nightwatch/README.md>`_, 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 <https://github.com/R3mmurd/Gale/blob/main/examples/rally/README.md>`_,
a small online Pong playable over a LAN or the internet; for
``gale.physics``, `examples/leap <https://github.com/R3mmurd/Gale/blob/main/examples/leap/README.md>`_, a
platformer using all three body types, and
`examples/hillclimb <https://github.com/R3mmurd/Gale/blob/main/examples/hillclimb/README.md>`_, a small
vehicle-physics demo built on motorized wheel joints; for
``gale.camera``, `examples/scavenger <https://github.com/R3mmurd/Gale/blob/main/examples/scavenger/README.md>`_,
a coin-collecting game with a scrolling/zooming camera; and, for
``gale.stencil``, `examples/lantern <https://github.com/R3mmurd/Gale/blob/main/examples/lantern/README.md>`_, a
top-down exploration game where the room is only revealed in a circle
around the player; and, for ``gale.tilemap``,
`examples/planks <https://github.com/R3mmurd/Gale/blob/main/examples/planks/README.md>`_,
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 <https://github.com/R3mmurd/Gale/blob/main/examples/outpost/README.md>`_,
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
<https://github.com/R3mmurd/Gale/blob/main/examples/circuit/README.md>`_,
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
<https://github.com/R3mmurd/Gale/blob/main/examples/futsal/README.md>`_,
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).

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``:

.. code-block:: bash

   pip install -r requirements/dev.txt

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

.. code-block:: bash

   pre-commit install

You can also run both checks manually at any time:

.. code-block:: bash

   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 <https://github.com/R3mmurd/Gale/blob/main/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
------------
.. image:: https://contrib.rocks/image?repo=R3mmurd/Gale
   :target: https://github.com/R3mmurd/Gale/graphs/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.


.. |Python3| image:: https://img.shields.io/badge/python-3-blue.svg?v=1
   :target: https://docs.python.org/3/

.. |Pygame2| image:: https://img.shields.io/badge/pygame-green.svg?v=1
   :target: https://www.pygame.org/docs/

.. |License| image:: https://img.shields.io/badge/License-MIT-yellow.svg
   :target: https://opensource.org/licenses/MIT

.. |PyPI| image:: https://img.shields.io/pypi/v/gale-engine.svg
   :target: https://pypi.org/project/gale-engine/

.. |GithubCommits| image:: https://img.shields.io/github/commits-since/R3mmurd/Gale/v1.8.0.svg
   :target: https://github.com/R3mmurd/Gale/compare/v1.8.0...main

.. |BlackFormatBadge| image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

.. |CIBadge| image:: https://github.com/R3mmurd/Gale/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/R3mmurd/Gale/actions/workflows/ci.yml

.. _gale: https://github.com/R3mmurd/Gale
.. _Python: https://www.python.org/
.. _Pygame: https://www.pygame.org
.. _The MIT License: https://opensource.org/licenses
