Reflecting on the state of Reflection

[cart]

I've been in a bit of a yak shave for the past couple of days. As part of my BSN asset work I'm trying to make the reflection parts as efficient as possible (ex: avoid boxing for primitive types using a DynamicValue enum, don't do string matching more than once). My DynamicValue / DynamicFields abstraction worked well for struct patching, but enums require FromReflect, which means DynamicFields needs to implement reflect. This is doable, but it would require storing string names on the DynamicFields instance (not ideal) and it would require matching on string names, as this is what FromReflect relies on (not ideal, as at this point we already have the field indices, which are faster to look up).

• I've generally been convinced that reflection in its current form needs some changes. We're doing a lot of redundant codegen and I suspect we can cut down on both compile times and binary sizes significantly with some rearchitecture (facet's general strategy is "better" imo, although not the right fit for Bevy as a whole). Many of my initial architectural choices for reflection six years ago (which was arguably the first generalized Rust reflection implementation) have ended up being short-sighted, and we have also accumulated a lot of "design cruft" over the years:
  • We have a ton of codegen for field accesses of various kinds (read-only index, mutable index, read-only string, mutable string) , when we could just store a pointer offset on the reflected field, then have non-monomorphized code for high level field access APIs.
  • My choice to allow "proxy types" to pretend to be real Rust types resulted in the need for the PartialReflect / Reflect split, introducing unnecessary complexity. We can simplify this a lot if we make these "dynamic value types" a standalone API that works on top of the reflection API
  • Supporting "proxy types" everywhere (apply, FromReflect, etc) has resulted in lots of overhead / codegen / complexity. FromReflect is hard-coded to look up field names ... this is suboptimal. It also tightly couples "reflection-driven init" to reflect-from-reflect, which limits use cases.
  • FromReflect functionality could be driven off of reflection metadata, rather than needing hard-coded per-type trait impls
  • TypePath stores a bunch of different string permutations plus the Vtable for each impl. I think it could just be a type, with a compressed representation that doesn't pack the binary with a bunch of substring variants.
  • Reflect and PartialReflect have a ton of methods, many of them for "convenience". Lots of monomorphization. We can slim this down a lot
• To those ends, I have been experimenting with a new Reflection API that I suspect will cut down on compile times and binary sizes, reduce internals complexity significantly, and also enable scenarios like BSN assets, BRP, and inspectors to perform better. I have basic reflection functionality working (derive reflect for structs, reflect field access, reflect-driven init (replacing FromReflect)). My plan is to make it a drop-in replacement for the Reflect derive. Then I can test the effect on binary sizes and compile times, and ensure it works in the scenarios we need it to.

I understand that changing the reflection APIs is disruptive, but I strongly suspect that we are stuck in a local optimum at the moment. I won't push for these changes until I've proven that to be true / the cost of porting friction is outweighed by the benefits of the switch. This will of course be a discussion as well (once we have actual details to discuss). This post is largely just a heads up that I'm investigating this.

[alice-i-cecile]

I'm very open to breaking changes here. Power users will benefit a lot from reduced code gen, and cleaning up the story around proxy types is a huge simplification.

[MrGVSV]

If we're open to making substantial changes, I wholeheartedly agree that we should make them. The current API is bloated, complex, and riddle with tech debt. We can slim this down a lot if we're okay with completely overhauling the crate.

I think we could take some ideas from https://github.com/soqb/perfect-reflect (@soqb's proof of concept for simplifying the reflection API). One of the main things I liked was how all the sub-traits (e.g., Struct, List, etc.) were fully encapsulated in an enum that looked like this:

pub enum Value {
    Dyn(Box<dyn Reflect>),
    Seq(Vec<Value>),
    Struct(FieldValues),
    Enum(VariantValue),
}

Because at the end of the day, that really is the rough shape of all Rust types. And even that API could be further simplified (e.g., FieldValues could instead be Vec<FieldValue> or similar, removing the need for the named-vs-unnamed distinction).

And of course, there's lots more (some that have already had some amount of work put into them): proper reflection-based serialization, proper reflection hashing/comparisons, smart pointer reflection, better feature gating, etc.

Not to mention that we can take the opportunity to break things up so things aren't as tightly coupled. This not only makes it harder for new users/contributors to understand the crate, it's also made it difficult to split up the crate as part of Modular Reflection.

All this to say I am definitely onboard with rearchitecting. I have other thoughts but I'll post them in separate comments for discussion 🙂

[MrGVSV]

I think with the prospect of rearchitecting, we should also take a moment to consider what we're architecting.

Is this a general-purpose reflection API built for any Rust user?

Is this a gamedev-focused reflection API meant mostly for users of Bevy (or maybe even other game engines as well)?

There will be a lot of overlap here, of course, but I think we should design this with an intended audience in mind. And personally while I'd love to make this general-purpose, I think it would serve Bevy better in the long-run to design the crate for Bevy.

Do we want custom attributes? Do we want a way to attach ECS or UI data to fields?¹ How can we make reflection-driven deserialization easier in asset readers?¹ How can we make it easier to hook data into the editor? How can we make it easier to interop with scripting languages?

The editor and inspector work should really be driving a lot of our design decisions. And by not being as cautious to introduce Bevy-specific code into the crate², we can make it easier for both our users to use and our contributors to contribute to.

That being said, I also do value the notion of the crate being more useful outside of just Bevy. So I am torn a bit. We could also consider splitting the crate into (at least) two crates: one for general Rust use and another built on top of it for Bevy use.

Footnotes

1. Yes, in some cases we can put the logic in the respective Bevy crate. But I'm talking here about theoretical instances where the "best" design would have the logic live in bevy_reflect. ↩ ↩²

2. This isn't to say that we have never added Bevy-specific code. It's just that we've also had it in the back of our minds to keep it general enough that people could use it outside Bevy, which has affected how we build bevy_reflect. ↩

[cart]

Is this a gamedev-focused reflection API meant mostly for users of Bevy (or maybe even other game engines as well)?

I think this is the move. Facet and the upstream Rust reflection WIP will handle the general cases more effectively. I think we should focus on being opinionated, lean (fast to compile, takes up as little space in the binary as possible), fast, and easy to use for apps and games. This is still a "general" / non-bevy area, but it is a more specific space than "the go to Rust reflection library". I think the ship has sailed on that one.

Do we want custom attributes

Yes

Do we want a way to attach ECS or UI data to fields?

I think anything that ties ECS to fields should be expressed as custom attributes, or expressed in some higher level framework. I don't think we should focus on tackling this, especially as part of the MVP.

How can we make it easier to hook data into the editor?

I think we already have pretty all of the tools we need here in the current Bevy Reflect. I'm not sure there is muuuuch more to do here, but I'm open to whatever ideas you have.

How can we make it easier to interop with scripting languages?

I think "reflect as scripting language interop runtime layer" isn't likely to be the end game (for performance reasons). I think its more likely that we use it to generate bindings somehow.

The editor and inspector work should really be driving a lot of our design decisions. And by not being as cautious to introduce Bevy-specific code into the crate

Yeah I think we should focus on making it the ideal Bevy reflection layer, at pretty much all other costs.

[MrGVSV]

Agreed!

And you didn't have to answer my rhetorical/illustrative questions btw, but thank you for doing so 😅

[MrGVSV]

Can we look into a nursery program or something for this new architecture? It would be nice if we give it a cycle or two for users to experiment with it as a separate crate before we force them to update all of their reflection logic to something that may have still needed time to cook.

[cart]

I like the idea of a dual-mode option that enables either (or both). I think doing the development upstream is helpful though, and it would allow us to start using the new reflection APIs for upcoming editor work (inspectors, UI, BSN assets, etc).

[MrGVSV]

Yeah we should definitely not do this outside of the existing monorepo.

I think the hard part will be integration into existing Bevy crates while trying not to break anything too badly. But there will probably be a point where we have to just accept that bevy_ecs, bevy_ui, etc. need to fully lean into the new reflection changes.

Until then, though, reducing the immediate breakages and facilitating experimentation would be great!

[MrGVSV]

To those ends, I have been experimenting with a new Reflection API

This will of course be a discussion as well (once we have actual details to discuss). This post is largely just a heads up that I'm investigating this.

@cart would it be possible for you to share snippets of your ideas and/or general design? Perhaps you're already close to finishing up your PoC, but if not, it may be worth sharing your thoughts early in case there's any pushback that would save you from wasting your time on a certain aspect of it.

[cart]

I'll push some stuff tomorrow!

[eugineerd]

We have a ton of codegen for field accesses of various kinds (read-only index, mutable index, read-only string, mutable string) , when we could just store a pointer offset on the reflected field, then have non-monomorphized code for high level field access APIs.

I think cutting down on monomorphization and replacing it with pointer/offset-based calculations is a good decision that should reduce codegen massively without impacting performance much. It would also be nice if reflection api exposed those offsets to the user.

TypePath stores a bunch of different string permutations plus the Vtable for each impl. I think it could just be a type, with a compressed representation that doesn't pack the binary with a bunch of substring variants.

I've actually tried compressing the path before and replacing it with a single string + compile-time computed offsets into it. From what I remember it gave ~1MB savings on native build, but when I tested it on wasm + compression the result was very negligible (because compression handles it very well it seems), so I never went ahead with making it into a PR.

My choice to allow "proxy types" to pretend to be real Rust types resulted in the need for the PartialReflect / Reflect split, introducing unnecessary complexity. We can simplify this a lot if we make these "dynamic value types" a standalone API that works on top of the reflection API

Just wanted to note that currently in inspector workgroup we're experimenting with relying heavily on PartialReflect for abstracting over the source of components data without backing of their real rust types. Hopefully this rearchitecture won't break it?

---

Also, not sure if it's in scope of this work, but supporting TypeInfo that isn't backed by real rust types so that reflection can be better utilized for scripting/dynamic purposes would be nice.

[cart]

Just wanted to note that currently in inspector workgroup we're experimenting with relying heavily on PartialReflect for abstracting over the source of components data without backing of their real rust types. Hopefully this rearchitecture won't break it?

Can you walk me through the dataflow / API usage here? What concrete type are you using as that PartialReflect impl?

[cart]

Also, not sure if it's in scope of this work, but supporting TypeInfo that isn't backed by real rust types so that reflection can be better utilized for scripting/dynamic purposes would be nice.

I think we can and should distinguish between something that is an actual Rust type and something else. I don't think "pretending" that something is a Rust type is going to produce the best designs here. That being said, I'm very on board to support non-rust types / layouts / metadata

[eugineerd]

Can you walk me through the dataflow / API usage here? What concrete type are you using as that PartialReflect impl?

So the idea is that inspector only really works with dyn PartialReflect values, with JsonSchemaBevyType informing the layout of everything in the inspector. This means serde_json::Values from remote, local components backed by actual rust types and (in the future) .bsn components are all represented by dyn PartialReflect in the inspector. So inspector works with dyn List, dyn Struct, etc. dynamic reflect types (from PartialReflect::reflect_mut) and doesn't really have to care about the what the backing type is as PartialReflect::apply will handle actually applying the changes to local values and serialization would handle remote part.

[cart]

We could in theory build a PartialReflect-like API on top of the proposed Reflect API (and still avoid doing a bunch of per-type codegen by implementing them for dyn Reflect), while also allowing for abstracting over arbitrary types.

That being said, I'm still largely on team "link, load, use the bevy data model directly", rather than driving this with BRP json schemas (or trying to treat json Values as the "final form" of input). Under those conditions, we could rely on Reflect / the TypeRegistry directly, because we would know we are working with "real types".

[eugineerd]

That being said, I'm still largely on team "link, load, use the bevy data model directly", rather than driving this with BRP json schemas (or trying to treat json Values as the "final form" of input). Under those conditions, we could rely on Reflect / the TypeRegistry directly, because we would know we are working with "real types".

The problem with this approach is that it works only when compiling from source on the same machine as the target (realistically, cursed workarounds do exist). Running inspector on already compiled games (when QA wants to inspect stuff), wasm or consoles would be somewhat difficult. Of course you can just compile it in and bundle inspector with the dev build, but at that point why should remote inspector exist at all? Also relying on "real types" would mean we can't as easily reuse inspector for .bsn editing (although you might have other plans on this?)

[SkiFire13]

My choice to allow "proxy types" to pretend to be real Rust types resulted in the need for the PartialReflect / Reflect split, introducing unnecessary complexity. We can simplify this a lot if we make these "dynamic value types" a standalone API that works on top of the reflection API

Are we planning to have these "dynamic value types" implement the Reflect trait as well? I feel like we'll go back to where we started if so.

[cart]

Are we planning to have these "dynamic value types" implement the Reflect trait as well? I feel like we'll go back to where we started if so.

Not in the way that they do today. They could implement Reflect, but it would reflect their actual structure. They wouldn't "pretend" to be something they are not. Instead, they would have their own logic for doing things like applying themselves to reflected types.

[tacuna]

Might be worth it to take #24561 into account in the design