{"id":15749746,"url":"https://github.com/jarkonik/bevy_scriptum","last_synced_at":"2025-04-09T09:07:34.291Z","repository":{"id":177891190,"uuid":"653683037","full_name":"jarkonik/bevy_scriptum","owner":"jarkonik","description":"📜 A plugin for Bevy that allows you to write some of your game logic in a scripting language.","archived":false,"fork":false,"pushed_at":"2024-07-28T05:09:33.000Z","size":5023,"stargazers_count":97,"open_issues_count":12,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-02T02:24:03.062Z","etag":null,"topics":["bevy","bevy-engine","bevy-plugin","game","game-development","gamedev","plugin","script","scripting","scripts"],"latest_commit_sha":null,"homepage":"https://jarkonik.github.io/bevy_scriptum/","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/jarkonik.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE-APACHE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["jarkonik"]}},"created_at":"2023-06-14T14:15:27.000Z","updated_at":"2025-03-29T01:37:58.000Z","dependencies_parsed_at":"2024-07-05T16:49:26.673Z","dependency_job_id":"445d714e-7a7c-4dad-b14b-3445433ac4eb","html_url":"https://github.com/jarkonik/bevy_scriptum","commit_stats":null,"previous_names":["jarkonik/bevy_scriptum"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarkonik%2Fbevy_scriptum","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarkonik%2Fbevy_scriptum/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarkonik%2Fbevy_scriptum/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jarkonik%2Fbevy_scriptum/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jarkonik","download_url":"https://codeload.github.com/jarkonik/bevy_scriptum/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"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","game","game-development","gamedev","plugin","script","scripting","scripts"],"created_at":"2024-10-04T06:04:47.467Z","updated_at":"2025-04-09T09:07:34.270Z","avatar_url":"https://github.com/jarkonik.png","language":"Rust","funding_links":["https://github.com/sponsors/jarkonik"],"categories":[],"sub_categories":[],"readme":"# bevy_scriptum 📜\n\nbevy_scriptum is a a plugin for [Bevy](https://bevyengine.org/) that allows you to write some of your game logic in a scripting language.\nCurrently [Rhai](https://rhai.rs/) and [Lua](https://lua.org/) are supported, but more languages may be added in the future.\n\nEverything you need to know to get started with using this library is contained in the\n[bevy_scriptum book](https://jarkonik.github.io/bevy_scriptum/)\n\nAPI docs are available in [docs.rs](https://docs.rs/bevy_scriptum/latest/bevy_scriptum/)\n\nbevy_scriptum's main advantages include:\n- low-boilerplate\n- easy to use\n- asynchronicity with a promise-based API\n- flexibility\n- hot-reloading\n\nScripts are separate files that can be hot-reloaded at runtime. This allows you to quickly iterate on your game logic without having to recompile your game.\n\nAll you need to do is register callbacks on your Bevy app like this:\n```rust\nuse bevy::prelude::*;\nuse bevy_scriptum::prelude::*;\nuse bevy_scriptum::runtimes::lua::prelude::*;\n\nApp::new()\n    .add_plugins(DefaultPlugins)\n    .add_scripting::\u003cLuaRuntime\u003e(|runtime| {\n         runtime.add_function(String::from(\"hello_bevy\"), || {\n           println!(\"hello bevy, called from script\");\n         });\n    })\n    .run();\n```\nAnd you can call them in your scripts like this:\n```lua\nhello_bevy()\n```\n\nEvery callback function that you expose to the scripting language is also a Bevy system, so you can easily query and mutate ECS components and resources just like you would in a regular Bevy system:\n\n```rust\nuse bevy::prelude::*;\nuse bevy_scriptum::prelude::*;\nuse bevy_scriptum::runtimes::lua::prelude::*;\n\n#[derive(Component)]\nstruct Player;\n\nApp::new()\n    .add_plugins(DefaultPlugins)\n    .add_scripting::\u003cLuaRuntime\u003e(|runtime| {\n        runtime.add_function(\n            String::from(\"print_player_names\"),\n            |players: Query\u003c\u0026Name, With\u003cPlayer\u003e\u003e| {\n                for player in \u0026players {\n                    println!(\"player name: {}\", player);\n                }\n            },\n        );\n    })\n    .run();\n```\n\nYou can also pass arguments to your callback functions, just like you would in a regular Bevy system - using `In` structs with tuples:\n```rust\nuse bevy::prelude::*;\nuse bevy_scriptum::prelude::*;\nuse bevy_scriptum::runtimes::lua::prelude::*;\n\nApp::new()\n    .add_plugins(DefaultPlugins)\n    .add_scripting::\u003cLuaRuntime\u003e(|runtime| {\n        runtime.add_function(\n            String::from(\"fun_with_string_param\"),\n            |In((x,)): In\u003c(String,)\u003e| {\n                println!(\"called with string: '{}'\", x);\n            },\n        );\n    })\n    .run();\n```\nwhich you can then call in your script like this:\n```lua\nfun_with_string_param(\"Hello world!\")\n```\n\n### Usage\n\nAdd the following to your `Cargo.toml`:\n\n```toml\n[dependencies]\nbevy_scriptum = { version = \"0.6\", features = [\"lua\"] }\n```\n\nor execute `cargo add bevy_scriptum --features lua` from your project directory.\n\nYou can now start exposing functions to the scripting language. For example, you can expose a function that prints a message to the console:\n\n```rust\nuse bevy::prelude::*;\nuse bevy_scriptum::prelude::*;\nuse bevy_scriptum::runtimes::lua::prelude::*;\n\nApp::new()\n    .add_plugins(DefaultPlugins)\n    .add_scripting::\u003cLuaRuntime\u003e(|runtime| {\n       runtime.add_function(\n           String::from(\"my_print\"),\n           |In((x,)): In\u003c(String,)\u003e| {\n               println!(\"my_print: '{}'\", x);\n           },\n       );\n    })\n    .run();\n```\n\nThen you can create a script file in `assets` directory called `script.lua` that calls this function:\n\n```lua\nmy_print(\"Hello world!\")\n```\n\nAnd spawn an entity with attached `Script` component with a handle to a script source file:\n\n```rust\nuse bevy::prelude::*;\nuse bevy_scriptum::prelude::*;\nuse bevy_scriptum::runtimes::lua::prelude::*;\n\nApp::new()\n    .add_plugins(DefaultPlugins)\n    .add_scripting::\u003cLuaRuntime\u003e(|runtime| {\n       runtime.add_function(\n           String::from(\"my_print\"),\n           |In((x,)): In\u003c(String,)\u003e| {\n               println!(\"my_print: '{}'\", x);\n           },\n       );\n    })\n    .add_systems(Startup,|mut commands: Commands, asset_server: Res\u003cAssetServer\u003e| {\n        commands.spawn(Script::\u003cLuaScript\u003e::new(asset_server.load(\"script.lua\")));\n    })\n    .run();\n```\n\nYou should then see `my_print: 'Hello world!'` printed in your console.\n\n### Demo\n\n![demo](demo.gif)\n\n### Provided examples\n\nYou can also try running provided examples by cloning this repository and running `cargo run --example \u003cexample_name\u003e_\u003clanguage_name\u003e`.  For example:\n\n```bash\ncargo run --example hello_world_lua\n```\nThe examples live in `examples` directory and their corresponding scripts live in `assets/examples` directory within the repository.\n\n### Bevy compatibility\n\n| bevy version | bevy_scriptum version |\n|--------------|-----------------------|\n| 0.14         | 0.6                   |\n| 0.13         | 0.4-0.5               |\n| 0.12         | 0.3                   |\n| 0.11         | 0.2                   |\n| 0.10         | 0.1                   |\n\n### Promises - getting return values from scripts\n\nEvery function called from script returns a promise that you can call `:and_then` with a callback function on. This callback function will be called when the promise is resolved, and will be passed the return value of the function called from script. For example:\n\n```lua\nget_player_name():and_then(function(name)\n    print(name)\nend)\n```\nwhich will print out `John` when used with following exposed function:\n\n```rust\nuse bevy::prelude::*;\nuse bevy_scriptum::prelude::*;\nuse bevy_scriptum::runtimes::lua::prelude::*;\n\nApp::new()\n   .add_plugins(DefaultPlugins)\n   .add_scripting::\u003cLuaRuntime\u003e(|runtime| {\n           runtime.add_function(String::from(\"get_player_name\"), || String::from(\"John\"));\n   });\n````\n\n## Access entity from script\n\nA variable called `entity` is automatically available to all scripts - it represents bevy entity that the `Script` component is attached to.\nIt exposes `index` property that returns bevy entity index.\nIt is useful for accessing entity's components from scripts.\nIt can be used in the following way:\n```lua\nprint(\"Current entity index: \" .. entity.index)\n```\n\n`entity` variable is currently not available within promise callbacks.\n\n### Contributing\n\nContributions are welcome! Feel free to open an issue or submit a pull request.\n\n### License\n\nbevy_scriptum is licensed under either of the following, at your option:\nApache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) or MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarkonik%2Fbevy_scriptum","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjarkonik%2Fbevy_scriptum","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjarkonik%2Fbevy_scriptum/lists"}