{"id":15018028,"url":"https://github.com/hikikones/bevy-sequential-actions","last_synced_at":"2025-04-07T05:13:15.311Z","repository":{"id":40306636,"uuid":"486304401","full_name":"hikikones/bevy-sequential-actions","owner":"hikikones","description":"A Bevy library for executing various actions in a sequence.","archived":false,"fork":false,"pushed_at":"2024-10-29T09:09:04.000Z","size":394,"stargazers_count":36,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-29T09:36:14.644Z","etag":null,"topics":["bevy","bevy-engine","bevy-plugin","ecs","game-development","gamedev","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/bevy-sequential-actions","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hikikones.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-27T18:17:16.000Z","updated_at":"2024-10-23T02:53:26.000Z","dependencies_parsed_at":"2023-10-28T01:22:30.710Z","dependency_job_id":"61f5c53c-8de0-45b2-b674-e849c9ffbd36","html_url":"https://github.com/hikikones/bevy-sequential-actions","commit_stats":{"total_commits":95,"total_committers":2,"mean_commits":47.5,"dds":"0.010526315789473717","last_synced_commit":"68fe508c46b4bf619075188d75bc8e927e2c4b83"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikikones%2Fbevy-sequential-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikikones%2Fbevy-sequential-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikikones%2Fbevy-sequential-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hikikones%2Fbevy-sequential-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hikikones","download_url":"https://codeload.github.com/hikikones/bevy-sequential-actions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595335,"owners_count":20963943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bevy","bevy-engine","bevy-plugin","ecs","game-development","gamedev","rust"],"created_at":"2024-09-24T19:51:20.212Z","updated_at":"2025-04-07T05:13:15.278Z","avatar_url":"https://github.com/hikikones.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Bevy Sequential Actions\n\n[![crates.io](https://img.shields.io/crates/v/bevy-sequential-actions?style=flat-square)](https://crates.io/crates/bevy-sequential-actions)\n[![docs.rs](https://img.shields.io/docsrs/bevy-sequential-actions?style=flat-square)](https://docs.rs/bevy_sequential_actions)\n[![MIT/Apache 2.0](https://img.shields.io/crates/l/bevy-sequential-actions?style=flat-square)](https://github.com/hikikones/bevy-sequential-actions#license)\n\n\nA simple library for managing and sequencing various actions in [Bevy](https://bevyengine.org).\n\n\u003cfigure\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/66b5b15e-96af-47bd-9371-eee8809d1294\"/\u003e\n    \u003cp\u003e\u003cem\u003eAn entity with a queue of repeating actions\u003c/em\u003e\u003c/p\u003e\n\u003c/figure\u003e\n\n\u003c/div\u003e\n\n## 📜 Getting Started\n\n#### Plugin\n\nThe quickest way for getting started is adding the `SequentialActionsPlugin` to your `App`.\n\n```rust\nuse bevy_sequential_actions::*;\n\nfn main() {\n    App::new()\n        .add_plugins((DefaultPlugins, SequentialActionsPlugin))\n        .run();\n}\n```\n\n#### Implementing an Action\n\nAn action is anything that implements the `Action` trait.\nThe trait contains various methods that together defines the _lifecycle_ of an action.\nFrom this, you can create any action that can last as long as you like,\nand do as much as you like.\n\nAn entity with actions is referred to as an `agent`.\n\nA simple wait action follows.\n\n```rust\npub struct WaitAction {\n    duration: f32, // Seconds\n    current: Option\u003cf32\u003e, // None\n}\n\nimpl Action for WaitAction {\n    // By default, this method is called every frame in the Last schedule.\n    fn is_finished(\u0026self, agent: Entity, world: \u0026World) -\u003e bool {\n        // Determine if wait timer has reached zero.\n        world.get::\u003cWaitTimer\u003e(agent).unwrap().0 \u003c= 0.0\n    }\n\n    // This method is called when an action is started.\n    fn on_start(\u0026mut self, agent: Entity, world: \u0026mut World) -\u003e bool {\n        // Take current time (if paused), or use full duration.\n        let duration = self.current.take().unwrap_or(self.duration);\n\n        // Run the wait timer system on the agent.\n        world.entity_mut(agent).insert(WaitTimer(duration));\n\n        // Is action already finished?\n        // Returning true here will immediately advance the action queue.\n        self.is_finished(agent, world)\n    }\n\n    // This method is called when an action is stopped.\n    fn on_stop(\u0026mut self, agent: Option\u003cEntity\u003e, world: \u0026mut World, reason: StopReason) {\n        // Do nothing if agent has been despawned.\n        let Some(agent) = agent else { return };\n\n        // Take the wait timer component from the agent.\n        let wait_timer = world.entity_mut(agent).take::\u003cWaitTimer\u003e();\n\n        // Store current time when paused.\n        if reason == StopReason::Paused {\n            self.current = Some(wait_timer.unwrap().0);\n        }\n    }\n\n    // Optional. This method is called when an action is added to the queue.\n    fn on_add(\u0026mut self, agent: Entity, world: \u0026mut World) {}\n\n    // Optional. This method is called when an action is removed from the queue.\n    fn on_remove(\u0026mut self, agent: Option\u003cEntity\u003e, world: \u0026mut World) {}\n\n    // Optional. The last method that is called with full ownership.\n    fn on_drop(self: Box\u003cSelf\u003e, agent: Option\u003cEntity\u003e, world: \u0026mut World, reason: DropReason) {}\n}\n\n#[derive(Component)]\nstruct WaitTimer(f32);\n\nfn wait_system(mut wait_timer_q: Query\u003c\u0026mut WaitTimer\u003e, time: Res\u003cTime\u003e) {\n    for mut wait_timer in \u0026mut wait_timer_q {\n        wait_timer.0 -= time.delta_seconds();\n    }\n}\n```\n\n#### Modifying Actions\n\nActions can be added to any `Entity` with the `SequentialActions` marker component.\nAdding and modifying actions is done through the `actions(agent)`\nextension method implemented for both `Commands` and `World`.\nSee the `ModifyActions` trait for available methods.\n\n```rust\nfn setup(mut commands: Commands) {\n    // Spawn entity with the marker component\n    let agent = commands.spawn(SequentialActions).id();\n    commands\n        .actions(agent)\n        // Add a single action\n        .add(action_a)\n        // Add more actions with a tuple\n        .add((action_b, action_c))\n        // Add a collection of actions\n        .add(actions![\n            action_d,\n            action_e,\n            action_f,\n        ])\n        // Add an anonymous action with a closure\n        .add(|_agent, world: \u0026mut World| -\u003e bool {\n            // on_start\n            world.send_event(AppExit::Success);\n            true\n        });\n}\n```\n\n#### ⚠️ Warning\n\nSince you are given a mutable `World`, you can in practice do _anything_.\nDepending on what you do, the logic for advancing the action queue might not work properly.\nThere are a few things you should keep in mind:\n\n* If you want to despawn an `agent` as an action, this should be done in `on_start`.\n* The `execute` and `next` methods should not be used,\n    as that will immediately advance the action queue while inside any of the trait methods.\n    Instead, you should return `true` in `on_start`.\n* When adding new actions, you should set the `start` property to `false`.\n    Otherwise, you will effectively call `execute` which, again, should not be used.\n    At worst, you will cause a **stack overflow** if the action adds itself.\n\n    ```rust,no_run\n        fn on_start(\u0026mut self, agent: Entity, world: \u0026mut World) -\u003e bool {\n            world\n                .actions(agent)\n                .start(false) // Do not start next action\n                .add((action_a, action_b, action_c));\n\n            // Immediately advance the action queue\n            true\n        }\n    ```\n\n## 📎 Examples\n\nSee the [examples](examples/) for more usage.\nEach example can be run with `cargo run --example \u003cexample\u003e`.\n\n| Example | Description |\n| ------- | ----------- |\n| `basic` | Basic usage of the library. |\n| `pause` | Pause and resume an action. |\n| `repeat` | Create an action that repeats. |\n| `parallel` | Create actions that run in parallel. |\n| `sequence` | Create action with a sequence of actions. |\n| `custom` | Custom plugin with different schedules and action queue advancement. |\n\n## 📌 Compatibility\n\n| bevy | bevy-sequential-actions |\n| ---- | ----------------------- |\n| 0.15 | 0.12                    |\n| 0.14 | 0.11                    |\n| 0.13 | 0.10                    |\n| 0.12 | 0.9                     |\n| 0.11 | 0.8                     |\n| 0.10 | 0.7                     |\n| 0.9  | 0.6                     |\n| 0.8  | 0.3 – 0.5               |\n| 0.7  | 0.1 – 0.2               |\n\n## 🔖 License\n\n`bevy-sequential-actions` is dual-licensed under either\n\n* MIT License ([LICENSE-MIT](LICENSE-MIT) or [http://opensource.org/licenses/MIT](http://opensource.org/licenses/MIT))\n* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0))\n\nat your option.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhikikones%2Fbevy-sequential-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhikikones%2Fbevy-sequential-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhikikones%2Fbevy-sequential-actions/lists"}