Teddy Bear Trash Compactor

2025-10-28T00:00:00+00:00

That's the rule of Chekhov's Gun: Have a gun. Now it's been seen, I will have to shoot someone before the end of the play... </blockquote>

If your game includes a teddy bear and a trash compactor, there's a good chance one of your players is going to try to put that teddy bear in that trash compactor. Why? Because it’s a tiny, consequence-free act of pure nihilism. Because they want to see what will happen. Because some people just want to watch the world burn. The why isn't actually important.

I bring up the Teddy Bear Trash Compactor scenario as an example of players making fun for themselves. These sorts of actions are interesting to me, as a game designer, because they are:

specific choices, enacted intentionally and often methodically by the player,</li>
the opportunity for which emerged naturally from the existing game world,</li>
perused despite having no mechanical reward, and no expectation of acknowledgment,</li>
which nevertheless makes the player feel something (wicked glee, shame, curiosity).</li> </ul>
I think games should try as hard as they can to recognize and respond to actions like these. When you put the teddy in the compactor and an NPC nearby goes "(gasp) you're a monster", it’s funny and underscores the emotional impact. I love that shit.
At this point, we could go into Theories of Fun and why interactions like these make games special, but I'm going to save that for another article. This one is about the mechanics: How do you track the state of the game in a way that allows you to respond to stuff like this?
Data Organization & Behavior</h1>
Say you're making a game: You've got some kind of global state, and then you've got a ton of "Game Objects" that might be bits of the map, or NPCs, or items. How should this data be organized? Well, it depends.
You have to consider how that data is likely to be used. What behavior is it going to drive? As we'll see, different types of behavior call for different representations and organizations.
Consistency</h2>
One very common requirement for behavior is consistency. Take physics, for example. The laws of physics, I am given to understand, are pretty much the same everywhere. If you want all your game objects to have the same physics, you generally want to have a single physics implementation. That implementation should probably periodically iterate over your game objects to read and update their physics data.
Following that line of reasoning, we can draw some conclusions about data representation. Storing all the physics data in a big uniform array is probably a good choice. By contrast, giving each game object (or perhaps class of game object) custom physics properties is probably a bad idea. If some of your objects express their inertial moment in different units, or represent their position and orientation using quaternions instead of projective matrices, achieving uniform behavior is going to be harder.
Generally, to get consistent behavior, it's best to have consistent data stored in a consistent place. This is all pretty textbook stuff.
Specificity</h2>
Sometimes though specificity matters more than consistency. My teddy bear trash compactor example is hyper-specific; there's just one trash compactor and just one teddy bear, so consistency isn't a concern at all.
In isolation, you can do whatever you want with inconsistent data. But what if you have several thousand specific state variables? What if they are all different types? At scale, even though it can be wildly inconsistent, highly specific behaviors have their own set of constraints. The main problem is ergonomics. The easier it is to store ad-hoc state, the more you will do so. So highly specific behavior requires effortless data definition and access.
In practice, there is often a trade-off between consistency and specificity. Consistent behavior affects more game objects, so you can afford to use patterns with more boilerplate, which are more complex to set up and maintain. Hyper-specific behaviors have no such luxury, since they may only apply to a single object for a brief moment. They are therefore constrained to patterns that cost next to nothing to set up and use.
Why am I talking about this? Well, over the past few months, I've gradually come to realize that this consistency/specificity tradeoff underpins some of the issues I have with the ECS pattern.
Dial E for Entity</h1>
You're reading a blog about game engine design, so I assume you've heard of an ECS before. If not, ECS is a data-storage pattern often used in games. It's an acronym.

E is for Entity: A key that uniquely identifies a game object.</li>
C is for Component: A type that each game object may have an instance of.</li>
S is for System: A routine that operates on game objects with a certain set of components.</li> </ul>
The ECS pattern is great for consistency. Every system defines behavior, and entities can opt in to behavior by adding a specific combination of components. Theoretically, an ECS also provides composition, with multiple isolated systems all working together to create complex emergent behavior across the various entities they operate on.
These benefits generally come at a cost: tracking the components attached to each entity comes with overhead, and setting up new components and systems often has some boilerplate. And, in my opinion, the typical approach to components tends to get in the way when implementing inconsistent or hyper-specific behaviors.
Naive Example</h2>
Let's look at what it takes to implement Teddy Bear Trash Compactor in my ECS of choice (Bevy</a>).
To start, we'll need some way to identify a the teddy bear and trash compactor game objects. An ECS idiom exists for this called "marker components" (which carry no data).
#[derive(Component)] struct TeddyBear; #[derive(Component)] struct TrashCompactor; </code></pre> We also need a place to store the actual state, which in bevy probably belongs in a "resource" (which are effectively just containers for global data). #[derive(Resource)] struct IsReadyBearInTrashCompactor(bool); </code></pre> This resource will need to be initialized when the game starts (so that we can persist it's state between saves and so on) and that means we'll have to register it in a plugin. The game in question probably already has one, so we'll add it to that. impl Plugin for MyGame { fn build(&self, app: &mut App) { ... app.init_resource::<IsReadyBearInTrashCompactor>(); ... } } </code></pre> Now in a system we can do the actual distance check and update the state resource. impl IsReadyBearInTrashCompactor { fn update( mut self: ResMut<Self> teddy_bear: Single<&Transform, With<TeddyBear>>, trash_compactor: Single<&Transform, With<TrashCompactor>>, ) { let dist = teddy_bear.translation.distance(trash_compactor.translation); if dist < 1.0 { self.0 = true; } } } </code></pre> This will also have to be schedule for execution within a plugin. ... app.init_resource::<IsReadyBearInTrashCompactor>(); app.add_systems(PostUpdate, IsReadyBearInTrashCompactor::update); ... </code></pre> Taken together you get this. #[derive(Component)] struct TeddyBear; #[derive(Component)] struct TrashCompactor; #[derive(Resource)] struct IsReadyBearInTrashCompactor(bool); impl IsReadyBearInTrashCompactor { fn update( mut self: ResMut<Self> teddy_bear: Single<&Transform, With<TeddyBear>>, trash_compactor: Single<&Transform, With<TrashCompactor>>, ) { let dist = teddy_bear.translation.distance(trash_compactor.translation); if dist < 1.0 { self.0 = true; } } } impl Plugin for MyGame { fn build(&self, app: &mut App) { ... app.init_resource::<IsReadyBearInTrashCompactor>(); app.add_systems(PostUpdate, IsReadyBearInTrashCompactor::update); ... } } </code></pre> This is a fair amount of code for a comparatively simple feature! It also introduces a lot of types, which, if you have thousands of similar little interactions, means: slower compile times, difficulty finding relevant things, and so on. It's just a lot of work to put on the compiler for very little benefit. A Modest Proposal</h2> Let me show you another way to write the same thing, from a parallel universe. fn is_teddy_bear_in_trash_compactor(world: &mut World) -> Result<()> { let teddy_bear = world.entity_named("teddy_bear")?.get::<Transform>()?; let trash_compactor = world.entity_named("trash_compactor")?.get::<Transform>()?; let dist = teddy_bear.translation.distance(trash_compactor.translation); if dist < 1.0 { world.set_property("is_teddy_bear_in_trash_compactor", true); } Ok(()) } impl Plugin for MyGame { fn build(&self, app: &mut App) { ... app.add_systems(PostUpdate, is_teddy_bear_in_trash_compactor); ... } } </code></pre> I've just done two things here: Replaced the static marker components with a dynamic name map.</li> Replaced the static state resource with a dynamic properties map.</li> </ul> I think this is big improvement. Compared to the previous, this version is more self-contained. It also uses the type system less (which means potentially faster compiles) and fewer macros. Remember the scale here, with a few hundred marker components, things add up. A few hundred flags could be more than a thousand mostly pointless types, which we now have to manage, and wait to compile. There's also more flexibility here. Names could be defined entirely at runtime, if you wanted. What's The Downside?</h1> What we have sacrificed, going from the first implementation to the second? Correctness. Suppose we change it from a teddy bear to a companion cube, or from a trash compactor to an incinerator. For the first version, the compiler is able to ensure that we make the change uniformly. In the second version, it's on us to make sure we update all references to the name correctly. Now, I don't think reducing compiler checking here is a huge loss. There are some things the compiler just can't check, and you wouldn't want to have it check: Content. Having to define content, like dialog trees, within the Rust type system is cumbersome and annoying.</li> Scene Editors. Since marker components are compiled into the app, they are more complex to embed in scenes. Name strings are easy for editors to work with.</li> Scripting. Using a simple key-value store instead of a resource makes it trivial to read and write from scripts.</li> Networking. If you're writing a networked game, encoding the organization of game state dynamically rather than within the type system can allow the server to send custom state to the client.</li> </ul> There are just so many things you can do with dynamic patterns like these. What you lose in correctness, we make up in flexibility and interoperability. My issue with many ECS implementations, which I alluded to earlier, is that they often do not include dynamic patterns or even discourage them. There is probably a slight selection bias among users of ECS-based engines (and especially Bevy), which draws people who like type-checking and correctness and large, consistent systems. To some extent, I think those same people tend to dislike exceptions, inconsistencies, ad-hoc behavior, and specificity. It's fine to dislike these sorts of APIs, especially if your work doesn't require them. But I think they are still important things for an engine to support. Engines which discourage these patterns rob their designers of the ability to make consistency/specificity correctness/flexibility tradeoff decisions themselves. And focusing on static correct consistent patterns can make it more difficult to implement certain things. All the categories I listed (Content editing, Scripting, Networking) have historically been weak points for Bevy. Perhaps it is because we are simply using the wrong patterns. Stay Tuned</h2> Some of you may still be skeptical, and that's fine. This post ended up being a lot of me "telling" and less "showing". In my next post, I'm going to show a more concrete example of how all this runtime-dynamic stuff can be used to implement a pretty sweet rules-based response system (modeled off the Source Engine dialog system). Until then, here's an omen of things to come... (criterion TeddyBearInTrashCompactor (is_teddy_bear_in_trash_compactor == true)) (rule (ConceptInteract Ally NpcIdle TeddyBearInTrashCompactor) (YouMonster)) (rule (ConceptInteract Ally IsLisa NpcIdle TeddyBearInTrashCompactor) (NeverLikedBears)) (response YouMonster list (line "(gasp) you monster!")) (response NeverLikedBears list (line "I never liked bears anyway.")) </code></pre>

I'm Giving A Talk In Boston 2025-09-10T00:00:00+00:00 You Americans, all you do is talk, and talk... </blockquote> The Boston Rust meetup group has invited me to deliver a short talk on multi-threading games using Rust</a> and Bevy</a>. Topics will include: How Rust can help (and hinder) game development.</li> Bevy's aggressive approach to multi-threading.</li> The design and implementation of a new ultra-low-latency scheduling library.</li> </ul> Where: 285 Summer Street, Suite 101, Boston, MA. When: Tuesday, September 30th. Doors open at 5:30 p.m. Talks start at 6:30 p.m. </code></pre> For more information, see the official meetup page</a>. If you somehow (a) read this blog (b) live in the greater Boston area and (c) do not already know me, please do come and introduce yourself! Working In Groups 2025-08-30T00:00:00+00:00 Wann hast du Geburtstag? </blockquote> A little over a year ago, Bevy introduced a new "Working Groups" process, as part of an effort to overcome some of the issues we were having with RFCs. Cart discussed this briefly in the 5th birthday post</a>, but I'm going to go into more detail about why we made this change, the ways I think it has succeeded and failed, and what conclusions I think the maintainers of other projects might draw from our little experiment. A Problem Of Scale</h2> Many successful open source projects suffer from the same problem: Massive contributor base, minimal structure. Take Bevy as an example. I believe the last time Charlotte</a> counted, we had somewhere around 60</code> regular contributors (people who merged at least ten PRs per year). That's actually pretty good for a project of Bevy's size, but it only represents a tiny fraction of the larger contributor base. Apparently Bevy merged 9,795</code> PRs last year, from somewhere upwards of 350</code> different contributors. Yowza! That's a lot of engineers. Imagine if Bevy were a company. With that number of developers, it would certainly have multiple isolated departments run by their own vice-presidents, an army of middle-managers, maybe a sales team, and probably several project managers. But Bevy isn't a company. It has a project lead, one full-time staff-engineer/engineering-PM, three maintainers, and a loose unstructured confederation and 1200</code> other people1</a> who are, by and large, doing their own thing. Lack of structure isn't inherently a bad thing. Most features and fixes are uncontroversial and can be decomposed into bite-sized tasks that a single engineer can complete more or less on their own. As long as bureaucracy and friction are kept comparatively low, it's possible to achieve really high throughput for this sort of work. Everyone just does whatever looks most interesting, more or less on their own. It takes some light community organizing and speedy code review, but the work gets done and the project keeps trundling along. However, not everything fits neatly into the "single-developer" mold. Invariably, projects appear which are too big or too controversial for a single developer to tackle. All the really important aspects of software development — standards writing, API design, and broad system architecture — inherently need some degree of collaboration and consensus-building. Work like this calls for a different set of tools. More often than not, this boils down to some sort of RFC process. More often than not, this is a mistake. Everybody Gets RFCs Wrong</h2> Now, I love a good RFC. But I have a problem with how most people approach writing RFCs, and how most RFC processes are administered. All RFC processes — Python's PEPs, BitTorrent's BEPs, Bevy, and Rust's RFCs — are to some degree modeled off the original IETF RFC series. Here's how that process was originally described. These are excerpts from RFC 3</a>, drafted in the summer of 1969: The content of [an RFC] may be any thought, suggestion, etc. [...] Notes are encouraged to be timely rather than polished. Philosophical positions without examples or other specifics, specific suggestions or implementation techniques without introductory or background explication, and explicit questions without any attempted answers are all acceptable. The minimum length for [an RFC] is one sentence. </blockquote> These standards (or lack of them) are stated explicitly for two reasons. First, there is a tendency to view a written statement as ipso facto authoritative, and we hope to promote the exchange and discussion of considerably less than authoritative ideas. Second, there is a natural hesitancy to publish something unpolished, and we hope to ease this inhibition. </blockquote> Unfortunately, some fifty years later, many modern RFC processes seem to have forgotten these guidelines. Getting the first draft of an RFC published is usually an exhausting, sometimes excruciating process. Incomplete thoughts or designs, documents that collate useful information without making recommendations, and unanswered questions are often not accepted. Take Rust as an example. Rust has, on the whole, a healthy skepticism of RFCs submitted by project newcomers. It is not a very open process. The Rust project also apparently uses something called a "pre-RFC" to vet documents before they reach the RFC stage; something akin to an RFC, but without the procedure. These "pre-RFCs" are, as far as I can tell, coupled with prototype compiler implementations, and shuffled around for informal review until deemed "ready for general consumption". This protective attitude is justified by the observation that [...] once an RFC has been published, it actually very rarely evolves significantly, because the author becomes entrenched in the proposal they've made. 2</a> </blockquote> I don't begrudge Rust for adopting these procedures; they are a small team of experts navigating the development of a language and compiler that are at once extremely popular and extremely complicated. Aggressive vetting is obviously required. Still, to me as an outsider, this sounds like a red flag. RFCs are "Requests For Comments" after all. They are intended to stimulate discussion, and to be updated based on those discussions until consensus is reached. If authors are regularly becoming "entrenched" in their existing views, that is, in my layman's opinion, a bad sign. Bevy had entirely different issues with its RFC process. Writing an RFC took ages, getting it through review took ages, and then getting it actually accepted took ages. Partly this was because reading and reviewing an RFC is a heck of a lot harder than reviewing code, and partly it was because it wasn't clear whose job it was to make the "yes/no" call. The result was burnout. We got some great RFCs, but usually the author was so exhausted after getting the design approved that they couldn't manage the implementation. When things ended up being implemented, it often was much harder than expected, or the design had to be fundamentally altered. A few years on, most of Bevy’s accepted RFCs are now either not completely implemented or outdated. These problems are not universal. It's possible you've participated in an RFC process that didn't suffer from these issues (in which case, please reach out, I'd love to hear more about it). But I'm willing to bet most people with any experience with RFCs will empathize with the issues I've described. Many RFC processes have issues like these. And almost always it's because they have neglected an important aspect of what made RFCs make sense. If you haven't guessed it yet, that thing is the "Working Group". It Was Always Working Groups</h2> RFC 3</a>, which I quoted in the previous section, doesn't talk about RFCs. It uses the term "NWG Note" instead, because originally RFCs were notes circulated to six members of the IETF Network Working Group. I think this is super important context. Originally, an RFC was literally a "request for comments from the other five guys in the working group". The members of the NWG all knew each other. They were working on similar stuff, and they started the RFC series to track and discuss their ideas. If you take process out of a collaborative group setting, the whole thing kind of falls apart. All of the Bevy RFCs had basically a single author, as far as I can tell. They mostly weren't writing for their peers, and they always didn't have buy-in before they started writing. Without collaborators, the main source of comments on RFCs was the maintainers, and often reviews could be quite sparse because of the difficulty of the material. To the degree that any RFC was successful, it was due in large part because other members of the community were willing to spend the time to become deeply involved. And that didn't always happen. The lack of collaboration is, I think, why authors tended to burn out, and why RFCs tended to languish without implementations. Honestly, I find this solo approach to RFCs very odd. After all, one of the neat things about working groups is that they are self-organizing. They spring up naturally after you get enough engineers in a room together, like mushrooms after a rain. People with similar interests naturally seek each other out if given the opportunity, and once two or three like-minded contributors get to talking, it's only a short step to making plans and collaborating. So I'm surprised that we didn't see many “homegrown working groups" submitting proposals through the RFC process. Outside the RFC system, we see them everywhere! Many of Bevy's complex or controversial features were pushed forward by a team of three or four dedicated contributors, who could all review each other's work and collaborate. The New Process</h2> After much discussion, we settled on a new process that would re-emphasize the importance of collaboration on complex features, but which would allow maintainers to steer (or veto) the direction of the work. You can read the full set of guidelines here</a>, but I will also briefly summarize them: To form a new working group, three people must put together a minimal proposal (a few sentences) and ask for maintainer ascent.</li> If accepted, the maintainers give them a dedicated space to communicate (a Discord thread), and the working group is tasked with developing a design document (essentially an RFC) and submitting it to the maintainers.</li> If the design doc is accepted by the maintainers, they may proceed to implementation without having to justify their design choices during code review (expediting the process).</li> Anyone can join or leave the group at any point, and there is no appointed leader. The group is encouraged to write down as much as possible, so it is easy for new members to join.</li> Groups are formally disbanded by the maintainers after the implementation is completed, there are fewer than three active participants, the work stalls, or the direction is vetoed.</li> </ol> We hoped this process would: Force people to check in with maintainers before starting work.</li> Allow the maintainers to limit the number of initiatives underway at once.</li> Help distribute the load over more people.</li> Ensure that there are always two people capable of doing internal peer review.</li> Allow design documents to change and shift during the implementation phase.</li> Direct bright-eyed new contributors to experts who can put them to work.</li> </ul> There was a second change that, in retrospect, was no less important. Previously, all our design documentation lived in GitHub discussions or as Markdown files within the RFC repo. But shortly before introducing working groups, we also created a quasi-official HackMD Org</a>. HackMD is Google Docs for Markdown, and though it wasn't explicitly specified, most working groups ended up relying on HackMD to manage their associated design documents. What Went Well</h3> We've now been using this process for well over a year and have hosted 27</code> working groups in that time. 5</code> were for releases or game jams.</li> 3</code> were otherwise process or community-focused.</li> Of the remaining 19</code> feature-oriented working groups: 8</code> are effectively completed (curves, color, picking, no_std, text, bsn, audio, relations)</li> 2</code> were closed as unsuccessful (render-graph, decoupled-rendering)</li> 2</code> have temporarily stalled due to lack of contributors (ptr, transforms)</li> 7</code> are ongoing (cli, hotpatching, wesl, tilemaps, nonsend-data, observers, rendering-refactor)</li> </ul> </li> </ul> Which means that, of the 19</code> feature-oriented working groups, 15</code> either ended up completed successfully or are on track to be completed. When I ran a similar tally in April, this stood at 11</code> groups out of 14</code>. If we only consider the definitively ended groups, it's 8</code> successes and effectively 2</code> failures (I expect the two stalled groups to get back into motion soon). These numbers are pretty encouraging: more than half the working groups we started last year reached a definitive conclusion, and three-fourths were successful. By contrast, of the 74</code> Bevy RFCs, 32</code> have stalled with no expectation of completion and 33</code> were closed without being accepted. Only 9</code> were ever accepted, and 5</code> took two or more years to implement. It's worth noting that Bevy's RFC usage was already in decline before these procedural changes, and these lackluster RFC success numbers looked more or less the same a year ago. One thing I was not expecting was the degree to which HackMD has displaced the RFC writing process. It ended up being essential to the working group process and has led to a substantial increase in the amount of writing done by the community as a whole. Our HackMD org is now filled with content that would fit very nicely under the criteria of RFC 3. Much of it is loosely structured or incomplete. But timely information, even if partial, is preferable to none. And incomplete work is, in this case, an invitation to collaborate. I think HackMD has largely freed us from the friction, formality, and stuffiness of RFCs. As a result, the community has written a lot of really great stuff! The org now has 59</code> members (and 25</code> non-member contributors) and has produced 72</code> notes. That's close to 74</code> RFCs Bevy received over the last five years. So in that regard, I'm incredibly pleased. The new process has met many of its stated goals as well: The maintainers have said "no" to working groups that it wasn't time for.</li> Maintainers have been able to conclusively halt work they disagreed with.</li> Proposed working groups have failed to form due to lack of interest.</li> Many working groups incorporate significant work from multiple core contributors.</li> New contributors do join working groups and often make meaningful contributions.</li> </ul> Most importantly: the new process does seem to have reduced burnout and fostered healthy and sustained collaborations. The "Better Audio" working group, for example, has been quietly trucking along for more than a year now, with multiple brilliant contributors regularly producing amazing work, and no signs of slowing down. Is this because that working group is full of amazing and uniquely talented contributors? Yes! But I hazard it's also because it's become Bevy’s dedicated audio-nerd hang-out space. A tiny community has formed around that feature, and it keeps people motivated to work on it. What's Still Hard</h3> Nothing is perfect, and there are still issues with the working group process. You can't manufacture interest. Some working groups still languish.</li> Rendering tends not to create working groups, and some of the rendering working groups have struggled with participation.</li> We potentially have started too many working groups at once, and our core contributor base may be spread too thinly between them.</li> Several working groups have proceeded directly to implementation, without completing their design documents or getting them approved.</li> </ul> While the working group process feels less formal and heavy-weight than RFCs, it also has a tendency to let boundaries blur. Every group needs at least three active participants to sustain it, but it's hard to say exactly what constitutes "active", or how many groups a single person can reasonably be "active" in at once. The line between the "design phase" and "implementation phase" is also pretty permeable. There's also a degree of permeability between what is and isn't a working group. When I got Charlotte</a>'s opinion on the scarcity of rendering working groups, she pointed out the rendering contributors [...] tend to be pretty well aligned relative to other teams and do a good job building consensus in a more ad-hoc manner" without needing to actually create formal groups for each initiative. [...] It's more about forming small groups in order to execute on some sub-goal rather than generating buy-in through a higher level planning process. </blockquote> This is a good take, and an indication that the formal "working groups process" is still too formal and bureaucratic for some situations. The rendering contributors are extremely well aligned and highly productive, so clearly whatever they are doing is working. Still, I'd still like to encourage them to write more stuff down, and to make their informal groups easier to discover and join. Perhaps there are ways we can change the process to make it work better for them. Maybe Try It?</h2> To summarize, we took an existing semi-dysfunctional RFC process and Shifted the emphasis from the documents themselves to the communities that write them,</li> Gave those communities names, gentle oversight, and spaces to communicate,</li> Made it much easier for them to write and edit documents collaboratively.</li> </ol> People really seem to like the new process; more stuff has been getting written down, more newcomers are able to help with big initiatives, and many complex features are proceeding swiftly from design and into implementation. It has been amazing to see the Bevy community come together over the past year for these 27</code> different initiatives. I cannot wait for the day when — some time in the next year — the first editor working group is officially launched. I'd also be eager to see other open source projects experiment with ways to get closer to the "old school" spirit outlined in RFC 3. I'm counting total historical contributors here. ↩</a> </li> This is a quote of a friendly and helpful explanation workingjubilee</code> posted in response to a newcomer eager to submit an RFC. It's worth noting that Jubilee is a member of the compiler team rather than the lang team, and obviously doesn’t speak for the project as a whole. Still, this framing has kind of stuck in my brain since I read it. There's more context in the original thread</a>. ↩</a> </li> </ol> </footer> Become a Regular Contributor 2025-03-10T00:00:00+00:00 Would you tell me, please, which way I ought to go from here? That depends a good deal on where you want to get to. </blockquote> Any healthy community project attracts a crowd of people who want to help out in a regular sustained way, but don't know where to begin. The Bevy Game Engine</a> gets a lot of these people, which is great. I am a regular contributor to Bevy and am somewhat active in community discussions, and so I'm occasionally in a position to offer advice to people caught in this situation. To make things easier, I thought I'd collect this advice into an article so I can easily link to it. If you did get linked here from Bevy, you should also take a look at the Contributing Guide</a> (which, incidentally, I helped write). If not, the advice I'm going to offer should be generally applicable to most open-source projects. This advice is aimed mostly at junior devs - especially those new to open source. If you're more experienced, what I have to say probably won't be very interesting to you. Whoever you are, if there's an open-source project you just know you'd love to become closely involved with but don't know where to start, I recommend doing these four things: Offer to do tiny, longstanding chores.</li> Study the code and take notes.</li> Ask questions in code reviews.</li> Attempt ambitious projects and refactors.</li> </ol> Tackle Tiny Chores</h2> Starting small is the most obvious approach, and it's a good one. Most projects have a mountain of tiny little chores that no one ever seems to get to. Probably because the more senior contributors are preoccupied with larger problems. Part of why new contributors are valuable to projects is exactly that they can help tackle this backlog (with the other part being that they sometimes grow into senior contributors and help sustain the project). The main thing you will get out of chores (apart from an exercise in self-discipline) is experience with the tooling and process in a low-stakes environment. If you're new to the language, or for example, git</code>, chores are the way to level up your skills until you reach basic proficiency. If you already have basic technical proficiency, it will still teach you about the social conventions and process particular to the community you are joining. Study The Code</h2> If the previous section seemed obvious, this one may not: You should get out a pen and paper (or whatever note-taking app you prefer) and read the entire codebase top-to-bottom like a "Choose Your Own Adventure" novel. Pick an example or some well-isolated top-level logic, and open it in an editor with go-to-definition support. This is the "top" of your call-stack; from there you should trace down all the definitions, reading and annotating as you go, until you reach the "bottom" and your code hits the underplaying API calls. Your goal here is to produce an architectural overview describing all the layers of abstraction you encounter and how they fit together. If you stick at it, you should end up with something like this</a>. I sense some of you may have some concerns... The first thing I want to assure you is you can do this. If you can write code, you can read it. Code comprehension is a skill, and like all skills you can develop it through regular exercise, even if it feels strange at first. The second thing you should know is: there is no substitute. The other things on this list will teach you the tooling and the process, teach you to make good engineering and design decisions, teach you where the codebase is going. But nothing will familiarize you with the codebase as it is like buckling down and reading it. I don't think it's controversial to say that most codebases are poorly documented. Even those that are not tend to lack broad architectural overviews, or cohesive visions of how all the pieces fit together to make the whole. Those diagrams usually exist only in people's minds. If you've only worked on your own projects before, you've gotten those mental models for free. But when you are interacting with code written by others, potentially hundreds or thousands of others, you'll need to spend time to grok (a wonderful term</a> from a horrible book</a>) the existing structure. It won't necessarily happen on its own. Note that you don't have to actually complete your architectural review for it to be a useful exercise. About 20%, or just enough to know how the lower-level API calls relate to the top-level abstraction, is probably enough to get you to where you need to be. Ask Questions In Reviews</h2> Bevy, like some other open source projects, has a community review process</a>. Alice's article lays out how it works, so I'll just pick out the most salient point: Anyone (literally, anyone) can review a PR. GitHub just lets you do it! </blockquote> Now I'll let you in on a little secret: Even if GitHub doesn’t let you hit the "approve" button for your particular project, you can almost always leave comments on open PRs pointing out errors or asking questions. When you're just starting out, my advice is to do this a lot. First, obviously, you've got to read the PR over. Don't leave review comments on PRs you have not read. But, if you followed the advice from the previous section, reading code should already feel natural to you. You will find that code review feels a little different than static architectural analysis: When doing an architectural analysis, all you care about is how things fit together, but when reviewing a PR, you should also be trying to ascertain if it is correct. I'll warn you upfront: checking code for correctness is hard. How hard depends on the domain, but it's always hard. As a new contributor, you are likely to immediately run into code you either don't understand or misunderstand (and which you may therefore incorrectly identify as an issue). This is fine and expected. So what you should do, considering that you may make frequent mistakes, is (a) be polite and (b) ask a lot of clarifying questions. Most of the time, the author will be happy to explain, but sometimes you will actually catch bugs just by asking about confusing bits of code! After all, the confusing bits are the most likely to be wrong. So the project gets additional valuable scrutiny on its PRs, and you essentially get mentored by the author for a bit. As an aside, please try to be mindful of the author's time when following this advice. Ask for additional information, not additional work. Attempt Ambitious Projects</h2> Many new contributors seem to tend naturally to ambitious large-scale improvements, and I can hardly blame them. Ambition is a great motivator, and to some degree is probably selected for in the population of people who are willing to throw themselves at a new project knowing basically nothing. My advice here is to temper your expectations, but to let yourself be ambitious nonetheless. If you're doing the other three things on this list, you're probably going to start developing opinions about and ideas for improving your project's codebase. Follow those feelings... follow them, with the knowledge that your first few big projects are probably not going to make it to completion. Part of becoming a seasoned contributor is, honestly, fighting with big changes, struggling, figuring out why no one else has solved this yet, and walking away. Don't let yourself become discouraged by failure - having to give up on a branch, or deciding you took the wrong approach and needing to start over, or declaring git bankruptcy because your history is out of control - these are all perfectly normal. If worst comes to worst, you can always shelve your idea and come back to it when you've got more experience. I don't want to give you the impression that I'm expecting you to fail every time you pick up a big task. There will be successes too: For me, I'd say about one in every five of my early attempts at big contributions ended up with a merged PR. A 20% success rate is not nothing. For the project that merges them, the unlikely successes are golden eggs. Ambitious PRs are, by definition, important. When someone new steps in and resolves an important bug or feature, that is the best-case scenario for the project: increasing momentum, freeing up other resources down the line, moving the project closer to its goals. It's not just that the important thing got done, it's that none of the other existing contributors had to take time away from their other work to do it. Now What</h2> If I know my audience, I suspect all of you will be doing some of these already, and some of you will be doing all of them. If you're only doing (1), (2), or (3), consider balancing out your approach with the other two: it can keep things fresh and interesting. In my experience, (4) tends to develop more from the other three than a conscious choice. Eventually, you will find: That the chores are no longer a good use of your time.</li> That you need to read up on the code less and less.</li> That your questions reveal more and more issues.</li> That your ambitious projects frequently end in success.</li> </ol> Congratulations, you've become a regular contributor. Hello World 2025-03-08T00:00:00+00:00 Look at that subtle off-white coloring. The tasteful thickness of it. </blockquote> I now have an internet place (a blog). For anyone who may not be aware, a "Blog" is where you play around with graphic design while imagining all the amazing and insightful articles that you will, one day, totally get around to writing. I spent a lot of time making this one look pretty and ensuring it met all the web accessibility guidelines. And by that, I mean I spent a lot of time browsing other websites and stealing stuff. The headers are Vollkorn</a>, the body is Dover Text</a>, the monospace bits are Space Mono</a>. I cribbed the core design language pretty much wholesale from the US Graphics Company</a>. Even the colors are from Tailwind. It's all built using Zola</a> and hosted on Cloudflare Pages</a>. One day, all of those links will be dead, and no one will know what any of that meant. The servers hosting this will be rusting in a backlot somewhere, or maybe they'll have been recycled into aluminum Yetti mugs. This site probably will have gone down long before that. Maybe I'll get fed up with it and take it down, or maybe give up programming entirely and forget it exists. Most likely I'll fail to renew the domain and will have to set it all up again in a year. But for now, we're both here, at the same time, and we can enjoy this internet place together.

Teddy Bear Trash Compactor

I'm Giving A Talk In Boston

Working In Groups

What's Still Hard</h3> Nothing is perfect, and there are still issues with the working group process.</p>

Maybe Try It?</h2> To summarize, we took an existing semi-dysfunctional RFC process and</p>

Become a Regular Contributor

Hello World