Metadata-Version: 2.4
Name: pygame-foundation
Version: 0.2.1
Summary: A modern wrapper around Pygame.
Author: Arad Rezakhani
License: MIT
Keywords: pygame,game,gamedev,engine,framework
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame-ce>=2.5
Requires-Dist: termcolor>=3.1
Dynamic: license-file

# Animation System

The animation system provides frame-based animation support for `pygame-foundation`.

It allows entities to store multiple animations, switch between them, control playback, and automatically update their current frame.

The system is designed to work directly with Pygame `Surface` objects and is integrated into the `Entity` class.

---

## Features

- Frame-based animations
- Adjustable frame duration
- Play and stop controls
- Animation restarting
- Finite animation loops
- Infinite looping with `LOOP_FOREVER`
- Animation states
- Named animations
- `AnimationManager`
- Multiple animations per entity
- Automatic animation updates through `Entity`

---

## Basic Animation

An animation is created using a list of Pygame `Surface` objects:

```python
from pygame_foundation.animation import Animation

animation = Animation(
    frames=[
        player_image,
        player_image2,
        player_image3
    ],
    frame_duration=0.1
)
```

`frame_duration` is measured in **seconds**.

For example:

```python
frame_duration=0.1
```

changes the animation frame every 0.1 seconds.

---

## Playing an Animation

Animations can be started with `play()`:

```python
animation.play()
```

The animation can be stopped with:

```python
animation.stop()
```

Stopping an animation freezes it at its current frame.

---

## Restarting

`restart()` resets the animation back to its first frame and resets its loop and timing state:

```python
animation.restart()
```

---

## Animation Loops

Animations can be configured to play a limited number of times.

```python
animation = Animation(
    frames,
    frame_duration=0.1,
    loops=5
)
```

The animation will stop after completing its configured loops.

For animations that should continue indefinitely, use `LOOP_FOREVER`:

```python
from pygame_foundation.core.constants import LOOP_FOREVER

animation = Animation(
    frames,
    frame_duration=0.1,
    loops=LOOP_FOREVER
)
```

`LOOP_FOREVER` is the default.

---

## Animation States

The animation system provides `AnimationState`:

```python
from pygame_foundation.animation import AnimationState
```

Available states are:

```python
AnimationState.PLAYING
AnimationState.STOPPED
```

The current state is available through:

```python
animation.playing
```

---

## Animation Manager

`AnimationManager` allows multiple animations to be stored and managed together.

This is useful for entities that have different animations, such as:

```text
Player
├── idle
├── walk
├── run
├── jump
└── attack
```

Create a manager:

```python
from pygame_foundation.animation import AnimationManager

animations = AnimationManager()
```

---

## Creating Animations Through the Manager

Animations can be created and registered directly:

```python
animations.create_animation(
    frames,
    frame_duration=0.1,
    name="idle"
)
```

Multiple animations can be registered:

```python
animations.create_animation(
    idle_frames,
    0.2,
    name="idle"
)

animations.create_animation(
    walk_frames,
    0.1,
    name="walk"
)

animations.create_animation(
    attack_frames,
    0.08,
    name="attack"
)
```

---

## Selecting an Animation

Use `set_animation()` to select an animation by name:

```python
animations.set_animation("walk")
```

The selected animation is available through:

```python
animations.current
```

---

## Entity Integration

Every `Entity` automatically has an `AnimationManager`:

```python
player = Entity(
    x=100,
    y=100
)

player.animations
```

This means an entity can manage its animations without requiring a separate animation object.

For example:

```python
player.animations.create_animation(
    idle_frames,
    0.2,
    name="idle"
)

player.animations.create_animation(
    walk_frames,
    0.1,
    name="walk"
)

player.animations.set_animation("idle")
```

The entity automatically updates its selected animation during its normal update cycle.

When an animation is active, the entity's `image` is updated to the animation's current frame.

---

## Example

A simple animated player can be implemented like this:

```python
import pygame

from pygame_foundation import Game, Entity


game = Game(
    600,
    500,
    "Animation Example",
    60
)

player = Entity(
    x=100,
    y=100
)

idle_frames = [
    pygame.image.load("assets/player_idle_1.png").convert_alpha(),
    pygame.image.load("assets/player_idle_2.png").convert_alpha(),
    pygame.image.load("assets/player_idle_3.png").convert_alpha(),
]

player.animations.create_animation(
    idle_frames,
    frame_duration=0.15,
    name="idle",
    playing=True
)

player.animations.set_animation("idle")

game.world.add(player)

game.run()
```

The `Entity` will automatically update the selected animation and display its current frame.

---

## Multiple Animations

A more complete player could contain several animations:

```python
player.animations.create_animation(
    idle_frames,
    0.2,
    name="idle"
)

player.animations.create_animation(
    walk_frames,
    0.1,
    name="walk"
)

player.animations.create_animation(
    attack_frames,
    0.08,
    loops=1,
    name="attack"
)
```

Then switch between them:

```python
player.animations.set_animation("idle")
```

or:

```python
player.animations.set_animation("walk")
```

or:

```python
player.animations.set_animation("attack")
```

This provides the foundation for more advanced animation systems, such as animation state machines and input-triggered animations.

---

## Future Development

The animation system is intentionally kept separate from input handling.

Future versions may provide features such as:

- Animation input triggers
- Automatic animation switching
- Animation state machines
- Animation callbacks
- More advanced playback controls

These features are not currently part of the animation system.


## Programmer
This package was created by `Arad Rezakhani`. 
