{"id":20410896,"url":"https://github.com/mintlu8/bevy-rectray-ui","last_synced_at":"2025-06-29T18:32:28.705Z","repository":{"id":204601659,"uuid":"712234185","full_name":"mintlu8/bevy-rectray-ui","owner":"mintlu8","description":"A light-weight Anchor-Offset based 2D sprite rendering system for the bevy engine.","archived":false,"fork":false,"pushed_at":"2024-03-15T16:03:58.000Z","size":11430,"stargazers_count":16,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-04T23:56:34.660Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/mintlu8.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2023-10-31T04:10:09.000Z","updated_at":"2024-08-16T04:17:29.000Z","dependencies_parsed_at":"2024-03-15T00:40:33.382Z","dependency_job_id":"4a2dc7ce-0abb-4f56-8c5b-3cbd64cd1b2e","html_url":"https://github.com/mintlu8/bevy-rectray-ui","commit_stats":null,"previous_names":["mintlu8/bevy-aoui"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mintlu8/bevy-rectray-ui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy-rectray-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy-rectray-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy-rectray-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy-rectray-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mintlu8","download_url":"https://codeload.github.com/mintlu8/bevy-rectray-ui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy-rectray-ui/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262647259,"owners_count":23342624,"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":[],"created_at":"2024-11-15T05:48:59.557Z","updated_at":"2025-06-29T18:32:28.677Z","avatar_url":"https://github.com/mintlu8.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bevy Rectray\n\n[![Crates.io](https://img.shields.io/crates/v/bevy_rectray.svg)](https://crates.io/crates/bevy_rectray)\n[![Docs](https://docs.rs/bevy_rectray/badge.svg)](https://docs.rs/bevy_rectray/latest/bevy_rectray/)\n[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://bevyengine.org/learn/book/plugin-development/)\n\nBevy Rectray is a native component based 2D and UI solution for the bevy engine.\n\n## Getting Started\n\nFirst add the `RectrayPlugin`:\n\n```rust\napp.add_plugins(RectrayPlugin)\n```\n\nImport the\n[DSL prelude](https://docs.rs/bevy_rectray/latest/bevy_rectray/dsl/prelude/),\npreferably inside the function scope.\n\n```rust\nfn spawn(mut commands: RCommands) {\n    use bevy_rectray::dsl::prelude::*;\n    ...\n}\n```\n\nCreate a sprite:\n\n```rust\nsprite!(commands {\n    sprite: \"Ferris.png\",\n    anchor: Left,\n    offset: [40, 0],\n    dimension: [200, 200],\n})\n```\n\nThis spawns a \"Ferris.png\" to the center left of the screen,\nmoved to the right by `40 px`, with dimension `200 px * 200 px`,\nand returns an `Entity`.\n\nCreate a hierarchy:\n\n```rust\nvstack!(commands {\n    font_size: em(2),\n    child: text! {\n        text: \"Hello\"\n    },\n    child: text! {\n        text: \"rust\",\n        child: text! {\n            text: \"and bevy!\"\n        },\n    },\n});\n```\n\n### Why a DSL?\n\n`bevy_rectray`'s DSL is a very simple `macro_rules` macro that reorganizes arguments in a way to make\n`commands` usable anywhere during the macro invocation, without the need to bend over backwards\nto create children/bundles before parents. As a result we have a simple rust-like syntax.\nthat is intuitive and enjoyable to write.\n\nIf you don't like the DSL you can use our\n[`bundles`](https://docs.rs/bevy_rectray/latest/bevy_rectray/bundles)\nor\n[`widgets`](https://docs.rs/bevy_rectray/latest/bevy_rectray/dsl/builders)\ndirectly,\n\n## How this works?\n\n`bevy_rectray` is all about rectangles!\n\nEach sprite is a rectangle, and placed relative to the parent\nrectangle.\n\nYou might want to\n\n```text\nPlace a sprite to the center right of the parent sprite,\nmove left by 10 px,\nwith 20% of parent's width as width\n2x font size as height\nand rotate by 45 degrees.\n```\n\nIn `bevy_rectray` this is incredibly simple:\n\n```rust\nsprite!(commands {\n    anchor: Right,\n    offset: [-10, 0],\n    dimension: size2!(20 %, 2 em),\n    rotation: degrees(45),\n    ...\n})\n```\n\nUse `Transform2D` and `Dimension` to manipulate our widgets directly.\n\n## What `bevy_rectray` provides\n\n* Fine grained low level anchor-offset layout system.\n* First class support for rotation and scaling.\n* Simple and intuitive containers.\n* Decentralized ECS components with no central state.\n* Complete support of bevy's 2D primitives.\n* Input handling system for mouse and cursor.\n* Building blocks for most common widgets.\n* Event handling through one-shot systems.\n* Reactivity and animation through signals.\n* `macro_rules` based DSL that annihilates boilerplate.\n* Easy integration with third-party 2D crates.\n* Easy migration to future bevy versions.\n\n## What `bevy_rectray` is not\n\n* Not a renderer.\n\n    `bevy_rectray` has minimal rendering features and no third party bevy dependencies,\n    this ensures maintainability and easy migration to future bevy versions,\n    at the cost of not having out of the box widget styles.\n\n* Not `bevy_ui` compatible.\n\n    `bevy_rectray` is not dependent on `bevy_ui` in any way. This means `bevy_ui` exclusive\n    features won't be available in `bevy_rectray` as is.\n\n* No ui script or serialization.\n\n    `bevy_rectray` uses rust closures for a lot of things, including events and reactivity,\n    those are unfortunately not serializable.\n\n* Limited reflection support.\n\n    Limiting the scope of this project to the supported feature set of `Reflection` is not ideal of this project. Use reflect to some extent to\n    debug is supported, but don't expect every reflect based feature to work with `bevy_rectray`.\n\n* No styling\n\n    Styling is outside the scope of this crate.\n\n## Container\n\nAnchor-Offset offers fine-grained control over the layout, but you can surrender\nthat control to\n[containers](https://docs.rs/bevy_rectray/latest/bevy_rectray/layout) for ergonomics.\n\nThe `Container` is a very simple layout system that\nonly depends on insertion order of its children. You can find your\n[`hstack`](https://docs.rs/bevy_rectray/latest/bevy_rectray/layout/struct.StackLayout.html),\n[`grid`](https://docs.rs/bevy_rectray/latest/bevy_rectray/layout/struct.FixedGridLayout.html)\nor\n[`paragraph`](https://docs.rs/bevy_rectray/latest/bevy_rectray/layout/struct.ParagraphLayout) here.\n\nYou can implement [`Layout`](https://docs.rs/bevy_rectray/latest/bevy_rectray/layout/trait.Layout) yourself to create a custom layout.\n\n## Widget Abstractions\n\nWidget builders are used to empower our DSL.\nWidget builders implements [`Widget`](https://docs.rs/bevy_rectray/latest/bevy_rectray/dsl/trait.Widget)\nand `Default`.\nThey can be used in general like so:\n\n```rust\nFrameBuilder {\n    offset: [121, 423].dinto(),\n    anchor: Center.dinto(),\n    color: color!(red).dinto()\n    ..Default::default()\n}.build(commands)\n```\n\nThis returns an `Entity`.\n\n`dinto` is implemented in `DslFrom` or `DslInto`.\nwhich gives us nice conversion like `[i32; 2] -\u003e Vec2`, which can save us a lot of typing!\n\nWhen using the dsl macro, this becomes\n\n```rust\nframe! (commands {\n    offset: [121, 423],\n    anchor: Center,\n    color: color!(red),\n});\n```\n\nmuch cleaner, right?\n\n## DSL Syntax\n\nThe DSL have a few special fields that makes it much more powerful than\na simple struct constructor.\n\n### commands\n\nAt the root level, the DSL takes a\n[`RCommands`](https://docs.rs/bevy_rectray/latest/bevy_rectray/dsl/struct.RCommands),\nwhich is a combination of `Commands`, `AssetServer` and\n[`SignalPool`](https://docs.rs/bevy_rectray/latest/bevy_rectray/signals/struct.SignalPool),\n\n### child\n\n`child:` is a special field that can be repeated, it accepts an `Entity`, `Option\u003cEntity\u003e`\nor an iterator of `Entity`/`\u0026Entity`,\nand inserts it/them as a child/children.\n\n```rust\nframe! (commands {\n    ...\n    child: rectangle! {\n        dimension: [40, 40]\n    },\n    child: text! {\n        text: \"Hello, World!!\"\n    },\n    child: \"Hello\".chars().map(|c|\n        text! (commands {\n            text: c,\n        })\n    )\n});\n```\n\nThis syntax, notice the use of braces `{}`,\n\n```rust\nfield: macro! { .. },\n```\n\nWill be automatically rewritten as\n\n```rust\nfield: macro!(commands { .. }),\n```\n\nWhich serves as context propagation.\n\n### extra\n\nExtra adds a component or a bundle to a widget,\nwhich is the idiomatic pattern to compose behaviors.\n\n```rust\n// Example: Add dragging support to a `Sprite`.\nsprite! (commands {\n    ...\n    extra: DragX,\n    extra: DragConstraint,\n    extra: DragSnapBack,\n});\n```\n\n### entity\n\n`entity` lets us fetch the `Entity`\ndirectly from a nested macro invocation.\n\n```rust\nlet sprite_entity: Entity;\nsprite! (commands {\n    child: sprite! {\n        entity: sprite_entity,\n    }\n});\n```\n\n### `quote!` syntax\n\nWe have support for a syntax inspired by the `quote!` crate,\nthat can be used to repeat a child by an iterator.\n\n```rust\nvstack! (commands {\n    child: #rectangle! {\n        dimension: #dimensions,\n        color: #colors,\n    }\n});\n```\n\nThis zips `colors` and `dimensions` and\niterate through them to create multiple rectangles.\n\n#### Note\n\nThe dsl normally functions on the field level, which is\nperformant and editor friendly, but using `quote!` syntax\nrequires running a `tt` muncher, which may cause editors to give up\nor break your recursion limit. You can use\n\n```rust\n#![recursion_limit=\"256\"]\n```\n\nto increase your recursion limit.\n\n## Next Steps\n\nCheckout our modules for more documentations and examples.\n\n* [events](https://docs.rs/bevy_rectray/latest/bevy_rectray/events)\n* [signals](https://docs.rs/bevy_rectray/latest/bevy_rectray/signals)\n* [widgets](https://docs.rs/bevy_rectray/latest/bevy_rectray/widgets)\n* [animation](https://docs.rs/bevy_rectray/latest/bevy_rectray/anim)\n\n## License\n\nLicense under either of\n\nApache License, Version 2.0 (LICENSE-APACHE or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\nMIT license (LICENSE-MIT or \u003chttp://opensource.org/licenses/MIT\u003e)\nat your option.\n\n## Contribution\n\nContributions are welcome!\n\nUnless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintlu8%2Fbevy-rectray-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmintlu8%2Fbevy-rectray-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintlu8%2Fbevy-rectray-ui/lists"}