Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Combine scene serialization sections #6

Merged
merged 4 commits into from
Nov 8, 2022
Merged

Combine scene serialization sections #6

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98c9b05
Combine scene serialization sections
rparrett Nov 8, 2022
9d09d0b
Embed diff
rparrett Nov 8, 2022
f8362a4
Undiff the diff
rparrett Nov 8, 2022
5bf793c
Add migration advice
rparrett Nov 8, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 6 additions & 127 deletions content/learn/book/migration-guides/0.8-0.9/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,7 @@ commands.entity(some_entity).remove_bundle::<SomeBundle>();
// New (0.9)
commands.entity(some_entity).remove::<SomeBundle>();
```

Replace `remove_bundle_intersection` with `remove_intersection`:

```rust
Expand Down Expand Up @@ -624,141 +625,19 @@ After:
);
```

### [Replace root list with struct](https://github.com/bevyengine/bevy/pull/6354)

The scene file format now uses a struct as the root object rather than a list of entities. The list of entities is now found in the `entities` field of this struct.

```rust
// Old (Bevy 0.8)
[
(
entity: 0,
components: [
// Components...
]
),
]

// New (Bevy 0.9)
(
entities: [
(
entity: 0,
components: [
// Components...
]
),
]
)
```

### [Use map for scene `components`](https://github.com/bevyengine/bevy/pull/6345)
### Scene serialization format improvements from [#6354](https://github.com/bevyengine/bevy/pull/6354), [#6345](https://github.com/bevyengine/bevy/pull/6345), and [#5723](https://github.com/bevyengine/bevy/pull/5723)

The scene format now uses a map to represent the collection of components. Scene files will need to update from the old list format.
* The root of the scene is now a struct rather than a list
* Components are now a map keyed by type name rather than a list
* Type information is now omitted when possible, making scenes much more compact

```rust
// Old (Bevy 0.8)
[
(
entity: 0,
components: [
{
"bevy_transform::components::transform::Transform": (
translation: (
x: 0.0,
y: 0.0,
z: 0.0
),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (
x: 1.0,
y: 1.0,
z: 1.0
),
),
},
{
"my_crate::Foo": (
text: "Hello World",
),
},
{
"my_crate::Bar": (
baz: 123,
),
},
],
),
]

// New (Bevy 0.9)
[
(
entity: 0,
components: {
"bevy_transform::components::transform::Transform": (
translation: (
x: 0.0,
y: 0.0,
z: 0.0
),
rotation: (0.0, 0.0, 0.0, 1.0),
scale: (
x: 1.0,
y: 1.0,
z: 1.0
),
),
"my_crate::Foo": (
text: "Hello World",
),
"my_crate::Bar": (
baz: 123
),
},
),
]
```
See [this diff](https://github.com/bevyengine/bevy/compare/v0.8.0...main#diff-12b7f105bbb2a716e818a2a7eb2c79d40bef29ae8cba45b536c79cfa16b83558) for an illustration.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't that just a full diff of bevy since 0.8? I think I'd prefer keeping the examples that were already present.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention was to link specifically to the diff for assets/scenes/load_scene_example.scn.ron. But that seems broken now. Will look into that, or just recreate the diff in a gist or something.

Keeping all the existing examples seems slightly problematic to me because we would be showing

Bevy 0.8 -> A format that is not valid
A format that is not valid -> Another format that is not valid
A format that is not valid -> Bevy 0.9

And this doesn't seem useful to me, personally.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I didn't realize those formats were all invalid. In that case maybe just paste the diff directly instead of a link?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good idea. I'll try that out

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not a huge fan of this either. I'm a bit lost about a good way to convey this information, really.

It was a bit better off-site as a side-by-side diff, but still not great.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I didn't realize those formats were all invalid.

That's a bit of an assumption, but I'm reasonably sure it holds.

I am assuming that most people affected will be re-serializing their scenes and not hand-editing them though so I'm not sure how useful any of this is.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's a good point actually, I guess the migration guide here is mostly about telling people that their old scene file won't work, not to update it manually. Do we have ways to re-serialize scenes though or would that just mean manually recreating it?

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I still like keeping the example there. It shows what's going on pretty well.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, sorry, by paste the diff I just meant to do like other guides and have it in 2 separate code block, one with 0.8 and one with 0.9

Done. That looks a lot better as a visual aid at least.

Do we have ways to re-serialize scenes though or would that just mean manually recreating it?

Might be worth asking around #scenes-dev to see if there's actually some sort of migration strategy for people. But as far as I know, it would mean manually recreating scenes.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess users might be confused about that too, so it might be worth spelling it out in the guide if that's the case.


### [Derive `Reflect` + `FromReflect` for input types](https://github.com/bevyengine/bevy/pull/6232)

* `Input<T>` now implements `Reflect` via `#[reflect]` instead of `#[reflect_value]`. This means it now exposes its private fields via the `Reflect` trait rather than being treated as a value type. For code that relies on the `Input<T>` struct being treated as a value type by reflection, it is still possible to wrap the `Input<T>` type with a wrapper struct and apply `#[reflect_value]` to it.
* As a reminder, private fields exposed via reflection are not subject to any stability guarantees.

### [Improve serialization format even more](https://github.com/bevyengine/bevy/pull/5723)

This PR reduces the verbosity of the scene format. Scenes will need to be updated accordingly:

```js
// Old format
{
"type": "my_game::item::Item",
"struct": {
"id": {
"type": "alloc::string::String",
"value": "bevycraft:stone",
},
"tags": {
"type": "alloc::vec::Vec<alloc::string::String>",
"list": [
{
"type": "alloc::string::String",
"value": "material"
},
],
},
}
}

// New format
{
"my_game::item::Item": (
id: "bevycraft:stone",
tags: ["material"]
)
}
```

### [Relax bounds on `Option<T>`](https://github.com/bevyengine/bevy/pull/5658)

If using `Option<T>` with Bevy’s reflection API, `T` now needs to implement `FromReflect` rather than just `Clone`. This can be achieved easily by simply deriving `FromReflect`:
Expand Down