Mark ghost nodes as experimental and partially feature flag them

[alice-i-cecile]

Objective

As discussed in #15341, ghost nodes are a contentious and experimental feature. In the interest of enabling ecosystem experimentation, we've decided to keep them in Bevy 0.15.

That said, we don't use them internally, and don't expect third-party crates to support them. If the experimentation returns a negative result (they aren't very useful, an alternative design is preferred etc) they will be removed.

We should clearly communicate this status to users, and make sure that users don't use ghost nodes in their projects without a very clear understanding of what they're getting themselves into.

Solution

To make life easy for users (and Bevy), GhostNode and all associated helpers remain public and are always available.

However, actually constructing these requires enabling a feature flag that's clearly marked as experimental. To do so, I've added a meaningless private field.

When the feature flag is enabled, our constructs (new and default) can be used. I've added a new constructor, which should be preferred over Default::default as that can be readily deprecated, allowing us to prompt users to swap over to the much nicer GhostNode syntax once this is a unit struct again.

Full credit: this was mostly @cart's design: I'm just implementing it!

Testing

I've run the ghost_nodes example and it fails to compile without the feature flag. With the feature flag, it works fine :)

[alice-i-cecile]

@villor can I get your review here?

[JMS55]

Small comment: You don't actually have to add an experimental folder. You can make an experimental module in the parent module, and then re-export the ghost node module's contents under it. This is what we did with other stuff.

[github-actions]

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

[alice-i-cecile]

I think that an experimental folder is a bit cleaner :)

[villor]

I’m glad we are keeping the ghost nodes! What’s an experimental game engine without experimentation 🤓

That’s a neat trick make it non-constructable while not having to change any of the traversal code.

I have no strong opinions on the file structure. Especially when there is only one experimental feature.

Solution looks good to me, spookiness included 🎃

[github-actions]

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

[viridia]

Yes, it's thematically appropriate that ghost nodes rely on phantom data. I can't wait to see the halloween-flavored release notes!

[github-actions]

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

[alice-i-cecile]

Yes, it's thematically appropriate that ghost nodes rely on phantom data. I can't wait to see the halloween-flavored release notes!

I was tempted to just use a boring () internal field, but the spooky synergy was too much to resist :D

[bushrat011899]

I think I have a cleaner solution that avoids the need for a constructor. Otherwise, I think this is a good idea.

[alice-i-cecile]

@bushrat011899 doesn't work :) GhostNode would need to be constructed as GhostNode() instead, which is not any better. The GhostNode symbol when it's a tuple strat is treated as a constructor function in the compiler errors.

[bushrat011899]

Sad my suggestion didn't pan out, I forgot that a tuple-struct can be used like a function. Looks good to go!