DEV Community: Jesse Freeman

I Made A Game In 72 Hours That Uses GitHub Issues To Crowd Source Maps

Jesse Freeman — Thu, 14 Oct 2021 11:20:25 +0000

Space Station 8 is a Micro Platformer created in 72 hours for Ludum Dare 49 based on a game I used to play on my original Macintosh called Spacestation Pheta. Space Station 8 is also heavily inspired by Bitsy and my Fantasy Console, Pixel Vision 8, which I used to create the game.

Unlike some of the other games I've created for game jams like Ludum Dare, there are no pre-made maps at all! Instead, the entire game revolves around a simple map editor, and I invited people to submit their games via a custom GitHub issue. In addition, I use GitHub Actions to automatically build new versions of the game every time I check in new code and update the wiki, which has all the instructions.

In this post, I'll walk you through how the level editor works, how I designed the map files to be easy to share, and some of the tricks I used to leverage GitHub to help crowdsource my game's levels.

Making Maps

The goal of Space Station 8 is to escape before you run out of oxygen. To do that, you will need to navigate the level, find the key, and make it to the exit in time. Each level is self-contained, and you are scored based on your ability to complete it within the amounted time and lives. There are also some prized gems you may want to collect on your way out while avoiding aliens and other deadly obstacles like spikes.

When you first load Space Station 8 up, it loads up the default map. You can immediately begin editing it, or you can drag a spacestation8.png map onto the game and load that up.

Space Station 8 map's should be at least 160 x 132 pixels:

You can also provide a map that is 160 x 152, where the last two rows are the sprites for the map:

Whenever you go to the splash screen, Space Station 5 will automatically create a new map.spacestation8.png for you in your /Levels/ folder:

Version	Path
Windows	C:\Users\UserName\Documents\SpaceStation8\Levels\
MacOS	/Users/UserName/SpaceStation8/Levels/
Linux	/Users/UserName/SpaceStation8/Levels/

Space Station 8 shows you the map editor before you can play a map. The editor has two main areas, the map and the tile picker on the bottom:

The white blinking box in the map area previews where the tile will be drawn. You can move the tile highlighter via a controller's d-pad, the keyboard arrows, or the mouse. By default, the mouse is hidden unless you move it.

You can pick from any of the 20 tiles on the bottom of the screen to draw with. The tile with the white background is the currently selected tile. You'll also see it previewed on the map. Some tiles have a flip or alternative state. This can be used for changing the direction of an enemy or spikes.

Finally, for a map to work, you need three things: a player, a key, and a door. When you start the game, if these things are not present, it will bring you back to the editor. There is no cap on how many players, keys, or doors you can draw on the map, but the game will only use the first of each when it processes all the tiles.

Submitting Maps With GitHub Issues

Once you are happy with a map, you can share it with someone else by sending them the map.spacestation8.png file. There are several ways to do this. You can attach it in a comment on the game's page, send it directly to them, or file a ticket on GitHub and include it there.

One thing to note is that some social networks like Twitter may compress the image. This will break the tilemap parser unless the image is pixel-perfect at 160 x 132 or 160 x 142.

The default map template looks like this:

As you can see, a map is comprised of a 20 x 17 tile grid where each tile is 8 x 8 pixels. The top row is ignored, and for map images that are 142 pixels high, the last two rows (18 and 19) are used for the game's sprites.

There are 40 sprites which you can also modify if you want to re-skin the game. Each sprite is fixed to a corresponding element in the game, so while you can re-skin the graphics, you will not make new ones or change the internal sprite mapping.

The last thing to keep in mind when modifying the sprites, or even using drawing tools like Aseprite to modify map files, is that you will have to use the following four colors (#2D1B2E, #574B67, #937AC5, #F9F4EA) .

Finally, I use some custom GitHub issues to make filing bugs, requesting features. If you are unfamiliar with the GitHub issue templates, they live inside your project's .github/ISSUE_TEMPLATE folder.

The first thing I needed to do was clean up my project's issue categories to match up with the templates I used.

Finally, I created a new_map.md file with the following markdown inside:

---
name: Submit New Map
about: Did you create a level that you'd like to have included with the source code?
title: ''"
labels: map
assignees: jessefreeman
---

**Who Created the level**
Name: Jesse Freeman
Website: https://jessefreeman.com
Twitter: [@jessefreeman](https://twitter.com/jessefreeman)

**Screenshots**
Attach your map png, [add screenshots from PV8](https://docs.pixelvision8.com/pixelvisionos/screenshots) to be included in the game.

**Additional information**
Add any other context or screenshots about the map you'd like to share.

The markdown frontmatter directly maps to the issue form, and you can use it to automatically assign a label and whom the issues should go to on the project's team.

Here is what the new issue looks like when someone wants to submit a new issue:

Now, I can go through each map and decide if I want to include it in the project or not. While I could have done this with pull requests, the thinking behind using an issue is that others can see the map before adding to the game and leaving comments.

Automated Release With GitHub Actions

In addition to creating custom issues, I use GitHub actions to automatically create new builds of my game whenever I push new code to the repo. I set this up early on in the game jam and having a simple continuous integration build system removed all the stress at the end of the game jam because I point people to the latest build, and it's always up-to-date by directing them to SpaceStation8/releases/latest/.

When I finished the game jam, I added a link to the last build, tag v1.17.0, for a snapshot of the state of the game so I could continue to make improvements after the jam.

I'll write a more in-depth article on how I use GitHub Actions, but at a high level, you need to create a specific folder in your repo, .github/workflows/ and put your yml file inside.

I was already using Gulp to package up my game anyway, so I made an action that does the following:

Creates a new release and tag ( actions/create-release@v1 )
Checks out my code on Ubuntu ( actions/checkout@v2 )
Create a changelog ( jimschubert/beast-changelog-action@v1 )
Install .net 5 ( actions/setup-dotnet@v1 )
Install NodeJS and call my Gulp build task ( actions/setup-node@v1 )
Upload the zipped Win, Mac, and Linus build artifacts to the release ( meeDamian/github-release@2.0 )
Update the wiki ( OrlovM/Wiki-Action@v1 )

It sounds like a lot of steps, but once you get used to working with Gulp and GitHub Actions, the process to orchestrate all of this is relatively straightforward.

Next Steps

I took a break from working on my game to recharge, and I have plans to build a more robust level editor, clean up all the bugs I'm seeing from the maps people are submitting, and add some new features to make this micro platformer engine a bit more modular.

I encourage you to think outside of the box and leverage all of these fantastic free, open-source tools and services to speed up your development. I don't know many people that would take half a day out of a game jam to build a CI system, but I've had too many last-minute panic attacks where my game won't build, or I can't upload it because the jam site is slammed by everyone else trying to upload their game at the same time.

If you like this project, please leave a 👍 and ⭐️ on Github. Don't forget to create a level and submit it because I plan on adding a way to browse, load, and edit other people's maps in the next major update I release!

Open Sourcing My Tools For Generating Tutorials From Source Code

Jesse Freeman — Tue, 12 Oct 2021 19:40:18 +0000

I have been working on my game engine, Pixel Vision 8, for the better part of 6 years now. One of the challenges of working on any sizeable open source project is writing all the documentation and tutorials. I've always been fascinated with designing automated build systems, and it occurred to me that I could create a tool to help me streamline this entire process. The idea was straightforward, could I analyze a code file and break it down into individual steps?

I started using Google Apps Script to automate converting Google Docs to generate markdown for PV8's Github wiki. I was having so much success with this workflow that I created a course for LinkedIn Learning called Google Apps Script for JavaScript Developers. Then I took the JS code out and put it into Atom as a plugin to do the tutorial generation in real-time. But last weekend, I packaged up the core logic and uploaded it to NPM. I named this project Tutorial Writer, and now it works with any NodeJS build system I would want to use.

Tutorial Writer is still more of a POC than a fully-fledged tool. While I continue to clean it up and add more features, I thought I'd walk through some of the logic that powers it. Let's start by looking at the following Lua script:

-- This is a local variable
local total = 0

-- Here is a function
function Init()

     -- Here is a generic block of code
     table.insert(tileIDs, index)

end

Using Tutorial Writer is straightforward. Once you install it from NPM like so:

> npm i tutorial-writer

You just need to reference the package and pass it the contents of a Lua file:

const tutorialWriter = require('../index');
const fs = require('fs');

let filePath = "./examples/code.lua"

let text = fs.readFileSync(filePath, 'utf8');

let markdown = tutorialWriter.toMarkdown("code.lua", text, tutorialWriter.luaTemplate);

console.log("# Tutorial Writer Markdown\n", markdown);

Tutorial Writer is going to take the script and convert it into a step by step tutorial in markdown like this:

Step 1

Create a new file called code.lua in your project folder.

Step 2

Create a new local variable called total inside the script:

01 local total = 0

This is a local variable

Step 3

Create a new function called Init():

02 function Init()
03 
04 end

Here is a function

Step 4

Add the following code to the Init() function:

03      table.insert(tileIDs, index)

Here is a generic block of code

Final Code

When you are done, you should have the following code in the code.lua file:

01 local total = 0
02 function Init()
03      table.insert(tileIDs, index)
04 end

Pretty cool, right? Now let's walk through how Tutorial Writer actually works. If you want to see the full potential of Tutorial Writer, be sure to check out my Pixel Vision 8 HashNode account, where I'm working on posting 50+ tutorials created from the API examples.

If you look at the sample Lua code above, you may notice it's formatted in a unique way. Each piece of code is on its own line, and above it is a comment. Let's look at the original code example and step through it, code block by code block.

So we have three blocks of code here: a variable, a function, and some generic code that triggers something to happen. To keep the parser simple, I only look for a few common types of code blocks:

Variables
Functions
Comments
Conditions
Loops
Generic Code

I'm currently in the process of making Tutorial Writer more modular. Ideally, it should support different rules to parse something like C#, which my game engine also supports. For now, Lua is easier to discuss, so let's talk about how Tutorial Writer breaks down the code.

The first step is to split up all of the code based on the empty lines in the file. Each code group is converted into a code block object, which I can process later. Here are the 4 code blocks Tutorial Writer sees:

Block 1

-- This is a local variable
local total = 0

Block 2

-- Here is a function
function Init()

Block 3

          -- Here is a generic block of code
          table.insert(tileIDs, index)

Block 4

end

Once we have each code block, the parser can loop through them and convert them into a step in the final tutorial. When I ask a code block to return markdown, it loops through each line and determines what kind of code it contains. Here's how block 1 is parsed.

There are two lines in this code block:

Line 1

-- This is a local variable

Line 2

local total = 0

I have a set of regex patterns I use to determine what's in each line. Here are some of the patterns I search for:

Variable: /(local)+\s+(\w+)/
Function: /(function|\s)+\s+(\w+) *\([^\)]*\)/
Condition: /if/
Loop: /for/
Else: /else/
BlockEnd: /end/

Determining if a line is a comment is easy because I just need to test the first two characters to see if they start with --. If there is a comment in the code block, I simply pull that line out and save it for later. Then, based on the regex test, I assign a type to the entire code block and move on to the next one.

If a block of code has a comment, that becomes the instructions at the bottom of the step. You can have any number of comments above a block of code as long as there are no empty lines between them. If the parser encounters a comment not attached to a code block, it's converted into a blockquote in markdown by adding > in front of each line.

Now that the block of code has been assigned a type of variable, we need to look up the step template to convert it into markdown. I have another object that contains templates for each code type. Here are a few that I use for Lua:

Code: Add the following code to the {0}:
Condition: Add the following condition to the {0}:
Loop: Create the following Loop:
Function: Create a new {0} called {1}():
Variable: Create a new {0} variable called {1}{2}:

Now that I have the step template, I analyze the variable's line to try and determine its scope. In Lua, I simply search for local since global is a bit more challenging to determine. Here is what the final markdown will look like since step one is always reserved for creating the code file itself:

Step 2

Create a new local variable called total inside the script:

01 local total = 0

This is a local variable

You'll notice I also assign the code a line number. The old programming books I read in the 80s heavily inspired this feature in Tutorial Writer. In these books, you'd have pages of code to type out with line numbers, so you didn't lose your place. Later on, this number plays an important role when I combine all of the steps back into the final step that presents all the code at once.

Each code block is responsible for determining what line it belongs on, and I have to do some unique things behind the scenes to make sure the numbers are correct and increment at the right place, especially when nested in other blocks of code.

Now we can look at block 2, which is a bit different because it's a function that has an opening and a close. In Lua, closing a statement requires an end which you can see in block 4, but the parser isn't aware of it yet. When a block of code that requires an ending is encountered, the parser automatically adds 2 lines to the code block, an empty line, and the close statement like so:

Step 3

Create a new function called Init():

02 function Init()
03 
04 end

Here is a function

The parser also sets a flag that it is now inside of a function, so when it encounters the following code block, it will reference the name of the function the code is being added to like so:

Step 4

Add the following code to the Init() function:

03      table.insert(tileIDs, index)

Here is a generic block of code

Notice how the line was changed to 3 even though the previous code block ended at 4. This is because the parser knows it's inside of a function and steps back a line to make sure you add the code inside of it correctly.

The last thing the parser needs to handle is the remaining end statement. Since this has been accounted for already in the function code block, it can just be ignored.

At this point, the parser is done and needs to generate the final code, which looks something like this:

Final Code

When you are done, you should have the following code in the code.lua file:

01 local total = 0
02 function Init()
03      table.insert(tileIDs, index)
04 end

And there you have it, a completely automated way of converting code into a step-by-step tutorial. While I originally wrote this to help me create scripts for my LinkedIn learning courses, it's evolved into something powerful enough to do complete tutorials that most developers wouldn't even know were generated by a script. Even better, it forces me to write clean, well-documented code as a byproduct of formatting things in a way that the parser can read.

While this is still a simple POC, I have plans to continue to build upon it and see how far I can take it.

If you like this project, please leave a ❤️ and ⭐️ on Github. I'd love to help developers just getting started with technical writing and looking to share their work with others by simply automating the entire process!