| Name | arcade-actions JSON |
| Version |
0.10.5
JSON |
| download |
| home_page | None |
| Summary | Extension library for Arcade 3.x, providing a high-level way to animate sprites with conditional actions. |
| upload_time | 2025-11-03 03:30:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License Copyright (c) 2025 Brandon Corfman 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. |
| keywords |
actions
animation
arcade
gamedev
sprites
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<table style="border: none; border-collapse: collapse;">
<tr>
<td align="center" style="border: none; padding: 10px; vertical-align: bottom;">
<img src="https://github.com/bcorfman/gif_resources/blob/main/space_clutter.gif?raw=true" style="width: 400px"/>
<br/>
<em style="display: block; width: 400px; text-align: center;">Space Clutter! - A game prototype demonstrating grid formations, wave patterns, and MoveUntil actions</em>
</td>
<td align="center" style="border: none; padding: 10px; vertical-align: bottom;">
<img src="https://github.com/bcorfman/gif_resources/blob/main/laser_gates.gif?raw=true" style="width: 400px"/>
<br/>
<em style="display: block; width: 400px; text-align: center;">A <a href="https://github.com/bcorfman/laser_gates">full game</a> under development, using Actions</em>
<br/>
<img src="https://github.com/bcorfman/gif_resources/blob/main/pattern_demo.gif?raw=true" style="width: 400px"/>
<br/>
<em style="display: block; width: 400px; text-align: center;">Pattern Demo - Showcasing various movement patterns and formation arrangements</em>
</td>
</tr>
</table>
---
# ArcadeActions extension library for Arcade 3.x
[](https://codecov.io/gh/bcorfman/arcade_actions)
[](https://deepwiki.com/bcorfman/arcade_actions)
## 🚀 Quick Appeal
So much of building an arcade game is a cluttered way of saying "animate this sprite until something happens", like colliding with another sprite, reaching a boundary, or an event response. Most of us manage this complexity in the game loop, using low-level movement of game objects and complex chains of `if`-statements. But what if you could write a concise command like "keep moving this sprite, wrap it the other side of the window if it hits a boundary, and raise an event when it collides with another sprite"?
```python
import arcade
from actions import MoveUntil, Action
class AsteroidDemoView(arcade.View):
def __init__(self):
super().__init__()
# Minimal, explicit setup
self.player = arcade.Sprite(":resources:/images/space_shooter/playerShip1_green.png")
self.player.center_x, self.player.center_y = 400, 100
self.asteroids = arcade.SpriteList()
# Position asteroids in a simple pattern with different velocities
positions = [(200, 450), (400, 400), (600, 450)]
velocities = [(3, -2), (-2, -3), (4, -1)]
for (x, y), (vx, vy) in zip(positions, velocities):
rock = arcade.Sprite(":resources:/images/space_shooter/meteorGrey_big1.png")
rock.center_x, rock.center_y = x, y
self.asteroids.append(rock)
# Each asteroid moves independently with its own velocity
MoveUntil(
velocity=(vx, vy),
condition=self.player_asteroid_collision,
on_stop=self.on_player_collision,
bounds=(-64, -64, 864, 664),
boundary_behavior="wrap",
).apply(rock)
def player_asteroid_collision(self):
"""Return data when player hits any asteroid; None to keep moving."""
hits = arcade.check_for_collision_with_list(self.player, self.asteroids)
return {"hits": hits} if hits else None
def on_player_collision(self, data):
"""React to collision."""
print(f"Game over! {len(data['hits'])} asteroid(s) hit the player.")
# ... reset player / end round / etc. ...
def on_update(self, dt):
Action.update_all(dt)
self.player.update()
self.asteroids.update()
def on_draw(self):
self.clear()
self.player.draw()
self.asteroids.draw()
```
This example shows how animation actions can be logically separated from collision responses, making your code simple and appealing.
If writing high-level game code appeals to you ... it's why you chose Python in the first place ... read on!
## 📚 Documentation Overview
### Essential Reading
1. **[API Usage Guide](docs/api_usage_guide.md)** - **START HERE** - Complete guide to using the framework
2. **[Testing Guide](docs/testing_guide.md)** - **Testing patterns and best practices**
3. **[PRD](docs/prd.md)** - Project requirements and architecture decisions
## 🚀 Getting Started
### 🛠️ Installation
**For Library Users:**
```bash
# Basic installation for most games; adjust the commands below depending on your Python package manager.
pip install arcade-actions
# With optional state machine support (platformers/character action games)
pip install arcade-actions[statemachine]
# With state machine diagram generation
pip install arcade-actions[statemachine_diagrams]
```
**For Contributors:**
```bash
# Clone the repository
git clone https://github.com/bcorfman/arcade_actions.git
cd arcade_actions
# Install for development (includes all optional dependencies and dev tools)
make devinstall
# Run tests
make test
# Run linter
make lint
# Format code
make format
```
### Quick Start by Game Type
Simple Arcade Games (no physics):
1. **Read the [API Usage Guide](docs/api_usage_guide.md)** to understand the framework
2. **Study working demos** to see Actions in practice
3. **Start with simple helper functions** (`move_until`, `rotate_until`)
4. **Build up to sequences** for complex behaviors
Platformers / Physics Games:
1. **Install with state machine support**: `uv add arcade-actions[statemachine]` (see Installation section above)
2. **Start with** `examples/pymunk_demo_platformer.py` - reference implementation
3. **Study the patterns**:
- InputState with @dataclass
- DUMB View / SMART State Machine architecture
- Centralized physics in state machine
- `cycle_textures_until` for animations
4. **Follow the architecture guide** (see Decision Matrix below)
## 📖 Documentation Structure
```
docs/
├── README.md # This file - overview and quick start
├── api_usage_guide.md # Complete API usage patterns (START HERE)
├── testing_guide.md # Testing patterns and fixtures
└── prd.md # Requirements and architecture
```
## 🔧 Core Components
### ✅ Implementation
#### Base Action System (actions/base.py)
- **Action** - Core action class with global management
- **Global management** - Automatic action tracking and updates
#### Configuration (actions/config.py)
- **Configurable debug logging**: Fine-grained, level-based diagnostics with per-Action filtering for focused output
- **Debug levels**: Level 0 (off), Level 1 (summary counts), Level 2 (lifecycle events), Level 3+ (verbose per-frame details)
- **Action filtering**: Observe specific action classes or all actions for targeted debugging
- **Environment variables**: `ARCADEACTIONS_DEBUG=2`, `ARCADEACTIONS_DEBUG_ALL=1`, `ARCADEACTIONS_DEBUG_INCLUDE=MoveUntil,CallbackUntil`
- **Programmatic API**: `set_debug_options(level=2, include=["MoveUntil"])` or `observe_actions(MoveUntil, CallbackUntil)` in your app startup
#### Instant Action System (actions/instant.py)
- **MoveBy** - Relative Sprite or SpriteList positioning
- **MoveTo** - Absolute positioning
#### Conditional Actions (actions/conditional.py)
- **MoveUntil** - Velocity-based movement until condition met (optional PyMunk physics integration)
- **FollowPathUntil** - Follow Bezier curve paths with optional automatic sprite rotation (optional PyMunk physics steering with `use_physics=True`)
- **RotateUntil** - Angular velocity rotation (optional PyMunk physics integration)
- **ScaleUntil** - Scale velocity changes
- **FadeUntil** - Alpha velocity changes
- **CycleTexturesUntil** - Cycle through a list of textures at a specific frame rate with simulation time duration support
- **BlinkUntil** - Toggle sprite visibility with optional enter/exit callbacks for collision management
- **CallbackUntil** - Execute callback functions at specified intervals or every frame until condition is met
- **DelayUntil** - Wait for condition to be met
- **TweenUntil** - Direct property animation from start to end value
- **GlowUntil** - Render full-screen Shadertoy effects with camera offset support
- **EmitParticlesUntil** - Manage per-sprite particle emitters with anchor and rotation following
#### Composite Actions (actions/composite.py)
- **Sequential actions** - Run actions one after another (use `sequence()`)
- **Parallel actions** - Run actions in parallel (use `parallel()`)
- **Repeat actions** - Repeat an action indefinitely (use `repeat()`)
#### Boundary Handling (actions/conditional.py)
- **MoveUntil with bounds** - Built-in boundary detection with bounce/wrap behaviors
#### Formation Management (actions/formation.py)
- **Formation functions** - Grid, line, circle, diamond, V-formation, triangle, hexagonal grid, arc, concentric rings, cross, and arrow positioning
- Zero-allocation support: pass `sprites=` to arrange existing sprites without allocating
- Contract: exactly one of `sprites` or creation inputs (`count` or `sprite_factory`) is required
- Grid rule: when `sprites` is provided, `len(sprites)` must equal `rows * cols`
- See `examples/formation_demo.py` for a quick start
#### Movement Patterns (actions/pattern.py)
- **Movement pattern functions** - Zigzag, wave, spiral, figure-8, orbit, bounce, and patrol patterns
- **Condition helpers** - Time-based and sprite count conditions for conditional actions
- See `examples/pattern_demo.py` for a quick start
#### State Machine Integration
ArcadeActions integrates seamlessly with the external [`python-statemachine`](https://github.com/fgmacedo/python-statemachine) library for complex state-driven game logic.
**Complete Example:** See `examples/pymunk_demo_platformer.py` for the reimagined Arcade 3.x implementation showing:
- InputState with @dataclass
- State machine with guard conditions and named events
- Physics force application centralized in state machine
- CycleTexturesUntil for walk/climb animations
- Zero state flags - state machine as single source of truth
**Additional Reference:** The [AmazonWarriors](https://github.com/bcorfman/amazon-warriors) and [Laser Gates](https://github.com/bcorfman/laser-gates) projects demonstrate more complete and advanced patterns.
### ♻️ Zero-Allocation Gameplay (experimental)
ArcadeActions now provides an optional zero-allocation workflow to eliminate per-wave sprite creation.
1) Use the new `SpritePool` (in `actions.pools`) to pre-allocate sprites once at boot:
```python
from actions.pools import SpritePool
from actions import arrange_grid
import arcade
def make_block():
return arcade.Sprite(":resources:images/items/star.png", scale=0.8)
pool = SpritePool(make_block, max_size=300)
blocks = pool.acquire(150) # borrow invisible sprites
arrange_grid(rows=30, cols=5, sprites=blocks, start_x=0, start_y=0) # position only
pool.assign(blocks) # return to pool (hidden & neutral)
```
2) During gameplay, acquire → arrange → release without allocating:
```python
shield = pool.acquire(width * 30)
arrange_grid(rows=30, cols=width, sprites=shield, start_x=WINDOW+50, start_y=TUNNEL_H)
# ... gameplay ...
pool.release(shield)
```
SpritePool API:
- `acquire(n) -> list[Sprite]` — borrow invisible, un-positioned sprites
- `release(iterable[Sprite])` — return sprites to the pool (hidden, detached, reset)
- `assign(iterable[Sprite])` — load externally-created sprites into the pool once
Arrange functions contract:
- Provide exactly one of `sprites` or creation inputs (`count`/`sprite_factory`)
- When using `sprites` with `arrange_grid`, `len(sprites) == rows * cols` is required
#### Easing Effects (actions/easing.py)
- **Ease wrapper** - Apply smooth acceleration/deceleration curves to any conditional action
- **Multiple easing functions** - Built-in ease_in, ease_out, ease_in_out support
- **Custom easing** - Create specialized easing curves and nested easing effects
#### Optional Physics Integration (actions/physics_adapter.py)
- **PyMunk Physics Support** - Optional integration with `arcade.PymunkPhysicsEngine` for physics-driven movement
- **Zero API Changes** - Existing code works unchanged; physics is opt-in via `Action.update_all(dt, physics_engine=engine)`
- **Automatic Kinematic Sync** - **NEW:** Kinematic bodies automatically synced (eliminates manual `set_velocity()` loops)
- **Automatic Routing** - `MoveUntil` and `RotateUntil` automatically use physics when engine is provided
- **Physics-Based Path Following** - `FollowPathUntil` with `use_physics=True` uses steering impulses for natural physics interaction
- **Fallback Behavior** - Actions work normally without a physics engine (direct sprite attribute manipulation)
- **Complete Example** - See `examples/pymunk_demo_platformer.py` for state machine + physics + actions integration
- **See the [API Usage Guide](docs/api_usage_guide.md#optional-physics-integration-arcade-3x--pymunk)** for detailed examples
## 📋 Decision Matrix: When to Use What
### Basic Actions & Composition
| Scenario | Use | Example |
|----------|-----|---------|
| Simple sprite actions | Helper functions | `move_until(sprite, ..., tag="move")` |
| Sprite group actions | Helper functions on SpriteList | `move_until(enemies, ..., tag="formation")` |
| Complex sequences | Direct classes + `sequence()` | `sequence(DelayUntil(...), MoveUntil(...))` |
| Parallel behaviors | Direct classes + `parallel()` | `parallel(MoveUntil(...), RotateUntil(...))` |
| Formation positioning | Formation functions | `arrange_grid(enemies, rows=3, cols=5)` |
| Curved path movement | `follow_path_until` helper | `follow_path_until(sprite, points, ...)` |
| Visibility blinking | `blink_until` helper | `blink_until(sprite, seconds_until_change=0.25, ...)` |
| Periodic callbacks | `callback_until` helper | `callback_until(sprite, callback=fn, condition=cond, seconds_between_calls=0.1)` |
| Shader/particle effects | `callback_until` for temporal control | `callback_until(sprite, lambda: emitter.update(), condition=cond)` |
| Boundary detection | `move_until` with bounds | `move_until(sprite, bounds=b, boundary_behavior="bounce")` |
| Smooth acceleration | `ease()` helper | `ease(sprite, action, duration=2.0)` |
| Property animation | `tween_until` helper | `tween_until(sprite, 0, 100, "center_x", ...)` |
### State Machine Integration
| Scenario | Use | Example/Reference |
|----------|-----|-------------------|
| Character animation states | `python-statemachine` + `cycle_textures_until` | See `examples/pymunk_demo_platformer.py` |
| Input handling | `@dataclass` InputState | Simple fields + computed properties |
| Physics + animation + input | State machine with guards + centralized forces | State machine calls `physics.apply_force()` |
| Walk/climb animations | `cycle_textures_until` in enter callbacks | Start in `on_enter_walk`, stop in `on_exit_walk` |
| Jump physics | Physics in state enter callback | `on_enter_jump` calls `apply_impulse` |
| Complex platformer mechanics | State machine + physics callbacks | `pymunk_moved` triggers state transitions |
### Physics Integration
| Scenario | Use | Pattern |
|----------|-----|---------|
| Kinematic moving platforms | `move_until` + bounce + physics | Automatic kinematic sync (no manual loop) |
| Player with physics forces | State machine + `apply_physics_forces()` | Centralize in state machine method |
| Dynamic sprites | PyMunk with gravity | Use PyMunk directly (masses, collisions) |
| Physics path following | `FollowPathUntil` with `use_physics=True` | Steering impulses for natural movement |
### Architecture Decision Guide
| Your Game Type | Recommended Stack | Rationale |
|----------------|-------------------|-----------|
| Simple arcade (Asteroids, Space Invaders) | ArcadeActions alone | `sequence()`, `move_until`, formations |
| Complex arcade | python-statemachine + ArcadeActions | See full game projects above |
| Complex arcade with physics | python-statemachine + ArcadeActions + PyMunk | See `pymunk_demo_platformer.py` |
| Cutscenes/tutorials | `sequence()` + `parallel()` | Complex multi-step choreography |
### View Architecture Pattern
| Component | Responsibility | Complexity |
|-----------|----------------|------------|
| DUMB View (Window) | Route input, call state machine events | Simple: 2-3 lines per handler |
| SMART State Machine | Guards, transitions, physics forces, animations | Complex: all game logic |
| @dataclass InputState | Hold input data, computed properties | Simple: fields + properties |
| PlayerSprite | Hold textures, forward to state machine | Medium: setup + callbacks |
Raw data
{
"_id": null,
"home_page": null,
"name": "arcade-actions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "actions, animation, arcade, gamedev, sprites",
"author": null,
"author_email": "Brandon Corfman <teacup_canny.5l@icloud.com>",
"download_url": "https://files.pythonhosted.org/packages/47/2e/b9c51ddf76658ca50bdd9e13794cded49452274f7ddfc215695cacd0807e/arcade_actions-0.10.5.tar.gz",
"platform": null,
"description": "<table style=\"border: none; border-collapse: collapse;\">\n<tr>\n<td align=\"center\" style=\"border: none; padding: 10px; vertical-align: bottom;\">\n<img src=\"https://github.com/bcorfman/gif_resources/blob/main/space_clutter.gif?raw=true\" style=\"width: 400px\"/>\n<br/>\n<em style=\"display: block; width: 400px; text-align: center;\">Space Clutter! - A game prototype demonstrating grid formations, wave patterns, and MoveUntil actions</em>\n</td>\n<td align=\"center\" style=\"border: none; padding: 10px; vertical-align: bottom;\">\n<img src=\"https://github.com/bcorfman/gif_resources/blob/main/laser_gates.gif?raw=true\" style=\"width: 400px\"/>\n<br/>\n<em style=\"display: block; width: 400px; text-align: center;\">A <a href=\"https://github.com/bcorfman/laser_gates\">full game</a> under development, using Actions</em>\n<br/>\n<img src=\"https://github.com/bcorfman/gif_resources/blob/main/pattern_demo.gif?raw=true\" style=\"width: 400px\"/>\n<br/>\n<em style=\"display: block; width: 400px; text-align: center;\">Pattern Demo - Showcasing various movement patterns and formation arrangements</em>\n</td>\n</tr>\n</table>\n\n---\n\n# ArcadeActions extension library for Arcade 3.x\n[](https://codecov.io/gh/bcorfman/arcade_actions)\n[](https://deepwiki.com/bcorfman/arcade_actions)\n\n## \ud83d\ude80 Quick Appeal\n\nSo much of building an arcade game is a cluttered way of saying \"animate this sprite until something happens\", like colliding with another sprite, reaching a boundary, or an event response. Most of us manage this complexity in the game loop, using low-level movement of game objects and complex chains of `if`-statements. But what if you could write a concise command like \"keep moving this sprite, wrap it the other side of the window if it hits a boundary, and raise an event when it collides with another sprite\"? \n\n```python \nimport arcade\nfrom actions import MoveUntil, Action\n\nclass AsteroidDemoView(arcade.View):\n def __init__(self):\n super().__init__()\n # Minimal, explicit setup\n self.player = arcade.Sprite(\":resources:/images/space_shooter/playerShip1_green.png\")\n self.player.center_x, self.player.center_y = 400, 100\n\n self.asteroids = arcade.SpriteList()\n # Position asteroids in a simple pattern with different velocities\n positions = [(200, 450), (400, 400), (600, 450)]\n velocities = [(3, -2), (-2, -3), (4, -1)]\n \n for (x, y), (vx, vy) in zip(positions, velocities):\n rock = arcade.Sprite(\":resources:/images/space_shooter/meteorGrey_big1.png\")\n rock.center_x, rock.center_y = x, y\n self.asteroids.append(rock)\n \n # Each asteroid moves independently with its own velocity\n MoveUntil(\n velocity=(vx, vy),\n condition=self.player_asteroid_collision,\n on_stop=self.on_player_collision,\n bounds=(-64, -64, 864, 664),\n boundary_behavior=\"wrap\",\n ).apply(rock)\n\n def player_asteroid_collision(self):\n \"\"\"Return data when player hits any asteroid; None to keep moving.\"\"\"\n hits = arcade.check_for_collision_with_list(self.player, self.asteroids)\n return {\"hits\": hits} if hits else None\n\n def on_player_collision(self, data):\n \"\"\"React to collision.\"\"\"\n print(f\"Game over! {len(data['hits'])} asteroid(s) hit the player.\")\n # ... reset player / end round / etc. ...\n\n def on_update(self, dt):\n Action.update_all(dt)\n self.player.update()\n self.asteroids.update()\n\n def on_draw(self):\n self.clear()\n self.player.draw()\n self.asteroids.draw()\n```\nThis example shows how animation actions can be logically separated from collision responses, making your code simple and appealing. \nIf writing high-level game code appeals to you ... it's why you chose Python in the first place ... read on!\n\n## \ud83d\udcda Documentation Overview\n\n### Essential Reading\n1. **[API Usage Guide](docs/api_usage_guide.md)** - **START HERE** - Complete guide to using the framework\n2. **[Testing Guide](docs/testing_guide.md)** - **Testing patterns and best practices**\n3. **[PRD](docs/prd.md)** - Project requirements and architecture decisions\n\n\n## \ud83d\ude80 Getting Started\n\n### \ud83d\udee0\ufe0f Installation\n\n**For Library Users:**\n```bash\n# Basic installation for most games; adjust the commands below depending on your Python package manager. \npip install arcade-actions\n\n# With optional state machine support (platformers/character action games)\npip install arcade-actions[statemachine]\n\n# With state machine diagram generation \npip install arcade-actions[statemachine_diagrams]\n```\n**For Contributors:**\n```bash\n# Clone the repository\ngit clone https://github.com/bcorfman/arcade_actions.git\ncd arcade_actions\n\n# Install for development (includes all optional dependencies and dev tools)\nmake devinstall\n\n# Run tests\nmake test\n\n# Run linter\nmake lint\n\n# Format code\nmake format\n```\n\n### Quick Start by Game Type\n\nSimple Arcade Games (no physics):\n1. **Read the [API Usage Guide](docs/api_usage_guide.md)** to understand the framework\n2. **Study working demos** to see Actions in practice\n3. **Start with simple helper functions** (`move_until`, `rotate_until`)\n4. **Build up to sequences** for complex behaviors\n\nPlatformers / Physics Games:\n1. **Install with state machine support**: `uv add arcade-actions[statemachine]` (see Installation section above)\n2. **Start with** `examples/pymunk_demo_platformer.py` - reference implementation\n3. **Study the patterns**:\n - InputState with @dataclass\n - DUMB View / SMART State Machine architecture\n - Centralized physics in state machine\n - `cycle_textures_until` for animations\n4. **Follow the architecture guide** (see Decision Matrix below)\n\n## \ud83d\udcd6 Documentation Structure\n\n```\ndocs/\n\u251c\u2500\u2500 README.md # This file - overview and quick start\n\u251c\u2500\u2500 api_usage_guide.md # Complete API usage patterns (START HERE)\n\u251c\u2500\u2500 testing_guide.md # Testing patterns and fixtures\n\u2514\u2500\u2500 prd.md # Requirements and architecture\n```\n\n## \ud83d\udd27 Core Components\n\n### \u2705 Implementation\n\n#### Base Action System (actions/base.py)\n- **Action** - Core action class with global management\n- **Global management** - Automatic action tracking and updates\n\n#### Configuration (actions/config.py)\n- **Configurable debug logging**: Fine-grained, level-based diagnostics with per-Action filtering for focused output\n- **Debug levels**: Level 0 (off), Level 1 (summary counts), Level 2 (lifecycle events), Level 3+ (verbose per-frame details)\n- **Action filtering**: Observe specific action classes or all actions for targeted debugging\n- **Environment variables**: `ARCADEACTIONS_DEBUG=2`, `ARCADEACTIONS_DEBUG_ALL=1`, `ARCADEACTIONS_DEBUG_INCLUDE=MoveUntil,CallbackUntil`\n- **Programmatic API**: `set_debug_options(level=2, include=[\"MoveUntil\"])` or `observe_actions(MoveUntil, CallbackUntil)` in your app startup\n\n#### Instant Action System (actions/instant.py)\n- **MoveBy** - Relative Sprite or SpriteList positioning\n- **MoveTo** - Absolute positioning\n\n#### Conditional Actions (actions/conditional.py)\n- **MoveUntil** - Velocity-based movement until condition met (optional PyMunk physics integration)\n- **FollowPathUntil** - Follow Bezier curve paths with optional automatic sprite rotation (optional PyMunk physics steering with `use_physics=True`)\n- **RotateUntil** - Angular velocity rotation (optional PyMunk physics integration)\n- **ScaleUntil** - Scale velocity changes \n- **FadeUntil** - Alpha velocity changes\n- **CycleTexturesUntil** - Cycle through a list of textures at a specific frame rate with simulation time duration support\n- **BlinkUntil** - Toggle sprite visibility with optional enter/exit callbacks for collision management\n- **CallbackUntil** - Execute callback functions at specified intervals or every frame until condition is met\n- **DelayUntil** - Wait for condition to be met\n- **TweenUntil** - Direct property animation from start to end value\n- **GlowUntil** - Render full-screen Shadertoy effects with camera offset support\n- **EmitParticlesUntil** - Manage per-sprite particle emitters with anchor and rotation following\n\n#### Composite Actions (actions/composite.py)\n- **Sequential actions** - Run actions one after another (use `sequence()`)\n- **Parallel actions** - Run actions in parallel (use `parallel()`)\n- **Repeat actions** - Repeat an action indefinitely (use `repeat()`)\n\n#### Boundary Handling (actions/conditional.py)\n- **MoveUntil with bounds** - Built-in boundary detection with bounce/wrap behaviors\n\n#### Formation Management (actions/formation.py)\n- **Formation functions** - Grid, line, circle, diamond, V-formation, triangle, hexagonal grid, arc, concentric rings, cross, and arrow positioning\n - Zero-allocation support: pass `sprites=` to arrange existing sprites without allocating\n - Contract: exactly one of `sprites` or creation inputs (`count` or `sprite_factory`) is required\n - Grid rule: when `sprites` is provided, `len(sprites)` must equal `rows * cols`\n - See `examples/formation_demo.py` for a quick start\n\n#### Movement Patterns (actions/pattern.py)\n- **Movement pattern functions** - Zigzag, wave, spiral, figure-8, orbit, bounce, and patrol patterns\n- **Condition helpers** - Time-based and sprite count conditions for conditional actions\n- See `examples/pattern_demo.py` for a quick start\n\n#### State Machine Integration\nArcadeActions integrates seamlessly with the external [`python-statemachine`](https://github.com/fgmacedo/python-statemachine) library for complex state-driven game logic.\n\n**Complete Example:** See `examples/pymunk_demo_platformer.py` for the reimagined Arcade 3.x implementation showing:\n- InputState with @dataclass\n- State machine with guard conditions and named events\n- Physics force application centralized in state machine\n- CycleTexturesUntil for walk/climb animations\n- Zero state flags - state machine as single source of truth\n\n**Additional Reference:** The [AmazonWarriors](https://github.com/bcorfman/amazon-warriors) and [Laser Gates](https://github.com/bcorfman/laser-gates) projects demonstrate more complete and advanced patterns.\n\n### \u267b\ufe0f Zero-Allocation Gameplay (experimental)\n\nArcadeActions now provides an optional zero-allocation workflow to eliminate per-wave sprite creation.\n\n1) Use the new `SpritePool` (in `actions.pools`) to pre-allocate sprites once at boot:\n\n```python\nfrom actions.pools import SpritePool\nfrom actions import arrange_grid\nimport arcade\n\ndef make_block():\n return arcade.Sprite(\":resources:images/items/star.png\", scale=0.8)\n\npool = SpritePool(make_block, max_size=300)\nblocks = pool.acquire(150) # borrow invisible sprites\narrange_grid(rows=30, cols=5, sprites=blocks, start_x=0, start_y=0) # position only\npool.assign(blocks) # return to pool (hidden & neutral)\n```\n\n2) During gameplay, acquire \u2192 arrange \u2192 release without allocating:\n\n```python\nshield = pool.acquire(width * 30)\narrange_grid(rows=30, cols=width, sprites=shield, start_x=WINDOW+50, start_y=TUNNEL_H)\n# ... gameplay ...\npool.release(shield)\n```\n\nSpritePool API:\n- `acquire(n) -> list[Sprite]` \u2014 borrow invisible, un-positioned sprites\n- `release(iterable[Sprite])` \u2014 return sprites to the pool (hidden, detached, reset)\n- `assign(iterable[Sprite])` \u2014 load externally-created sprites into the pool once\n\nArrange functions contract:\n- Provide exactly one of `sprites` or creation inputs (`count`/`sprite_factory`)\n- When using `sprites` with `arrange_grid`, `len(sprites) == rows * cols` is required\n\n\n#### Easing Effects (actions/easing.py)\n- **Ease wrapper** - Apply smooth acceleration/deceleration curves to any conditional action\n- **Multiple easing functions** - Built-in ease_in, ease_out, ease_in_out support\n- **Custom easing** - Create specialized easing curves and nested easing effects\n\n#### Optional Physics Integration (actions/physics_adapter.py)\n- **PyMunk Physics Support** - Optional integration with `arcade.PymunkPhysicsEngine` for physics-driven movement\n- **Zero API Changes** - Existing code works unchanged; physics is opt-in via `Action.update_all(dt, physics_engine=engine)`\n- **Automatic Kinematic Sync** - **NEW:** Kinematic bodies automatically synced (eliminates manual `set_velocity()` loops)\n- **Automatic Routing** - `MoveUntil` and `RotateUntil` automatically use physics when engine is provided\n- **Physics-Based Path Following** - `FollowPathUntil` with `use_physics=True` uses steering impulses for natural physics interaction\n- **Fallback Behavior** - Actions work normally without a physics engine (direct sprite attribute manipulation)\n- **Complete Example** - See `examples/pymunk_demo_platformer.py` for state machine + physics + actions integration\n- **See the [API Usage Guide](docs/api_usage_guide.md#optional-physics-integration-arcade-3x--pymunk)** for detailed examples\n\n## \ud83d\udccb Decision Matrix: When to Use What\n\n### Basic Actions & Composition\n\n| Scenario | Use | Example |\n|----------|-----|---------|\n| Simple sprite actions | Helper functions | `move_until(sprite, ..., tag=\"move\")` |\n| Sprite group actions | Helper functions on SpriteList | `move_until(enemies, ..., tag=\"formation\")` |\n| Complex sequences | Direct classes + `sequence()` | `sequence(DelayUntil(...), MoveUntil(...))` |\n| Parallel behaviors | Direct classes + `parallel()` | `parallel(MoveUntil(...), RotateUntil(...))` |\n| Formation positioning | Formation functions | `arrange_grid(enemies, rows=3, cols=5)` |\n| Curved path movement | `follow_path_until` helper | `follow_path_until(sprite, points, ...)` |\n| Visibility blinking | `blink_until` helper | `blink_until(sprite, seconds_until_change=0.25, ...)` |\n| Periodic callbacks | `callback_until` helper | `callback_until(sprite, callback=fn, condition=cond, seconds_between_calls=0.1)` |\n| Shader/particle effects | `callback_until` for temporal control | `callback_until(sprite, lambda: emitter.update(), condition=cond)` |\n| Boundary detection | `move_until` with bounds | `move_until(sprite, bounds=b, boundary_behavior=\"bounce\")` |\n| Smooth acceleration | `ease()` helper | `ease(sprite, action, duration=2.0)` |\n| Property animation | `tween_until` helper | `tween_until(sprite, 0, 100, \"center_x\", ...)` |\n\n### State Machine Integration\n\n| Scenario | Use | Example/Reference |\n|----------|-----|-------------------|\n| Character animation states | `python-statemachine` + `cycle_textures_until` | See `examples/pymunk_demo_platformer.py` |\n| Input handling | `@dataclass` InputState | Simple fields + computed properties |\n| Physics + animation + input | State machine with guards + centralized forces | State machine calls `physics.apply_force()` |\n| Walk/climb animations | `cycle_textures_until` in enter callbacks | Start in `on_enter_walk`, stop in `on_exit_walk` |\n| Jump physics | Physics in state enter callback | `on_enter_jump` calls `apply_impulse` |\n| Complex platformer mechanics | State machine + physics callbacks | `pymunk_moved` triggers state transitions |\n\n### Physics Integration\n\n| Scenario | Use | Pattern |\n|----------|-----|---------|\n| Kinematic moving platforms | `move_until` + bounce + physics | Automatic kinematic sync (no manual loop) |\n| Player with physics forces | State machine + `apply_physics_forces()` | Centralize in state machine method |\n| Dynamic sprites | PyMunk with gravity | Use PyMunk directly (masses, collisions) |\n| Physics path following | `FollowPathUntil` with `use_physics=True` | Steering impulses for natural movement |\n\n### Architecture Decision Guide\n\n| Your Game Type | Recommended Stack | Rationale |\n|----------------|-------------------|-----------|\n| Simple arcade (Asteroids, Space Invaders) | ArcadeActions alone | `sequence()`, `move_until`, formations |\n| Complex arcade | python-statemachine + ArcadeActions | See full game projects above |\n| Complex arcade with physics | python-statemachine + ArcadeActions + PyMunk | See `pymunk_demo_platformer.py` |\n| Cutscenes/tutorials | `sequence()` + `parallel()` | Complex multi-step choreography |\n\n### View Architecture Pattern\n\n| Component | Responsibility | Complexity |\n|-----------|----------------|------------|\n| DUMB View (Window) | Route input, call state machine events | Simple: 2-3 lines per handler |\n| SMART State Machine | Guards, transitions, physics forces, animations | Complex: all game logic |\n| @dataclass InputState | Hold input data, computed properties | Simple: fields + properties |\n| PlayerSprite | Hold textures, forward to state machine | Medium: setup + callbacks |\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2025 Brandon Corfman 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.",
"summary": "Extension library for Arcade 3.x, providing a high-level way to animate sprites with conditional actions.",
"version": "0.10.5",
"project_urls": {
"Documentation": "https://deepwiki.com/bcorfman/arcade_actions",
"Homepage": "https://github.com/bcorfman/arcade_actions",
"Issues": "https://github.com/bcorfman/arcade_actions/issues",
"Repository": "https://github.com/bcorfman/arcade_actions"
},
"split_keywords": [
"actions",
" animation",
" arcade",
" gamedev",
" sprites"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a7deb7be3ea335f368a9de665c924d7c449cac00cd36ca8598cb946b60e1af27",
"md5": "6e8f7f9a8c7331a782619ef1f1f220a7",
"sha256": "6ef0fd9f6a59645cd398ecdca581fbff7177b0e656016bb7b1c009e378e90ecb"
},
"downloads": -1,
"filename": "arcade_actions-0.10.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6e8f7f9a8c7331a782619ef1f1f220a7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 73969,
"upload_time": "2025-11-03T03:30:22",
"upload_time_iso_8601": "2025-11-03T03:30:22.054255Z",
"url": "https://files.pythonhosted.org/packages/a7/de/b7be3ea335f368a9de665c924d7c449cac00cd36ca8598cb946b60e1af27/arcade_actions-0.10.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "472eb9c51ddf76658ca50bdd9e13794cded49452274f7ddfc215695cacd0807e",
"md5": "700df04a297f131e603fe0125afe70cf",
"sha256": "48261c0a5432e5ecf4e9afc3c1877ac1d3030e75b68b54f6d3837f30df5c18fa"
},
"downloads": -1,
"filename": "arcade_actions-0.10.5.tar.gz",
"has_sig": false,
"md5_digest": "700df04a297f131e603fe0125afe70cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 471329,
"upload_time": "2025-11-03T03:30:23",
"upload_time_iso_8601": "2025-11-03T03:30:23.710685Z",
"url": "https://files.pythonhosted.org/packages/47/2e/b9c51ddf76658ca50bdd9e13794cded49452274f7ddfc215695cacd0807e/arcade_actions-0.10.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-03 03:30:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bcorfman",
"github_project": "arcade_actions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "arcade-actions"
}
