Defining a stable core API for better maintainability

[neshume]

Proposal: Defining a stable core API for better maintainability

Description

As a developer using Bevy for project development, I've encountered challenges with maintaining my projects due to the rapid evolution of the Bevy API. While I understand and appreciate the reasons behind the frequent changes (rapid iteration, performance improvements, keeping up with the evolving Rust gamedev ecosystem), I believe that defining a stable core API could provide significant benefits for project maintainability and long-term adoption.

Proposal

I suggest that we consider defining a stable core API that encapsulates the fundamental primitives and patterns that are unlikely to change frequently. This could include things like:

• Colors
• Transforms
• Basic ECS composition and usage
• Core math types and operations
• Key input event handling
• Basic rendering setup and configuration

The goal would be to provide a fixed, well-documented API for these core concepts that developers can rely on across Bevy versions, even as the wider framework continues to evolve and improve.

Potential Benefits

• Improved maintainability for long-lived projects
• Reduced upgrade friction and breaking changes for fundamental use cases
• A stable foundation for learning Bevy and building reusable libraries
• Increased adoption and confidence in using Bevy for serious projects

Potential Approaches

• Carefully designing core APIs with forwards/backwards compatibility in mind
• Providing a separate "core" library with a fixed API, distinct from the main library
• Maintaining thorough documentation and guides for the stable APIs
• Providing detailed changelogs and migration guides for any necessary breaking changes
• Offering a slower-moving, stability-focused release channel in addition to the current cutting-edge channel

Open Questions

• What specific primitives and patterns should be included in the stable core?
• How do we balance stability with the need for ongoing improvement and evolution?
• How do we handle necessary breaking changes to the stable core over time?
• What's the best way to structure and distribute a stable core API alongside the main library?

I'm open to discussion and feedback on this proposal. I believe that with careful design and community input, we could define a stable core that would make Bevy even more powerful and appealing for long-term, serious project development.

Cheers,

Neshume

[Retrodad0001]

But i would suggest after the minimum vertical slice implementation mvp..what that mvp is good discusion. I think at least some editor (i dont need it) but is better for adoption,basic buildin physcs, 2d light,audio and ui. Basic 3d anim and navigation. Asset prperation.. my fear is that we keep updating 3d and the api and try to compete with unreal..

[neshume]

I totally get where you're coming from about defining an MVP and focusing on features like an editor or built-in physics—those are definitely important for adoption and growth.

That said, my main point here was more about the stability of the core API—things like transforms, colors, and basic ECS patterns. These are the building blocks that a lot of us rely on, and having them stay stable across versions would make it so much easier to maintain projects long-term.

;o)
I think Bevy can avoid the whole "compete with Unreal" thing by doubling down on being lightweight, flexible, and reliable. Even if other features evolve (and they should!), having a stable foundation gives everyone a solid starting point.

Cheers,

Neshume

[bushrat011899]

There's still a lot of major changes to the public API being made which would make this kind of stabilisation very challenging. For example, the no_std support I'm adding is technically a massive set of breaking changes, since you now must enable an std feature if you were disabling defaults. Once bsn, relationships, the editor, and probably several other major APIs I'm not thinking of right now ship, maybe there'd be room to stabilise APIs. But right now, there's still debate around fundamentals like whether Resource should just be a component, or if observers should include an on_mutate hook.

[JMS55]

I don't think rendering is ready to commit to any stable APIs. I expect not just the internals to change, but basic stuff like the Mesh, Material, and RenderGraph APIs to get major overhauls at some point in the future. Additionally, every time we upgrade wgpu that's a breaking change.

[BenjaminBrienen]

https://bevyengine.org/learn/contribute/introduction/

Bevy also currently has the following "development process" goals:

• Rapid experimentation over API stability: We need the freedom to experiment and iterate in order to build the best engine we can. This will change over time as APIs prove their staying power.