| Name | arcade-actions JSON |
| Version |
0.5.1
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-08-19 11:19:57 |
| 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.
|
<img src="https://github.com/bcorfman/gif_resources/blob/main/space_clutter.gif?raw=true"/>
*Space Clutter!, a game prototype demonstrating grid formations, wave patterns, and MoveUntil actions.*
---
# 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
1. **Read the [API Usage Guide](api_usage_guide.md)** to understand the framework
2. **Study the working demos in the examples directory** to understand the power of Actions
3. **Start with simple conditional actions** and build up to complex compositions
4. **Use formation and pattern functions** for organizing sprite positions and layouts
## 📖 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
- **CompositeAction** - Base for sequential and parallel actions
- **Global management** - Automatic action tracking and updates
- **Composition helpers** - `sequence()` and `parallel()` functions
#### 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
- **FollowPathUntil** - Follow Bezier curve paths with optional automatic sprite rotation
- **RotateUntil** - Angular velocity rotation
- **ScaleUntil** - Scale velocity changes
- **FadeUntil** - Alpha velocity changes
- **DelayUntil** - Wait for condition to be met
- **TweenUntil** - Direct property animation from start to end value
#### Composite Actions (actions/composite.py)
- **Sequential actions** - Run actions one after another (use `sequence()`)
- **Parallel actions** - Run actions in parallel (use `parallel()`)
#### 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
#### 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
#### 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
## 📋 Decision Matrix
| 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(...))` |
| Instant actions | Position initialization in a sequence | sequence(MoveBy(...), MoveUntil(...)) |
| Formation positioning | Formation functions | `arrange_grid(enemies, rows=3, cols=5)` |
| Curved path movement | `follow_path_until` helper | `follow_path_until(sprite, points, ...)` |
| Boundary detection | `move_until` with bounds | `move_until(sprite, ..., bounds=bounds, boundary_behavior="bounce")` |
| Smooth acceleration | `ease()` helper | `ease(sprite, action, ...)` |
| Complex curved movement | `ease()` + `follow_path_until` | `ease(sprite, follow_path_until(...), ...)` |
| Property animation | `tween_until` helper | `tween_until(sprite, 0, 100, "center_x", ...)` |
| Standard sprites (no actions) | arcade.Sprite + arcade.SpriteList | Regular Arcade usage |
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/c4/78/6e276a4bbae0b09a5ab8c819d1399f7f2e0e8e7e463b3f029940b4bf298b/arcade_actions-0.5.1.tar.gz",
"platform": null,
"description": "<img src=\"https://github.com/bcorfman/gif_resources/blob/main/space_clutter.gif?raw=true\"/>\n\n*Space Clutter!, a game prototype demonstrating grid formations, wave patterns, and MoveUntil actions.*\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\n1. **Read the [API Usage Guide](api_usage_guide.md)** to understand the framework\n2. **Study the working demos in the examples directory** to understand the power of Actions\n3. **Start with simple conditional actions** and build up to complex compositions\n4. **Use formation and pattern functions** for organizing sprite positions and layouts\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- **CompositeAction** - Base for sequential and parallel actions\n- **Global management** - Automatic action tracking and updates\n- **Composition helpers** - `sequence()` and `parallel()` functions\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\n- **FollowPathUntil** - Follow Bezier curve paths with optional automatic sprite rotation\n- **RotateUntil** - Angular velocity rotation\n- **ScaleUntil** - Scale velocity changes \n- **FadeUntil** - Alpha velocity changes\n- **DelayUntil** - Wait for condition to be met\n- **TweenUntil** - Direct property animation from start to end value\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\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\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\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## \ud83d\udccb Decision Matrix\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| Instant actions | Position initialization in a sequence | sequence(MoveBy(...), MoveUntil(...)) |\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| Boundary detection | `move_until` with bounds | `move_until(sprite, ..., bounds=bounds, boundary_behavior=\"bounce\")` |\n| Smooth acceleration | `ease()` helper | `ease(sprite, action, ...)` |\n| Complex curved movement | `ease()` + `follow_path_until` | `ease(sprite, follow_path_until(...), ...)` |\n| Property animation | `tween_until` helper | `tween_until(sprite, 0, 100, \"center_x\", ...)` |\n| Standard sprites (no actions) | arcade.Sprite + arcade.SpriteList | Regular Arcade usage |\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.5.1",
"project_urls": {
"Documentation": "https://github.com/bcorfman/arcade_actions/blob/main/docs/",
"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": "12e5af6efc5f8e30462b31bfda5cf492a2669f28c256d0d5e592b09df668a388",
"md5": "63af1f6e78f1f3b9d75085becf4bd595",
"sha256": "79e056fa5dc7b79374b9b236f7ee1a64d7385a1162eedf549437f7367078d295"
},
"downloads": -1,
"filename": "arcade_actions-0.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "63af1f6e78f1f3b9d75085becf4bd595",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 47129,
"upload_time": "2025-08-19T11:19:55",
"upload_time_iso_8601": "2025-08-19T11:19:55.738475Z",
"url": "https://files.pythonhosted.org/packages/12/e5/af6efc5f8e30462b31bfda5cf492a2669f28c256d0d5e592b09df668a388/arcade_actions-0.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c4786e276a4bbae0b09a5ab8c819d1399f7f2e0e8e7e463b3f029940b4bf298b",
"md5": "12c133dd3d2f5ef9f38c4f8ddf3760c9",
"sha256": "7376529fc4e0fcb44f14ebc14d72c7473ec82f1c7ead145a903e59ad1b356fdd"
},
"downloads": -1,
"filename": "arcade_actions-0.5.1.tar.gz",
"has_sig": false,
"md5_digest": "12c133dd3d2f5ef9f38c4f8ddf3760c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 952385,
"upload_time": "2025-08-19T11:19:57",
"upload_time_iso_8601": "2025-08-19T11:19:57.102069Z",
"url": "https://files.pythonhosted.org/packages/c4/78/6e276a4bbae0b09a5ab8c819d1399f7f2e0e8e7e463b3f029940b4bf298b/arcade_actions-0.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 11:19:57",
"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"
}
