bevy_archive 0.2.1

An experimental ECS world snapshot system built on Bevy, featuring structured archetype storage and manifest-based serialization.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

# bevy_archive



[![Crates.io](https://img.shields.io/crates/v/bevy_archive.svg)](https://crates.io/crates/bevy_archive)
[![Docs.rs](https://docs.rs/bevy_archive/badge.svg)](https://docs.rs/bevy_archive)
[![CI](https://github.com/chengts95/bevy_archive/actions/workflows/rust.yml/badge.svg)](https://github.com/chengts95/bevy_archive/actions)

**bevy_archive** is an experimental project for exploring ECS world storage and loading strategies based on archetype decomposition and structured serialization.

It uses a combination of serialization formats to balance:
- **flexibility** (via JSON as a common object model),
- **machine-read/write efficiency** (via CSV), and
- **human readability/editability** (via TOML manifests).

Currently implemented on top of [Bevy ECS](https://bevyengine.org/), but designed with the potential for cross-ECS engine compatibility in mind.

---

## ✨ Goals


- Represent ECS state in a fully structured, archetype-separated format
- Support full world snapshot roundtrip (save → serialize → reload)
- Enable patching, diffing, and composable storage segments
- Treat `Entity` references as serializable via wrappers (e.g., `ChildOfWrapper`)
- Organize data in layers: entity IDs → archetypes → CSV-encoded columns

---

## 📦 Format Overview ("Aurora")


Aurora is the internal name for the snapshot format used in this project. It is not a rigid standard, but a set of conventions designed to:

- Encode **archetype layout** in manifest
- Encode **component data** in columnar CSV or structured JSON
- Embed or reference data via paths/URIs (`embed://`, `file://`, etc.)
- Save and load data from multiple data files (not tested yet)

### Aurora TOML Manifest Example

```toml
name = "MyWorld"

[world]
version = "0.1"

[[world.archetypes]]
name = "arch_0"
components = ["Position", "Velocity"]
storage = ["Table", "Table"]
source = "embed://arch_0"

[world.embed.arch_0]
format = "csv"
data = '''
id,Position.x,Position.y,Velocity.dx,Velocity.dy
0,1.0,2.0,0.1,-0.2
'''
```

---

## 📂 Examples

### 🔁 Minimal Snapshot Example


```rust
// Full roundtrip: save → serialize → load

use bevy_archive::prelude::*;
use bevy_ecs::prelude::*;
use serde::{Serialize, Deserialize};

#[derive(Component, Serialize, Deserialize)]

struct Health(f32);

fn main() {
    // Setup world and registry
    let mut world = World::new();
    let mut registry = SnapshotRegistry::default();
    registry.register::<Health>();

    // Spawn some test data
    world.spawn(Health(100.0));
    world.spawn(Health(75.0));

    // Save snapshot
    let manifest = save_world_manifest(&world, &registry).unwrap();
    manifest.to_file("my_world.toml", None).unwrap();

    // Load into new world
    let loaded = AuroraWorldManifest::from_file("my_world.toml", None).unwrap();
    let mut new_world = World::new();
    load_world_manifest(&mut new_world, &loaded, &registry).unwrap();
}

```
---
Custom type wrappers can be added via:
```rust
//Vector2Wrapper need to implement From<&Vector> and Into<Vector2> for Vector2Wrapper
registry.register_with::<Vector2, Vector2Wrapper>(); 

```
### Other examples

- `aurora_manifest_example.rs`: save/load a Bevy world with children using a structured manifest
- `entity_snapshot.rs`: legacy entity-based archive with per-entity serialization
- `cross_ecs.rs`: example for **experimental** `flecs` <-> `bevy` data exchange.
- `archetype_reduction_example.rs`: show how the deferred entity insertion can avoid archetype explosion in `bevy`



---

## 🔧 Future Directions

- global singleton support
- Patch and delta snapshot calculation
- Archetype merge and dependency resolution
- Cross-engine (e.g., Flecs, EnTT) structure mapping
- Streamed and binary snapshotting

---

## 🪐 Philosophy


This project does not aim to lock into a fixed standard. Instead, it provides a practical, iteratively refined data flow that is:

- observable,
- debuggable,
- serializable,
- and extensible.

> ECS is not about objects — it's about structure, state, and change. With Aurora, composable components can form a flexible patching system that updates only the key state information, allowing targeted restoration or transformation of an ECS world.

> 
> Note: This project is **not affiliated with the official Bevy organization**. It is an experimental toolset built on top of the Bevy ECS framework.
> 
---

## License


MPL 2.0 License