Create "usage examples" category of first-party Bevy examples #2131
Conversation
alice-i-cecile
added
C-Feature
There was a problem hiding this comment.
In risk of opening up a big bikeshedding party, I suggest adding an extra constraint to game examples: use the plugin organization pattern
This is by now tried and tested by many members of the community. It's not really thaaaat useful for frameworks or crates, so you tend to not see it often when perusing your dependencies, but it's really, really helpful in organizing actual games.
I say this because I know that if I'm upstreaming a tiny game example, I'm definitely going to try and use this pattern, and it may be nice to just start using it for all game examples for consistency. I've also helped many learners on Discord that had problems with figuring out how to organize themselves beyond "put everything into one or two files", and quite a few of them wished that Bevy itself had taught them this pattern sooner, perhaps in examples.
Again, I know this is very opinionated, I know others disagree on the usefulness of this, and we can also let different game examples show different styles of organization, that's fine too :) In that case, it would be good to explicitly allow for that in this document.
Just wanted to open this potential can of worms rather sooner than later.
| each of which have their own goals and subfolder: | ||
|
|
||
| 1. API examples: clearly demonstrating a single feature or group of closely related small features. | ||
| 2. Usage examples: teach users opinionated patterns for accomplishing common game development tasks. |
There was a problem hiding this comment.
YES please to more opinionated stuff! I think Bevy has in the past shied away from teaching very useful stuff in fear of being too opinionated, so addressing this is the right step imo
There was a problem hiding this comment.
Not a contributor so sorry for spamming, but: Yes to opinionated examples! Just as a user/beginner I think it's important to be told when something is opinionated, and if it's a footgun, or if it's just a good practice with other, potentially good alternatives.
| 1. API examples live in `examples/api`, then subdivided by engine category. | ||
| 2. Usage examples live in `examples/usage`, then subdivided by domain. |
There was a problem hiding this comment.
Not sure the distinction between these two is clear to newcomers, maybe some better names can be found?
There was a problem hiding this comment.
Yeah, bikeshed welcome on this!
There was a problem hiding this comment.
I also think "patterns" works for smaller examples showcasing a single concept. Maybe even "snippets" or "parts". I also think that for these small examples, somehow linking them in the module-level docs of what they're shocasing would be neat, but that is probably out of scope for this. well, except maybe that api/pattern/snippet examples could be placed in folders matching the module hierarchy?
| 4. Stress tests live in the root level `stress-tests` folder. | ||
| 5. Testbeds live in the root level `tests` folder, subdivided by domain (e.g. `3d`). | ||
| 2. Each example should consist of exactly one `.rs` file, except where assets or shaders are required. | ||
| 1. Game examples are an exception to this, and should be structured as self-contained small projects with a realistic file and module structure. |
There was a problem hiding this comment.
This was a huge reason for why I didn't seriously consider contributing a tiny game before, so this is very welcome :)
| Usage examples can be more opinionated, and may demonstrate multiple possible approaches to the same problem, explaining the tradeoffs involved. | ||
|
|
||
| Game examples are much more expensive to maintain, and should be used sparingly. Each game example should demonstrate Bevy's capabilities in a new genre or style of game, while being simple enough for new Bevy users to follow and get excited about. | ||
| Polish is important here: these are often a new user's first impression of the engine, although it must be balanced against added complexity. |
There was a problem hiding this comment.
Are game examples allowed to run only well on native, or should they all be just as usable on Wasm?
Asking because on Wasm
- playing music is generally very quickly very choppy, so it's hard to add polish there without some advanced hacks
- locking and unlocking the cursor behaves very unintuitively, meaning that any first person examples would have to include weird hacks for that (I can elaborate if needed)
There was a problem hiding this comment.
WASM support is a nice-to-have. Ideally we should fix both of those long-term.
Definitely agree with using plugins, neutral on fn plugins vs dedicated structs. That can wait for follow-up IMO: "realistic structure" covers "games should use plugins". |
|
Then that's good enough for me, as one is just a shorthand for the other :) |
|
Another point: what is the guideline on starting the example documention with |
| These should be focused on realism, building out the minimum required to demonstrate that they actually solve the problem at hand. | ||
| Usage examples can be more opinionated, and may demonstrate multiple possible approaches to the same problem, explaining the tradeoffs involved. | ||
|
|
||
| Game examples are much more expensive to maintain, and should be used sparingly. Each game example should demonstrate Bevy's capabilities in a new genre or style of game, while being simple enough for new Bevy users to follow and get excited about. |
There was a problem hiding this comment.
How much should game examples repeat important information that is already provided elsewhere? For example, every first person game should imo have a separate view model and world model for accessibility reasons, since Bevy cares a lot about accessibility.
Is it enough to add a comment on that part of a game example that says "this is important for accessibility, see this other example here for an in-depth explanation"? Or should it try to be entirely self-contained?
There was a problem hiding this comment.
Cross-linking in various forms is fine :)
| 4. Stress tests live in the root level `stress-tests` folder. | ||
| 5. Testbeds live in the root level `tests` folder, subdivided by domain (e.g. `3d`). | ||
| 2. Each example should consist of exactly one `.rs` file, except where assets or shaders are required. | ||
| 1. Game examples are an exception to this, and should be structured as self-contained small projects with a realistic file and module structure. | ||
| 3. Assets live in `/assets`. Try to avoid adding new assets unless strictly necessary to keep the repository small. Don't add "large" asset files. |
There was a problem hiding this comment.
How big are game examples allowed to get? Fox example, textures and normal maps are not strictly necessary, but are part of polish. Is there some file size we should aim for, e.g. every example game is allowed to bring in up to 5 MiB of new assets?
Or should game examples try to get by with only using pure color StandardMaterials?
Or is there some kind of shared texture library we can commit once and let all examples draw from those?
There was a problem hiding this comment.
This is one of my biggest concern with allowing that style of example. Almost every PR I've seen that wanted to add something like that came with adding a new texture or asset. This isn't sustainable long term.
There was a problem hiding this comment.
Strongly agree, and I've added clarification to this effect in a later commit.
I think there might be a little more nuance to it than plugins vs no plugins. Imo where the plugins are located, and what they're abstracting away is important to the discussion. Semi structured thoughts :)
Imho examples are the most practical aspect of documentation, and where users will often look first when they're "just trying to get something working". Hiding complexity or details in other files/crates can do a disservice to the reader as they're receiving an incomplete picture. Examples don't need to look pretty, they should give the reader the information needed to achieve something in the most direct and simple way possible. |
For the rest of your points I agree in the case of regular examples. My comment is specifically about example games, which I would assume are fine to optimize for IDE usage and are less "how do I do this specific thing" and more "how do all of these separate things come together to form an entire game?" So for me, a usage example, per this PR, should put the friction of setting up details front and center, while a game example should show how to get the actual game done while not getting lost in details. |
|
Yea I guess the size and necessary complexity of the "example" will dictate what makes sense where. I'm still a little fuzzy on what would qualify for the "usage examples" or "game examples", and if this PR is only for the game examples, and where do we draw the line? Most practical examples won't need a full game to demonstrate them, split screen is a great example. How big would these game examples be? Breakout is 400 lines, though I can easily imagine a few thousand lines for larger examples like a basic minecraft async voxel generation example, especially if there's a lot of comments. It could even make sense to have those big examples be their own crate, so they can specify their bevy features, assets etc directly and you could just build the example or copy it's whole directory out of the bevy examples and run it standalone (aka as a starting point). Though I haven't thought that through too much. It would be the "most realistic" version. I'm wary of discussing hypothetical scenarios, or those from different contexts like the quinn example much more. Would much prefer if we had short descriptions of a handful of these game-examples so we could consider these points in the context of how they would be used. |
|
Good point! I personally had in mind potentially coding a first person shooting gallery with targets moving around, where you try to hit as many as accurately as possible in a time window, after which you get a score board. That example would include a nicely designed level, so some vegetation, some buildings, etc. as a (noninteractive) backdrop, as well as animations and sound effects. There also needs to be a pause menu that allows you to change the mouse sensitivity and FOV for accessibility. Again, this is just the first idea that came into mind and I haven't thought any of this through. @alice-i-cecile is this about the right scope? Or is it already wayyy to much? |
There was a problem hiding this comment.
I think the examples directory is a particular strength of Bevy's ecosystem and I'm very happy to see interest in expanding it. I constantly tell people the examples directory should be their first stop.
Note
I feel like I have to disclose that I do make income from educational content, some of which is Bevy related. I think that's mostly generally known but just in case someone reading is unaware.
That said, there is a significant cost in terms of review and maintenance. I've have seen real contributors express explicit sentiment that they aren't pursuing a PR because they don't want to update the examples.
Its also worth noting that even the current examples aren't kept up to date with new APIs. I say this mostly to air the maintenance/review burden, not to say the examples are bad in any way. A good example right now is that the UI examples specifically have largely not been updated to use the children![] APIs, which is one of the more useful locations to teach that API. At the current pace of PR review, updating the directory will take months.
I fear that "opinionated" code organization/style conversations will devolve into bikeshed conversations quickly. We've already started off the very first comment in this PR with a self-described bikeshed topic that is probably getting as much or more discussion than the PR contents.
That is all to say, I feel like maintaining these examples is basically going to turn into a full time job for someone. Creation, maintenance, review, decisions around what actually fits or doesn't, and seemingly pushing into "how is this serialized as useful a learning path" from the description here.
To add some context/color for maintenance for "full game" examples, I'm currently in the middle of scripting workshops for about 5 games for 0.16 (2048, block breaker, snake, minesweeper, flappy bird). These end up being 500-1000 lines of code if you don't include anything strictly unecessary (In my experience people often skip/don't want to see UI/menus/etc for example). These examples should also probably skip menu systems unless a menu system is the point of the example.
Games that include significant non-bevy-related code should probably also be excluded. ex: 2048 requires writing the board-shift logic generically (or in 4 directions) and that's probably not useful learning material for bevy use cases when compared to the maintenance.
The most common thing I run into is a missing bevy feature that requires an external dependency. For example, Asteroids is almost completely doable in Bevy without dependencies, but as a new user you have to make a choice between switching to Avian or not just for a triangle collider for the ship. (IntersectsVolume supports circle/sphere and rect/cube afaik). Bevy relies on its ecosystem heavily currently (physics, particles, etc), so exluding ecosystem crates speaks to the limited scope for the examples.
It would be nice if (broadly speaking) every time there was a helper/util or similar created for one of these games, if an issue was filed to figure out how to eliminate/upstream that helper. Constructing custom abstractions (ex: SpawnObserver) shouldn't be a focus of these examples.
Rendering use case examples are often verbose but I think that's widely known. I've stopped trying to PR new rendering use-case examples because they've been denied in the past. I wonder when/which Rendering examples would be ok to PR to this new directory.
Overall, what's written here seems great. I wonder how we'll maintain it over the long term (it seems like a job role in the foundation one day) and where we expect wider ecosystem learning material to fit. I try to make sure the material I create outside of the repo complements what exists in Bevy's repo/docs rather than repeat it so its helpful to have these kinds of goals written down so I can plan that work.
| 2. **Clear:** They must use descriptive variable names, be formatted, and be appropriately commented. Try your best to showcase best practices when it doesn't obscure the point of the example. | ||
| 3. **Relevant:** They should explain, through comments or variable names, what they do and how this can be useful to a game developer. | ||
| 4. **Minimal:** They should be no larger or complex than is needed to meet the goals of the example. | ||
| 1. **Goal-driven:** Each example must have a single clearly stated learning-focused goal. |
There was a problem hiding this comment.
I think this is especially important since small games are a possibility here. "I made an implementation of X game" and "I made an example to teach a concept" are different goals with different maintenance burdens.
There was a problem hiding this comment.
Reading through and dumping my thoughts as I go. I worry it may be difficult to get contributors to think like this. We might end up in a (a) well motivated, (b) polished, (c) complete; pick two situation.
| Game examples are much more expensive to maintain, and should be used sparingly. Each game example should demonstrate Bevy's capabilities in a new genre or style of game, while being simple enough for new Bevy users to follow and get excited about. | ||
| Polish is important here: these are often a new user's first impression of the engine, although it must be balanced against added complexity. | ||
|
|
||
| Full game templates or more complex demonstrations of functionality are also welcome, but to manage maintenance burden these should be submitted to [`bevy-assets`](https://github.com/bevyengine/bevy-assets), as part of our semi-curated collection of community-maintained learning resources. |
There was a problem hiding this comment.
I generally haven't submitted my workshop work to bevy-assets because there is a paid component to them. Should I be putting them there since they extend past this PR's examples? (They often use 3rd party dependencies, etc)
There was a problem hiding this comment.
(Not for me to decide, but personally I think Chris should definitely be allowed to put his paid content there, especially since we want to transition the asset page to an asset store at some point in the future anyways)
There was a problem hiding this comment.
Yes, please feel free to put paid content on Bevy Assets! Supporting a broader community of people making a living off of the ecosystem is part of our long-term vision here.
|
Some great points. Bevy's examples are probably the best official examples of any game engine I know. I've seen I'm not the only one who appreciates that quite a bit. That positive reinforcement likely leads to prioritisation on keeping them compiling, up to date, and covering more areas. Bevy is still quite feature-lite compared to what one might get from a more established engine. I won't get into examples but it's not hard to imagine how a feature that is "just" a node/component/checkbox in another engine would require a decent amount of custom work and often domain knowledge, therefore leading people to ask for examples of how to achieve it in Bevy. And Bevy still has a relatively small (but passionate!) educator community (youtube, blogs, tutorials), which traditionally has filled in the majority of examples and sample projects in other engines. Not to mention API evolution makes older material less usable and often contradictory to current "best practices" (see constant questions about EventReader v Observers in discord 🤣 ). Together all of these points put pressure on more first party examples in the repo and keeping them fresh. But as you said we have to keep in mind the burden it puts on engine contributors and maintainers. There must be more we can do to alleviate the burden. Perhaps examples could be tiered, and non-tier 1 examples aren't required to be updated to merge a PR, instead becoming a "good first issue" style thing to encourage contributors and allow other people to share the work? But I'm just spitballing, I'm sure there are other ideas.
I definitely agree with the sentiment, though (maybe naively) as Bevy matures the rate of API change should slow down as patterns emerge and we start to build upon the foundations more than changing them. Some examples may also be removed and absorbed into the engine as features when they make sense, eg ui/button hover styles. It's hard to state how nice it is to quickly flick to the examples to see such comprehensive and thorough use of the APIs. Other engines often have their flagship first-party new-feature demos no longer compiling 6 months later which is pretty sad which speaks to their priorities and motivations, and not in a good way 😓 . I'm glad the Bevy contributors put the amount of effort they do into the examples, it's one of the ways I feel taken care of as a user of Bevy. |
|
I think all the points raised by @ChristopherBiscardi are very valid and it pretty much echoes my own opinions. Personally, I think we should consider usage example to be in a separate repo and maybe even only track the last released version of bevy. This could allow different standards for review and it won't block PR authors trying to work on a new feature. Once we are close to the release, it would also make for a good benchmark of the migration guide to update all those usage examples. It will also help with keeping asset bloat separated from the main repo. We still need a long term solution for that, but this would help in the short term. |
Yep, pushing this sort of problem to the forefront of the minds of maintainers and contributors is part of why I want to move in this direction. Bevy cannot and should not do everything, but in the long-term third-party dependencies should be for saving work, advanced users or replacing an existing module, not required for core functionality (particles, physics, action management, UI widgets...).
Agreed: my kingdom for a budget to hire someone to do docs full-time. That said, I think this is a critical next step for adoption: we're getting there in terms of features, but our perceived quality and learning curve is still too low.
I'm strongly against this. I understand the frustration and concerns here, but we a) need to be able to spot migration and regression problems immediately and b) we can't afford to pile on end-of-cycle work. End-of-cycle work is extremely hard to distribute and painful for maintainers in general, and leads to near-stoppages of productivity for the entire rest of the engine. It would be particularly painful here, as updating the Bevy version depended on by these examples would either need to be done in one mega-PR, or merge code with examples in broken states. If the rendering SMEs are united in "we can't afford to do this yet", I can agree to that as a temporary exemption while we address technical debt and boilerplate. But other more gameplay focused examples are much easier to keep up to date, and other areas like assets are sorely in need of more realistic examples for both learning and testing.
I agree that we need a real solution for this. We should avoid adding new assets to our examples until this is resolved. |
|
I've added a dedicated section on asset usage inside of examples in 6dcac00. While I am very much discontent with that as a long-term solution, it's good to communicate the current rules, and also clarify for reviewers of this PR that I am not currently proposing changing them. I expect that many valuable usage examples (especially in audio, rendering and animation) will largely be blocked by bevyengine/bevy#13875, but that's another can of worms to solve, and something that I know @mockersf has plans for. |
My view here is that the standard for updating examples in PRs is "all examples must continue to work", which is critically distinct from "all examples must be idiomatic and fully up-to-date" :) Something like the addition of observers or required components can be moved over slowly. We need to ensure that viable migration paths exist, code paths don't quietly rot, and that the examples remain usable learning material. |
This is a serious bug: can you check the issues and PRs on this repo please? |
It might have something to do with #2098 not yet being merged, but I'm not certain. |
|
Either along this effort, or as a follow-up, i think it would be good to re-order how examples are categorized on the homepage. Specifically, i think in some way the most complete, best looking examples should come first. Be that just by ordering the "game" examples above others, or by introducing "featured" or "favourited" examples which are hoisted above all others, it's just not very good optics having to scroll past pages of default-grey background examples showing a single sprite, a basic scene, etc. Its a thought i've had for a while, but its not something i wanted to make an issue for without knowing the bigger picture, but i can understand if this should be a follow-up issue as it may not be too relevant for the considerations in this PR. |
There was a problem hiding this comment.
Strongly needed. User-driven examples like this would be a huge step forward. Broadly in favor. Have questions about how we get from here to there.
Getting people to write more usage examples and fewer API examples seems like a cultural shift that will take some effort to effect. I guess the plan is to sort of start small and hope it catches on?
Actually I think it may be a bit tricky to identify interesting and useful usage examples. But once identified, I imagine many examples could be implemented by junior devs (with some guidence). So maybe we should start collecting a list of potential candidates for people to flesh out? An inventory system UI with various item types maybe (people often seem to ask about that).
Pretty much all the existing examples will become API examples, yes?
| 2. **Clear:** They must use descriptive variable names, be formatted, and be appropriately commented. Try your best to showcase best practices when it doesn't obscure the point of the example. | ||
| 3. **Relevant:** They should explain, through comments or variable names, what they do and how this can be useful to a game developer. | ||
| 4. **Minimal:** They should be no larger or complex than is needed to meet the goals of the example. | ||
| 1. **Goal-driven:** Each example must have a single clearly stated learning-focused goal. |
There was a problem hiding this comment.
Reading through and dumping my thoughts as I go. I worry it may be difficult to get contributors to think like this. We might end up in a (a) well motivated, (b) polished, (c) complete; pick two situation.
| [Examples in Bevy](https://github.com/bevyengine/bevy/tree/main/examples) in Bevy can be categorized into three distinct categories, | ||
| each of which have their own goals and subfolder: | ||
|
|
||
| 1. API examples: clearly demonstrating a single feature or group of closely related small features. |
There was a problem hiding this comment.
I think we'd agree these are objectively the easiest to write. How are we going to encourage people to do the harder two, short of getting them all in a room at a con?
There was a problem hiding this comment.
I don't think we have to encourage that? We already have people that want to submit usage examples and this makes it more structured, but I don't see why that implies prioritizing those.
| 5. Testbeds live in the root level `tests` folder, subdivided by domain (e.g. `3d`). | ||
| 2. Each example should consist of exactly one `.rs` file, except where assets or shaders are required. | ||
| 1. Game examples are an exception to this, and should be structured as self-contained small projects with a realistic file and module structure. | ||
| 3. Assets live in `/assets`, organized by kind, rather than by example. |
There was a problem hiding this comment.
Are we at all concerned about the asset needs of the small game examples stretching the abilities of git?
There was a problem hiding this comment.
Ah, I see this is addressed later.
| 7. Examples should not share common "utility" logic: if you feel this is warranted, improve the engine instead! | ||
| 1. Similarly, try to avoid incidental complexity and abstractions. Find a simpler way for now, and work to create these tools and resolve this tension in the engine itself. |
There was a problem hiding this comment.
I'd want to contribs to file issues for pain points like these which they encounter during example development.
|
|
||
| ## Platform support | ||
|
|
||
| By default, every example must work on our desktop platforms: Linux, Windows and MacOS. |
I'm not sure I agree with the "fewer API examples" part. We should still encourage api examples for new apis because they are still super valuable. The one thing this could allow is to make the api examples leaner and remove things that were done to make the example look better but maybe less straight forward, but not write less of them. |
|
Exciting to see this! (Just had the time to sit down and get through all the discussion) On maintenance burden: examples are not load-bearing to the engine, and I think it makes sense to considering at least archiving an example if it is causing problems for maintenance. A future pitfall with expanding / changing the scope of examples might be imagining that examples should become more iterative (walking through changes in problem solving in a Jupyter notebook style way) than descriptive (we're doing it this way, and here's how and a bit of reasoning for why)1.
Seconded. I think some can be considered superfluous, but not that many. A lot of the examples make for a really good "W3schools" style stripped-down intro to bevy in terms of showing off API in-practice. But not to contradict my first point, it might be wise to think about when it makes sense to retire an example, even if we're not over-eager to. Footnotes
|
Clarify README organization and change ordered list to unordered list
alice-i-cecile
added
S-Ready-For-Final-Review
|
This has been thoroughly reviewed, and discussed by dozens of contributors, both online and at RustWeek 2025 :) There has been broad consensus that something along these lines is desirable and important to prioritize. I'm going to go ahead and merge this now, and unblock the work of our contributors here at the Bevy Unconf. |
# Objective We want to extend our examples with a new category "usage" to demonstrate common use cases (see bevyengine/bevy-website#2131). This PR adds an example of animated cooldowns on button clicks. ## Solution - New example in "usage" directory - Implement a cooldown with an animated child Node ## Testing - I ran this on Linux - [x] test web (with bevy CLI: `bevy run --example cooldown web --open`) --------- Co-authored-by: Thierry Berger <[email protected]> Co-authored-by: Ida "Iyes" <[email protected]>
As Bevy grows and matures, the need for better documentation grows with it. While we've gotten our API-focused documentation to a fairly good state with our existing examples + rustdoc, that only answers the "what does this API do?" question.
Users, especially experienced game developers, will commonly ask "how do I a specific task in Bevy", and will come up empty-handed. Instead, they're told to read or community-maintained resources, ask questions in our community spaces,or just "figure it out". While these can be excellent strategies, they're inefficient, commonly outdated, and are a missed opportunity to showcase how simple and effective a lot of these common tasks are in Bevy.
I've opted to build on the excellent work by @fallible-algebra over in #1949 to propose a new category of example aimed at filling this goal, while cleaning up and clarifying some guidance about our existing examples and example-like code.
From the perspective of the engine developer, this category of example represents a non-trivial maintenance burden, especially, as @IceSentry has pointed out, in terms of rendering code due to weaker abstractions and higher difficulty during refactoring. That said, I feel that this is ultimately valuable to engine devs as well, because these examples:
This PR is only the first step: the existing examples and tooling will need to be refactored to match this proposal (e.g. the split screen example is an existing usage example), and if this proposal is accepted, I would expect to see a substantial number of new added examples demonstrating common tasks.
I'm opening this PR now, in the hopes that it can be polished, discussed and accepted in time for May 16th, the Bevy Unconf at RustWeek 2025: this refactoring and example writing effort would be a great fit for a large group of in-person contributors of all skill levels :)