{"id":20410917,"url":"https://github.com/mintlu8/bevy_serde_lens","last_synced_at":"2026-02-13T04:18:38.828Z","repository":{"id":225174347,"uuid":"764846871","full_name":"mintlu8/bevy_serde_lens","owner":"mintlu8","description":"Stateful, structural and pretty serialization framework for the bevy engine.","archived":false,"fork":false,"pushed_at":"2024-04-25T22:18:02.000Z","size":87,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-25T22:32:46.958Z","etag":null,"topics":["bevy","rust","save","serde","serialization"],"latest_commit_sha":null,"homepage":"","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}},"created_at":"2024-02-28T20:20:33.000Z","updated_at":"2024-04-28T17:34:58.746Z","dependencies_parsed_at":"2024-04-28T17:45:04.963Z","dependency_job_id":null,"html_url":"https://github.com/mintlu8/bevy_serde_lens","commit_stats":null,"previous_names":["mintlu8/bevy_serde_project","mintlu8/bevy_serde_lens"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy_serde_lens","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy_serde_lens/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy_serde_lens/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mintlu8%2Fbevy_serde_lens/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mintlu8","download_url":"https://codeload.github.com/mintlu8/bevy_serde_lens/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224737131,"owners_count":17361345,"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","rust","save","serde","serialization"],"created_at":"2024-11-15T05:49:02.503Z","updated_at":"2026-02-13T04:18:38.815Z","avatar_url":"https://github.com/mintlu8.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bevy_serde_lens\n\n[![Crates.io](https://img.shields.io/crates/v/bevy_serde_lens.svg)](https://crates.io/crates/bevy_serde_lens)\n[![Docs](https://docs.rs/bevy_serde_lens/badge.svg)](https://docs.rs/bevy_serde_lens/latest/bevy_serde_lens/)\n[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://bevyengine.org/learn/book/plugin-development/)\n\nBlazingly fast, schema based and human-readable serialization crate for the bevy engine.\n\n## Features\n\n* Stateful serialization and deserialization with world access.\n* No systems, no plugins.\n* Blazingly fast (compared to `DynamicScene`).\n* Treat an `Entity`, its `Component`s and children as a single serde object.\n* Deserialize trait objects like `Box\u003cdyn T\u003e`, as an alternative to `typetag`.\n* Supports every serde format using familiar syntax.\n* Serialize `Handle`s and provide a generalized data interning interface.\n* No reflection needed.\n\n## Getting Started\n\nImagine we have a typical `Character` bundle.\n\nFirst we derive `BevyObject`:\n\n```rust\n#[derive(Bundle, BevyObject)]\n#[bevy_object(query)]\npub struct Character {\n    pub transform: Transform,\n    pub name: Name,\n    pub position: Position,\n    pub hp: Hp,\n}\n```\n\n* `#[bevy_object(query)]`\n\nThis indicates we are serializing a query instead of a hierarchical tree, which improves performance.\n\nTo serialize we simply do:\n\n```rust\nserde_json::to_string(\u0026world.serialize_lens::\u003cCharacter\u003e());\n```\n\nThis finds all entities that fits the `QueryFilter` of the bundle and serializes them in an array.\n\nTo deserialize we use `deserialize_scope`:\n\n```rust\nworld.deserialize_scope(|| {\n    // Returned object doesn't matter, data is stored in the world.\n    let _ = serde_json::from_str::\u003cInWorld\u003cCharacter\u003e\u003e(\u0026json_string);\n})\n```\n\nThis statement spawns new entities in the world and fills them with deserialized data.\n\nYou might want to delete current entities before loading new ones,\nto delete all associated entities of a serialization:\n\n```rust\n// Despawn all character.\nworld.despawn_bound_objects::\u003cCharacter\u003e()\n```\n\nTo save multiple types of objects in a batch, create a batch serialization type with the `batch!` macro.\n\n```rust\ntype SaveFile = batch!(\n    Character, Monster,\n    // Use `SerializeResource` to serialize a resource.\n    SerializeResource\u003cTerrain\u003e,\n);\nworld.serialize_lens::\u003cSaveFile\u003e()\nworld.deserialize_scope(|| {\n    let _ = serde_json::from_str::\u003cInWorld\u003cSaveFile\u003e\u003e(\u0026json_string);\n})\nworld.despawn_bound_objects::\u003cSaveFile\u003e()\n```\n\nThis saves each type in a map entry:\n\n```rust\n{\n    \"Character\": [ \n        { .. },\n        { .. },\n        ..\n    ],\n    \"Monster\": [ .. ],\n    \"Terrain\": ..\n}\n```\n\n## Advanced Serialization\n\n`BevyObject` is not just a clone of `Bundle`, we support additional types.\n\n* `impl BevyObject`: Components are automatically `BevyObject` and `BevyObject` can contain multiple other `BevyObject`s.\n* `Maybe\u003cT\u003e` can be used if an item may or may not exist.\n* `DefaultInit` initializes a non-serialize component with `FromWorld`.\n* `Child\u003cT\u003e` finds and serializes a single `BevyObject` in children.\n* `ChildVec\u003cT\u003e` finds and serializes multiple `BevyObject`s in children.\n\nNew in 0.5:\n\n* `Child\u003cT, C\u003e` finds and serializes a single `BevyObject` from a custom children component.\n* `ChildVec\u003cT, C\u003e` finds and serializes multiple `BevyObject`s from a custom children component.\n\nSee the `BevyObject` derive macro for more details.\n\n```rust\n// Note we cannot derive bundle anymore.\n// #[bevy_object(query)] also cannot be used due to children being serialized.\n#[derive(BevyObject)]\n#[bevy_object(rename = \"character\")]\npub struct Character {\n    pub transform: Transform,\n    pub name: Name,\n    pub position: Position,\n    pub hp: Hp,\n    #[serde(default)]\n    pub weapon: Maybe\u003cWeapon\u003e\n    #[serde(skip)]\n    pub cache: DefaultInit\u003cCache\u003e,\n    pub potions: ChildVec\u003cPotion\u003e\n}\n```\n\n## Stateful Serialization\n\nWhen using `bevy_serde_lens` you can use `with_world` to access `\u0026World`\nin `Serialize` implementations and `with_world_mut` to access `\u0026mut World`\nin `Deserialize` implementations.\n\nThese functions actually comes from `bevy_serde_lens_core`\nwhich is more semver stable and more suited as a dependency for library authors.\n\n## Serialize Handles\n\nTo serialize a `Handle` as its string path, you can use `#[serde(with = \"PathHandle\")]`.\nTo serialize its content, use `#[serde(with = \"UniqueHandle\")]`.\n\n```rust\n#[derive(Component, Serialize, Deserialize)]\nstruct MySprite {\n    #[serde(with = \"PathHandle\")]\n    image: Handle\u003cImage\u003e\n}\n```\n\nOr use the newtype directly.\n\n```rust\n#[derive(Component, Serialize, Deserialize)]\nstruct MySprite {\n    image: PathHandle\u003cImage\u003e\n}\n```\n\n## TypeTag\n\nWe provide registration based deserialization as an alternative to the `typetag` crate.\nSee the `typetagged` module for details.\n\n## Versions\n\n| bevy | bevy-serde-lens-core | bevy-serde-lens    |\n|------|----------------------|--------------------|\n| 0.13 | -                    | 0.1-0.3            |\n| 0.14 | 0.14                 | 0.4                |\n| 0.15 | 0.15                 | 0.5                |\n| 0.16 | 0.16                 | 0.6                |\n| 0.17 | 0.17                 | 0.7                |\n| 0.18 | 0.18                 | 0.8                |\n\n## License\n\nLicensed under either of\n\n* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e)\n* MIT license ([LICENSE-MIT](LICENSE-MIT) or \u003chttp://opensource.org/licenses/MIT\u003e)\n\nat your option.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any\nadditional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintlu8%2Fbevy_serde_lens","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmintlu8%2Fbevy_serde_lens","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmintlu8%2Fbevy_serde_lens/lists"}