Contributing to Excalibur

This is a submission for the 2024 Hacktoberfest Writing challenge: Contributor Experience

For Hacktoberfest, I created a new Graphic module, called a Nine-Slice, in Excalibur.js. I've spent a couple weeks ironing out the details of the code, proving it out, writing tests, and documenting this contribution. I am going to shed some light on that journey.

I've spent the past couple years using the Excalibur.js game engine to create my games. It has also served as my introduction into contributing to open source projects. We will cover the how and why of contributing to open source projects in this article.

The why behind my contribution

For this contribution, through using the tools in a recent game coding competition, I was in need of a new Graphic type for my game entry. Need being the mother of all innovation, I took a few moments to prototype up a rough component to use in my game, and it was successful. That led me to the belief that others may need something like this so I decided to share it with the community. This demonstrates how new features can be derived by using the tools in their current form and feeling out the opportunity to improve them.

What is the contribution

The Nine-Slice Graphic component is an extension of the standard Graphics library available in Excalibur. This component can allow for a Graphic to be created of any dimensions with a fixed input texture. The component breaks the texture down into 9 separate elements, then redraws the returned graphic to the new dimensions. This allows for users of the component to draw larger graphics without needing to create additional assets.

Let's say your input sprite looks like this:

Well, the 9-slice technique will break up your image into 9 sections, like this:

With the component, you can adjust the margins of the slice boundaries to control how the components are broken up into different pieces.

With these nine pieces, one can create new Graphic images in different dimensions, like this:

The contribution process

After the game coding competition, I cloned a copy of the Excalibur.js repo and created a new local branch. I took my prototype code and refactored it for clarity, so others could easily understand what was happening, including all exported methods, types, and enumerations.

I went to the the discord server for Excalibur and opened up a post in their game dev forum regarding the contribution. This let people review the context of the submission and weigh in on clarity and easy of understanding.

Testing

As is normal with other projects, new features should be accompanied with their own set of unit tests to ensure code quality. This gave me the opportunity to work with Karma, a test runner library for the JS language. I was not really familiar with this library, as I usually use Vitest. But through the documentation and assistance from the community I was able to write enough tests to properly cover my code submission. A big help was looking at other components in the Excalibur project as a guiding template for how the testing could be constructed.

Documentation

Excalibur.js uses docusaurus in their project that allows for markdown files to be displayed. I created a new document page in markdown to explain the usage and configuration of this new graphic so the new docs could be seamlessly integrated into the current documentation scheme of Excalibur.js. Also, quick examples with sample code were provided to improve any onboarding of new users.

Community Engagement

So with the changed source, the updated documents, and the additional unit tests, I submitted the pull request for the change. Then I went back to the discord server to have some discussions and reviews of the changes. There was a lot of good dialogue and ideas on how things could be improved, including a refactoring of the configuration types that allowed for the removal of some //@ts-ignore that I had forgotten to clean up along the way. Other eyes on the documentation led to some iteration of some diagrams to improve clarity.

Conclusion

This is the largest contribution I've made to the core Excalibur code base. I learned a ton over the process of creating the new module, refactoring it for others consumption, writing documentation, and finally the unit tests needed to ensure quality. It feels good to be able to improve the project, and also to give back to a community that has helped me substantially in the past couple years.

For me personally, it helps squash the imposter syndrome that tends to develop when activities like this prove to my self that I am more than capable of making a difference in an open source project. I hope anecdotes like this can help anyone out there that is wondering if they can contribute to projects they enjoy. I strongly urge people to try and get started today! Get Started!!!

About me

I'm a hobbyist developer that has been enamored with game development. I've competed in game jams and coding competitions, and I've really enjoyed engaging with the Excalibur.js community and working with the code base. Come drop me a note!

I'm on twitter at jyoung424242.

My itch.io page: Mookie4242

About Excalibur

ExcaliburJS is a friendly, TypeScript 2D game engine that can produce games for the web. It is free and open source (FOSS), well documented, and has a growing, healthy community of gamedevs working with it and supporting each other. There is a great discord channel for it JOIN HERE, for questions and inquiries. Check it out!!!